Object
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 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!
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):
Look in the current working directory for the template.
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).
Append .converter_name to the template name and look for it in the kramdown data directory (the form .convertername is deprecated).
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, line 99 def self.convert(tree, options = {}) converter = new(tree, ::Kramdown::Options.merge(options.merge(tree.options[:options] || {}))) apply_template(converter, '') if !converter.options[:template].empty? && converter.apply_template_before? result = converter.convert(tree) result.encode!(tree.options[:encoding]) if result.respond_to?(:encode!) && result.encoding != Encoding::BINARY result = apply_template(converter, result) if !converter.options[:template].empty? && converter.apply_template_after? [result, converter.warnings] end
Return the template specified by template.
# File lib/kramdown/converter/base.rb, line 130 def self.get_template(template) #DEPRECATED: use content of #get_template_new in 2.0 format_ext = '.' + self.name.split(/::/).last.downcase shipped = File.join(::Kramdown.data_dir, template + format_ext) if File.exist?(template) File.read(template) elsif File.exist?(template + format_ext) File.read(template + format_ext) elsif File.exist?(shipped) File.read(shipped) elsif template.start_with?('string://') template.sub(/\Astring:\/\//, '') else get_template_new(template) end end
Returns whether the template should be applied ater the conversion of the tree.
Defaults to true.
# File lib/kramdown/converter/base.rb, line 71 def apply_template_after? true end
Returns whether the template should be applied before the conversion of the tree.
Defaults to false.
# File lib/kramdown/converter/base.rb, line 64 def apply_template_before? false end
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, line 113 def convert(el) raise NotImplementedError end
Extract the code block/span language from the attributes.
# File lib/kramdown/converter/base.rb, line 182 def extract_code_language(attr) if attr['class'] && attr['class'] =~ /\blanguage-\w+\b/ attr['class'].scan(/\blanguage-(\w+)\b/).first.first end end
Warning: This version will modify the given attributes if a language is present.
# File lib/kramdown/converter/base.rb, line 191 def extract_code_language!(attr) lang = extract_code_language(attr) attr['class'] = attr['class'].sub(/\blanguage-\w+\b/, '').strip if lang attr.delete('class') if lang && attr['class'].empty? lang end
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, line 202 def generate_id(str) str = ::Kramdown::Utils::Unidecoder.decode(str) if @options[:transliterated_header_ids] gen_id = str.gsub(/^[^a-zA-Z]+/, '') gen_id.tr!('^a-zA-Z0-9 -', '') gen_id.tr!(' ', '-') gen_id.downcase! gen_id = 'section' if gen_id.length == 0 @used_ids ||= {} if @used_ids.has_key?(gen_id) gen_id += '-' << (@used_ids[gen_id] += 1).to_s else @used_ids[gen_id] = 0 end @options[:auto_id_prefix] + gen_id end
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, line 170 def in_toc?(el) @options[:toc_levels].include?(el.options[:level]) && (el.attr['class'] || '') !~ /\bno_toc\b/ end
Return the output header level given a level.
Uses the header_offset option for adjusting the header level.
# File lib/kramdown/converter/base.rb, line 177 def output_header_level(level) [[level + @options[:header_offset], 6].min, 1].max end
Generated with the Darkfish Rdoc Generator 2.