class Grizzled::FileUtil::Includer

Introduction ↑

An Includer object preprocesses a text file, resolve include references. The Includer is an Enumerable, allowing iteration over the lines of the resulting expanded file.

Include 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 matches include directives

like this

%include “/absolute/path/to/file” %include “../relative/path/to/file” %include “local_reference” %include “localhost/path/to/my.config”

Relative and local file references are relative to the including file or URL. That, 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 “localhost/bmc/foo.txt” and encounters an attempt to include file “bar.txt”, it will assume “bar.txt” is to be found at “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 class constructor.

Supported Methods ↑

Includer supports all the methods of the File class and can be used the same way as a File object is used.

Examples ↑

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

require 'grizzled/fileutil/includer'
include Grizzled::FileUtil

inc = Includer.new(path)
inc.each do |line|
  puts(line)
end

Attributes

max_nesting[R]
name[R]

Public Class Methods

new(source, options={}) click to toggle source

Initialize a new Includer.

Parameters:

source

A string, representing a file name or URL (http, https or ftp), a File object, or an object with an each_line method that returns individual lines of input.

options

Various processing options. See below.

Options:

*NOTE*: Options are symbols (e.g., :recursive).

#max_nesting

Maximum include nesting level. Default: 100

include_pattern

String regex pattern to match include directives. Must have a single regex group for the file name or URL. Default: ^%includes“(+)”

allow_glob

For file names, allow and expand glob expressions. Doesn't apply to URLs.

# File lib/grizzled/fileutil/includer.rb, line 177
def initialize(source, options={})
  @max_nesting = options.fetch(:max_nesting, 100)
  inc_pattern = options.fetch(:include_pattern, '^%include\s"([^"]+)"')
  @include_re = /#{inc_pattern}/
  @allow_glob = options.fetch(:allow_glob, false)
  includer_source = source_to_includer_source source
  @source_uri = includer_source.uri
  @temp = preprocess includer_source
  @input = File.open @temp.path
  forward_to @input
end

Public Instance Methods

close() click to toggle source

Force the underlying resource to be closed.

# File lib/grizzled/fileutil/includer.rb, line 197
def close
  @input.close
  @temp.unlink
end
path() click to toggle source

Return the path of the original include file, if defined. If the original source was a URL, the URL is returned. If the source was a string, nil is returned.

# File lib/grizzled/fileutil/includer.rb, line 192
def path
  @source_uri.path
end