Class: Grizzled::FileUtil::Includer

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Grizzled::Forwarder
Defined in:
lib/grizzled/fileutil/includer.rb

Overview

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Grizzled::Forwarder

#forward_to

Constructor Details

#initialize(source, options = {}) ⇒ Includer

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“(+)”



139
140
141
142
143
144
145
146
147
148
 
# File 'lib/grizzled/fileutil/includer.rb', line 139

def initialize(source, options={})
  @max_nesting = options.fetch(:max_nesting, 100)
  inc_pattern = options.fetch(:include_pattern, '^%include\s"([^"]+)"')
  @include_re = /#{inc_pattern}/
  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

Instance Attribute Details

#max_nesting ⇒ Object (readonly)

Returns the value of attribute max_nesting.



120
121
122
 
# File 'lib/grizzled/fileutil/includer.rb', line 120

def max_nesting
  @max_nesting
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



120
121
122
 
# File 'lib/grizzled/fileutil/includer.rb', line 120

def name
  @name
end

Instance Method Details

#close ⇒ Object

Force the underlying resource to be closed.



158
159
160
161
 
# File 'lib/grizzled/fileutil/includer.rb', line 158

def close
  @input.close
  @temp.unlink
end

#do_read(input, temp, level) ⇒ Object 



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/grizzled/fileutil/includer.rb', line 179

def do_read(input, temp, level)
  input.reader.each_line do |line|
    if m = @include_re.match(line)
      if level >= @max_nesting
        raise IncludeException.new("Too many nested includes " +
                                   "(#{level.to_s}), at: " +
                                   "\"#{line.chomp}\"")
      end
      new_input = process_include(m[1], input)
      do_read(new_input, temp, level + 1)
    else
      temp.write(line)
    end
  end
end

#path ⇒ Object

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.



153
154
155
 
# File 'lib/grizzled/fileutil/includer.rb', line 153

def path
  @source_uri.path
end