Class | Asciidoctor::Reader |
In: |
lib/asciidoctor/reader.rb
|
Parent: | Object |
Public: Methods for retrieving lines from AsciiDoc source files
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: 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: 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: 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"]
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.
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.
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'