class Kramdown::Converter::Base

Base class for converters

This class serves as base class for all converters. It provides methods that can/should be used by all converters (like generate_id) as well as common functionality that is automatically applied to the result (for example, embedding the output into a template).

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

Implementing a converter

Implementing a new converter is rather easy: just derive a new class from this class and put it in the Kramdown::Converter module (the latter is only needed if auto-detection should work properly). Then you need to implement the convert method which has to contain the conversion code for converting an element and has to return the conversion result.

The actual transformation of the document tree can be done in any way. However, writing one method per element type is a straight forward way to do it - this is how the Html and Latex converters do the transformation.

Have a look at the Base::convert method for additional information!

Attributes

data[R]

Can be used by a converter for storing arbitrary information during the conversion process.

options[R]

The hash with the conversion options.

root[R]

The root element that is converted.

warnings[R]

The warnings array.

Public Class Methods

convert(tree, options = {}) click to toggle source

Convert the element tree tree and return the resulting conversion object (normally a string) and an array with warning messages. The parameter options specifies the conversion options that should be used.

Initializes a new instance of the calling class and then calls the convert method with tree as parameter.

If the template option is specified and non-empty, the template is evaluate with ERB before and/or after the tree conversion depending on the result of apply_template_before? and apply_template_after?. If the template is evaluated before, an empty string is used for the body; if evaluated after, the result is used as body. See ::apply_template.

The template resolution is done in the following way (for the converter ConverterName):

  1. Look in the current working directory for the template.

  2. Append .converter_name (e.g. .html) to the template name and look for the resulting file in the current working directory (the form .convertername is deprecated).

  3. Append .converter_name to the template name and look for it in the kramdown data directory (the form .convertername is deprecated).

  4. Check if the template name starts with ‘string://’ and if so, strip this prefix away and use the rest as template.

    # File lib/kramdown/converter/base.rb
100 def self.convert(tree, options = {})
101   converter = new(tree, ::Kramdown::Options.merge(options.merge(tree.options[:options] || {})))
102 
103   if !converter.options[:template].empty? && converter.apply_template_before?
104     apply_template(converter, '')
105   end
106   result = converter.convert(tree)
107   if result.respond_to?(:encode!) && result.encoding != Encoding::BINARY
108     result.encode!(tree.options[:encoding] ||
109                    (raise ::Kramdown::Error, "Missing encoding option on root element"))
110   end
111   if !converter.options[:template].empty? && converter.apply_template_after?
112     result = apply_template(converter, result)
113   end
114 
115   [result, converter.warnings]
116 end

Private Class Methods

new(root, options) click to toggle source

Initialize the converter with the given root element and options hash.

   # File lib/kramdown/converter/base.rb
54 def initialize(root, options)
55   @options = options
56   @root = root
57   @data = {}
58   @warnings = []
59 end

Public Instance Methods

apply_template_after?() click to toggle source

Returns whether the template should be applied after the conversion of the tree.

Defaults to true.

   # File lib/kramdown/converter/base.rb
72 def apply_template_after?
73   true
74 end
apply_template_before?() click to toggle source

Returns whether the template should be applied before the conversion of the tree.

Defaults to false.

   # File lib/kramdown/converter/base.rb
65 def apply_template_before?
66   false
67 end
basic_generate_id(str) click to toggle source

The basic version of the ID generator, without any special provisions for empty or unique IDs.

    # File lib/kramdown/converter/base.rb
236 def basic_generate_id(str)
237   gen_id = str.gsub(/^[^a-zA-Z]+/, '')
238   gen_id.tr!('^a-zA-Z0-9 -', '')
239   gen_id.tr!(' ', '-')
240   gen_id.downcase!
241   gen_id
242 end
convert(_el) click to toggle source

Convert the element el and return the resulting object.

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

    # File lib/kramdown/converter/base.rb
121 def convert(_el)
122   raise NotImplementedError
123 end
extract_code_language(attr) click to toggle source

Extract the code block/span language from the attributes.

    # File lib/kramdown/converter/base.rb
173 def extract_code_language(attr)
174   if attr['class'] && attr['class'] =~ /\blanguage-\S+/
175     attr['class'].scan(/\blanguage-(\S+)/).first.first
176   end
177 end
extract_code_language!(attr) click to toggle source

See extract_code_language

Warning: This version will modify the given attributes if a language is present.

    # File lib/kramdown/converter/base.rb
182 def extract_code_language!(attr)
183   lang = extract_code_language(attr)
184   attr['class'] = attr['class'].sub(/\blanguage-\S+/, '').strip if lang
185   attr.delete('class') if lang && attr['class'].empty?
186   lang
187 end
format_math(el, opts = {}) click to toggle source

Format the given math element with the math engine configured through the option ‘math_engine’.

    # File lib/kramdown/converter/base.rb
205 def format_math(el, opts = {})
206   return nil unless @options[:math_engine]
207 
208   engine = ::Kramdown::Converter.math_engine(@options[:math_engine])
209   if engine
210     engine.call(self, el, opts)
211   else
212     warning("The configured math engine #{@options[:math_engine]} is not available.")
213     nil
214   end
215 end
generate_id(str) click to toggle source

Generate an unique alpha-numeric ID from the the string str for use as a header ID.

Uses the option auto_id_prefix: the value of this option is prepended to every generated ID.

    # File lib/kramdown/converter/base.rb
221 def generate_id(str)
222   str = ::Kramdown::Utils::Unidecoder.decode(str) if @options[:transliterated_header_ids]
223   gen_id = basic_generate_id(str)
224   gen_id = 'section' if gen_id.empty?
225   @used_ids ||= {}
226   if @used_ids.key?(gen_id)
227     gen_id += "-#{@used_ids[gen_id] += 1}"
228   else
229     @used_ids[gen_id] = 0
230   end
231   @options[:auto_id_prefix] + gen_id
232 end
highlight_code(text, lang, type, opts = {}) click to toggle source

Highlight the given text in the language lang with the syntax highlighter configured through the option ‘syntax_highlighter’.

    # File lib/kramdown/converter/base.rb
191 def highlight_code(text, lang, type, opts = {})
192   return nil unless @options[:syntax_highlighter]
193 
194   highlighter = ::Kramdown::Converter.syntax_highlighter(@options[:syntax_highlighter])
195   if highlighter
196     highlighter.call(self, text, lang, type, opts)
197   else
198     warning("The configured syntax highlighter #{@options[:syntax_highlighter]} is not available.")
199     nil
200   end
201 end
in_toc?(el) click to toggle source

Return true if the header element el should be used for the table of contents (as specified by the toc_levels option).

    # File lib/kramdown/converter/base.rb
161 def in_toc?(el)
162   @options[:toc_levels].include?(el.options[:level]) && (el.attr['class'] || '') !~ /\bno_toc\b/
163 end
output_header_level(level) click to toggle source

Return the output header level given a level.

Uses the header_offset option for adjusting the header level.

    # File lib/kramdown/converter/base.rb
168 def output_header_level(level)
169   [[level + @options[:header_offset], 6].min, 1].max
170 end
smart_quote_entity(el) click to toggle source

Return the entity that represents the given smart_quote element.

    # File lib/kramdown/converter/base.rb
247 def smart_quote_entity(el)
248   res = @options[:smart_quotes][SMART_QUOTE_INDICES[el.value]]
249   ::Kramdown::Utils::Entities.entity(res)
250 end
warning(text) click to toggle source

Add the given warning text to the warning array.

    # File lib/kramdown/converter/base.rb
155 def warning(text)
156   @warnings << text
157 end