class Kramdown::Parser::Base

Base class for parsers

This class serves as base class for parsers. It provides common methods that can/should be used by all parsers, especially by those using StringScanner(Kramdown) for parsing.

A parser object is used as a throw-away object, i.e. it is only used for storing the needed state information during parsing. Therefore one can’t instantiate a parser object directly but only use the Base::parse method.

Implementing a parser

Implementing a new parser is rather easy: just derive a new class from this class and put it in the Kramdown::Parser module – the latter is needed so that the auto-detection of the new parser works correctly. Then you need to implement the parse method which has to contain the parsing code.

Have a look at the Base::parse, Base::new and Base#parse methods for additional information!

Attributes

options [R]

The hash with the parsing options.

root [R]

The root element of element tree that is created from the source string.

source [R]

The original source string.

warnings [R]

The array with the parser warnings.

Public Class Methods

parse (source, options = {})

Source

# File lib/kramdown/parser/base.rb, line 72
def self.parse(source, options = {})
  parser = new(source, options)
  parser.parse
  [parser.root, parser.warnings]
end

Parse the source string into an element tree, possibly using the parsing options, and return the root element of the element tree and an array with warning messages.

Initializes a new instance of the calling class and then calls the parse method that must be implemented by each subclass.

Public Instance Methods

adapt_source (source)

Source

# File lib/kramdown/parser/base.rb, line 96
def adapt_source(source)
  unless source.valid_encoding?
    raise "The source text contains invalid characters for the used encoding #{source.encoding}"
  end
  source = source.encode('UTF-8')
  source.gsub!(/\r\n?/, "\n")
  source.chomp!
  source << "\n"
end

Modify the string source to be usable by the parser (unifies line ending characters to \n and makes sure source ends with a new line character).

add_text (text, tree = @tree, type = @text_type)

Source

# File lib/kramdown/parser/base.rb, line 108
def add_text(text, tree = @tree, type = @text_type)
  last = tree.children.last
  if last && last.type == type
    last.value << text
  elsif !text.empty?
    location = (last && last.options[:location] || tree.options[:location])
    tree.children << Element.new(type, text, nil, location: location)
  end
end

This helper method adds the given text either to the last element in the tree if it is a type element or creates a new text element with the given type.

extract_string (range, strscan)

Source

# File lib/kramdown/parser/base.rb, line 120
def extract_string(range, strscan)
  result = nil
  begin
    enc = strscan.string.encoding
    strscan.string.force_encoding('ASCII-8BIT')
    result = strscan.string[range].force_encoding(enc)
  ensure
    strscan.string.force_encoding(enc)
  end
  result
end

Extract the part of the StringScanner strscan backed string specified by the range. This method works correctly under Ruby 1.8 and Ruby 1.9.

parse ()

Source

# File lib/kramdown/parser/base.rb, line 84
def parse
  raise NotImplementedError
end

Parse the source string into an element tree.

The parsing code should parse the source provided in @source and build an element tree the root of which should be @root.

This is the only method that has to be implemented by sub-classes!

warning (text)

Source

# File lib/kramdown/parser/base.rb, line 89
def warning(text)
  @warnings << text
  # TODO: add position information
end

Add the given warning text to the warning array.