Class: Kramdown::Parser::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/kramdown/parser/base.rb

Overview

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!

Direct Known Subclasses

Html, Kramdown

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source, options) ⇒ Base

Initialize the parser object with the source string and the parsing options.

The @root element, the @warnings array and @text_type (specifies the default type for newly created text nodes) are automatically initialized.



51
52
53
54
55
56
57
 
# File 'lib/kramdown/parser/base.rb', line 51

def initialize(source, options)
  @source = source
  @options = Kramdown::Options.merge(options)
  @root = Element.new(:root, nil, nil, :encoding => (source.encoding rescue nil), :location => 1)
  @warnings = []
  @text_type = :text
end

Instance Attribute Details

#options ⇒ Object (readonly)

The hash with the parsing options.



36
37
38
 
# File 'lib/kramdown/parser/base.rb', line 36

def options
  @options
end

#root ⇒ Object (readonly)

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



45
46
47
 
# File 'lib/kramdown/parser/base.rb', line 45

def root
  @root
end

#source ⇒ Object (readonly)

The original source string.



42
43
44
 
# File 'lib/kramdown/parser/base.rb', line 42

def source
  @source
end

#warnings ⇒ Object (readonly)

The array with the parser warnings.



39
40
41
 
# File 'lib/kramdown/parser/base.rb', line 39

def warnings
  @warnings
end

Class Method Details

.parse(source, options = {}) ⇒ Object

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.



65
66
67
68
69
 
# File 'lib/kramdown/parser/base.rb', line 65

def self.parse(source, options = {})
  parser = new(source, options)
  parser.parse
  [parser.root, parser.warnings]
end

Instance Method Details

#adapt_source(source) ⇒ Object

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



89
90
91
92
93
94
95
 
# File 'lib/kramdown/parser/base.rb', line 89

def adapt_source(source)
  if source.respond_to?(:encode)
    raise "The encoding of the source text is not valid!" if !source.valid_encoding?
    source = source.encode('UTF-8')
  end
  source.gsub(/\r\n?/, "\n").chomp + "\n"
end

#add_text(text, tree = @tree, type = @text_type) ⇒ Object

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.



99
100
101
102
103
104
105
106
 
# File 'lib/kramdown/parser/base.rb', line 99

def add_text(text, tree = @tree, type = @text_type)
  last = tree.children.last
  if last && last.type == type
    last.value << text
  elsif !text.empty?
    tree.children << Element.new(type, text, nil, :location => (last && last.options[:location] || tree.options[:location]))
  end
end

#extract_string(range, strscan) ⇒ Object

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.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/kramdown/parser/base.rb', line 110

def extract_string(range, strscan)
  result = nil
  if strscan.string.respond_to?(:encoding)
    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
  else
    result = strscan.string[range]
  end
  result
end

#parse ⇒ Object

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!

Raises:

  • (NotImplementedError) 


77
78
79
 
# File 'lib/kramdown/parser/base.rb', line 77

def parse
  raise NotImplementedError
end

#warning(text) ⇒ Object

Add the given warning text to the warning array.



82
83
84
85
 
# File 'lib/kramdown/parser/base.rb', line 82

def warning(text)
  @warnings << text
  #TODO: add position information
end