Process "include" directives in files, returning an iterator over lines from the flattened files.

The grizzled.file.Includer class can be used to process "include" directives within a text file, returning a file-like object. It also contains some utility functions that permit using include-enabled files in other contexts.

WARNING: This class is not thread-safe.

Syntax

The include syntax is defined by a regular expression; any line that matches the regular expression is treated as an include directive. The default regular expression, %include\s"(["]+)"$ matches include directives like this:

%include "/absolute/path/to/file"
%include "../relative/path/to/file"
%include "local_reference"
%include "http://localhost/path/to/my.config"

Relative and local file references are relative to the including file or URL. That is, if an Includer is processing file "/home/bmc/foo.txt" and encounters an attempt to include file "bar.txt", it will assume "bar.txt" is to be found in "/home/bmc".

Similarly, if an Includer is processing URL "http://localhost/bmc/foo.txt" and encounters an attempt to include file "bar.txt", it will assume "bar.txt" is to be found at "http://localhost/bmc/bar.txt".

Nested includes are permitted; that is, an included file may, itself, include other files. The maximum recursion level is configurable and defaults to 100.

The include syntax can be changed by passing a different regular expression to the Includer constructor.

Usage

This package provides an Includer class, which processes include directives in a file and behaves somewhat like a Scala Source. See the class documentation for more details.

The package also provides a preprocess() convenience function, via a companion object, that can be used to preprocess a file; it returns the path to the resulting preprocessed file.

Examples

Preprocess a file containing include directives, then read the result:

import grizzled.file.Includer

Includer(path).foreach(println(_))

Use an include-enabled file with a Scala scala.io.Source object:

import grizzled.file.includer.Includer
import scala.io.Source

val source = Source.fromFile(Includer.preprocess("/path/to/file"))