Class Asciidoctor::Reader
In: lib/asciidoctor/reader.rb
Parent: Object

Public: Methods for retrieving lines from AsciiDoc source files

Methods

Attributes

lineno  [R]  Public: Get the 1-based offset of the current line.
source  [R]  Public: Get the document source as a String Array of lines.

Public Class methods

Public: Initialize the Reader object.

data - The Array of Strings holding the Asciidoc source document. The

             original instance of this Array is not modified (default: nil)

document - The document with which this reader is associated. Used to access

             document attributes (default: nil)

preprocess - A flag indicating whether to run the preprocessor on these lines.

             Only enable for the outer-most Reader. If this argument is true,
             a Document object must also be supplied.
             (default: false)

block - A block that can be used to retrieve external Asciidoc

             data to include in this document.

Examples

  data   = File.readlines(filename)
  reader = Asciidoctor::Reader.new data

Public Instance methods

Public: Advance to the next line by discarding the line at the front of the stack

Removes the line at the front of the stack without any processing.

returns a boolean indicating whether there was a line to discard

Public: Chomp the String on the last line if this reader contains at least one line

Delegates to chomp!

Returns nil

Public: Consume consecutive lines containing line- or block-level comments.

Returns the Array of lines that were consumed

Examples

  @lines
  => ["// foo\n", "////\n", "foo bar\n", "////\n", "actual text\n"]

  comment_lines = consume_comments
  => ["// foo\n", "////\n", "foo bar\n", "////\n"]

  @lines
  => ["actual text\n"]

Public: Consume consecutive lines containing line comments.

Returns the Array of lines that were consumed

Examples

  @lines
  => ["// foo\n", "bar\n"]

  comment_lines = consume_comments
  => ["// foo\n"]

  @lines
  => ["bar\n"]

Public: Check whether this reader is empty (contains no lines)

If preprocessing is enabled for this Reader, and there are lines remaining, the next line is preprocessed before checking whether there are more lines.

Returns true if @lines is empty, otherwise false.

Public: Get the next line of source data. Consumes the line returned.

preprocess - A Boolean flag indicating whether to evaluate preprocessing

             directives (macros) before reading line (default: true)

Returns the String of the next line of the source data if data is present. Returns nil if there is no more data.

Public: Return all the lines from `@lines` until we (1) run out them,

  (2) find a blank line with :break_on_blank_lines => true, or (3) find
  a line for which the given block evals to true.

options - an optional Hash of processing options:

          * :break_on_blank_lines may be used to specify to break on
              blank lines
          * :skip_first_line may be used to tell the reader to advance
              beyond the first line before beginning the scan
          * :preserve_last_line may be used to specify that the String
              causing the method to stop processing lines should be
              pushed back onto the `lines` Array.
          * :grab_last_line may be used to specify that the String
              causing the method to stop processing lines should be
              included in the lines being returned

Returns the Array of lines forming the next segment.

Examples

  reader = Reader.new ["First paragraph\n", "Second paragraph\n",
                       "Open block\n", "\n", "Can have blank lines\n",
                       "--\n", "\n", "In a different segment\n"]

  reader.grab_lines_until
  => ["First paragraph\n", "Second paragraph\n", "Open block\n"]

Public: Check whether there are any lines left to read.

If preprocessing is enabled for this Reader, and there are lines remaining, the next line is preprocessed before checking whether there are more lines.

Returns true if @lines is empty, or false otherwise.

Public: Get a copy of the remaining Array of String lines parsed from the source

Private: Normalize raw input, used for the outermost Reader.

This method strips whitespace from the end of every line of the source data and appends a LF (i.e., Unix endline). This whitespace substitution is very important to how Asciidoctor works.

Any leading or trailing blank lines are also removed.

The normalized lines are assigned to the @lines instance variable.

data - A String Array of input data to be normalized

returns nothing

 Private: Normalize raw input read from an include directive

 This method strips whitespace from the end of every line of
 the source data and appends a LF (i.e., Unix endline). This
 whitespace substitution is very important to how Asciidoctor
 works.

 Any leading or trailing blank lines are also removed. (DISABLED)

 data - A String Array of input data to be normalized

 returns the processed lines

-

 FIXME this shares too much in common w/ normalize_data; combine
 in a shared function

Public: Get the next line of source data. Does not consume the line returned.

preprocess - A Boolean flag indicating whether to evaluate preprocessing

             directives (macros) before reading line (default: true)

Returns a String dup of the next line of the source data if data is present. Returns nil if there is no more data.

TODO document & test me!

Internal: Preprocess the directive (macro) to conditionally include content.

Preprocess the conditional inclusion directive (ifdef, ifndef, ifeval, endif) under the cursor. If the Reader is currently skipping content, then simply track the open and close delimiters of any nested conditional blocks. If the Reader is not skipping, mark whether the condition is satisfied and continue preprocessing recursively until the next line of available content is found.

directive - The conditional inclusion directive (ifdef, ifndef, ifeval, endif) target - The target, which is the name of one or more attributes that are

             used in the condition (blank in the case of the ifeval directive)

delimiter - The conditional delimiter for multiple attributes (’+’ means all

             attributes must be defined or undefined, ',' means any of the attributes
             can be defined or undefined.

text - The text associated with this directive (occurring between the square brackets)

             Used for a single-line conditional block in the case of the ifdef or
             ifndef directives, and for the conditional expression for the ifeval directive.

returns a Boolean indicating whether the cursor advanced, or nil if there are no more lines available.

Internal: Preprocess the directive (macro) to include the target document.

Preprocess the directive to include the target document. The scenarios are as follows:

If SafeMode is SECURE or greater, the directive is ignore and the include directive line is emitted verbatim.

Otherwise, if an include handler is specified (currently controlled by a closure block), pass the target to that block and expect an Array of String lines in return.

Otherwise, if the include-depth attribute is greater than 0, normalize the target path and read the lines onto the beginning of the Array of source data.

If none of the above apply, emit the include directive line verbatim.

target - The name of the source document to include as specified in the

         target slot of the include::[] macro

returns a Boolean indicating whether the line under the cursor has changed.

Internal: Preprocess the next line until the cursor is at a line of content

Evaluate preprocessor macros on the next line, continuing to do so until the cursor arrives at a line of included content. That line is marked as preprocessed so that preprocessing is not performed multiple times.

returns a Boolean indicating whether the cursor advanced, or nil if there are no more lines available.

Private: Resolve the value of one side of the expression

Public: Convert a string to a legal attribute name.

name - The String holding the Asciidoc attribute name.

Returns a String with the legal name.

Examples

  sanitize_attribute_name('Foo Bar')
  => 'foobar'

  sanitize_attribute_name('foo')
  => 'foo'

  sanitize_attribute_name('Foo 3 #-Billy')
  => 'foo3-billy'

Private: Strip off leading blank lines in the Array of lines.

Examples

  @lines
  => ["\n", "\t\n", "Foo\n", "Bar\n", "\n"]

  skip_blank_lines
  => 2

  @lines
  => ["Foo\n", "Bar\n"]

Returns an Integer of the number of lines skipped

skip_comment_lines(options = {})

Alias for consume_comments

Public: Push Array of lines onto the front of the Array of source data, unless `lines` has no non-nil values.

Returns nil

Public: Push the String line onto the beginning of the Array of source data.

Since this line was (assumed to be) previously retrieved through the reader, it is marked as preprocessed.

returns nil

[Validate]