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

Public: Methods for retrieving lines from AsciiDoc source files

Methods

Classes and Modules

Class Asciidoctor::Reader::Cursor

Attributes

dir  [R] 
file  [R] 
lineno  [R]  Public: Get the 1-based offset of the current line.
path  [R] 
process_lines  [RW]  Public: Control whether lines are processed using Reader#process_line on first visit (default: true)
source_lines  [R]  Public: Get the document source as a String Array of lines.

Public Class methods

Public Instance methods

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

direct - A Boolean flag to bypasses the check for more lines and immediately

          returns the first element of the internal @lines Array. (default: true)

Returns a Boolean indicating whether there was a line to discard.

empty?()

Alias for eof?

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

Returns true if there are no more lines to peek, otherwise false.

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

If a previous call to this method resulted in a value of false, immediately returned the cached value. Otherwise, delegate to peek_line to determine if there is a next line available.

Returns True if there are more lines, False if there are not.

Public: Get information about the last line read, including file name and line number.

Returns A String summary of the last line read

Public: Get a copy of the remaining Array of String lines managed by this Reader

Returns A copy of the String Array of lines remaining in this Reader

Public: Peek at the next line and check if it‘s empty (i.e., whitespace only)

This method Does not consume the line from the stack.

Returns True if the there are no more lines or if the next line is empty

next_line_info()

Alias for line_info

Public: Peek at the next line of source data. Processes the line, if not already marked as processed, but does not consume it.

This method will probe the reader for more lines. If there is a next line that has not previously been visited, the line is passed to the Reader#process_line method to be initialized. This call gives sub-classess the opportunity to do preprocessing. If the return value of the Reader#process_line is nil, the data is assumed to be changed and Reader#peek_line is invoked again to perform further processing.

direct - A Boolean flag to bypasses the check for more lines and immediately

          returns the first element of the internal @lines Array. (default: false)

Returns the next line of the source data as a String if there are lines remaining. Returns nothing if there is no more data.

Public: Peek at the next multiple lines of source data. Processes the lines, if not already marked as processed, but does not consume them.

This method delegates to Reader#read_line to process and collect the line, then restores the lines to the stack before returning them. This allows the lines to be processed and marked as such so that subsequent reads will not need to process the lines again.

num - The Integer number of lines to peek. direct - A Boolean indicating whether processing should be disabled when reading lines

Returns A String Array of the next multiple lines of source data, or an empty Array if there are no more lines in this Reader.

Internal: Prepare the lines from the provided data

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.

data - A String Array of input data to be normalized opts - A Hash of options to control what cleansing is done

Returns The String lines extracted from the data

Internal: Processes a previously unvisited line

By default, this method marks the line as processed by incrementing the look_ahead counter and returns the line unmodified.

Returns The String line the Reader should make available to the next invocation of Reader#read_line or nil if the Reader should drop the line, advance to the next line and process it.

Public: Get the remaining lines of source data joined as a String.

Delegates to Reader#read_lines, then joins the result.

Returns the lines read joined as a String

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

direct - A Boolean flag to bypasses the check for more lines and immediately

          returns the first element of the internal @lines Array. (default: false)

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

Public: Get the remaining lines of source data.

This method calls Reader#read_line repeatedly until all lines are consumed and returns the lines as a String Array. This method differs from Reader#lines in that it processes each line in turn, hence triggering any preprocessors implemented in sub-classes.

Returns the lines read as a String Array

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.
          * :read_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

  data = [
    "First line\n",
    "Second line\n",
    "\n",
    "Third line\n",
  ]
  reader = Reader.new data, nil, :normalize => true

  reader.read_lines_until
  => ["First line", "Second line"]
readlines()

Alias for read_lines

replace_line(replacement)

Alias for replace_next_line

Public: Replace the next line with the specified line.

Calls Reader#advance to consume the current line, then calls Reader#unshift to push the replacement onto the top of the line stack.

replacement - The String line to put in place of the next line (i.e., the line at the cursor).

Returns nothing.

restore_line(line_to_restore)

Alias for unshift_line

restore_lines(lines_to_restore)

Alias for unshift_lines

Internal: Shift the line off the stack and increment the lineno

This method can be used directly when you‘ve already called peek_line and determined that you do, in fact, want to pluck that line off the stack.

Returns The String line at the top of the stack

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

Examples

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

  skip_blank_lines
  => 2

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

Returns an Integer of the number of lines skipped

Public: Skip consecutive lines containing line comments and return them.

Examples

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

  comment_lines = skip_comment_lines
  => ["// foo"]

  @lines
  => ["bar"]

Returns the Array of lines that were skipped

Public: Skip consecutive lines that are line comments and return them.

Public: Get the source lines for this Reader joined as a String

Public: Get a copy of the remaining lines managed by this Reader joined as a String

Public: Advance to the end of the reader, consuming all remaining lines

Returns nothing.

Public: Get a summary of this Reader.

Returns A string summary of this reader, which contains the path and line information

Internal: Restore the line to the stack and decrement the lineno

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 seen.

line_to_restore - the line to restore onto the stack

Returns nothing.

Public: Push an Array of lines onto the front of the Array of source data.

Since these lines were (assumed to be) previously retrieved through the reader, they are marked as seen.

Returns nothing.

[Validate]