class Webgen::ContentProcessor

Namespace for all content processors.

About

Content processors are used to process the content of paths, normally of paths in Webgen Page Format. However, they can potentially process any type of content, even binary content.

Implementing a content processor

A content processor only needs to respond to one method called call. This method is invoked with a Webgen::Context object that provides the whole context (especially the content and the node chain) and the method needs to return this object. During processing a content processor normally changes the content of the context but it does not need to.

This allows one to implement a content processor as a class with a class method called call. Or as a Proc object.

The content processor has to be registered so that webgen knows about it, see ContentProcessor.register for more information.

Sample Content Processor

The following sample content processor checks for a meta information replace_key and replaces strings of the form 'replace_key:path/to/node' with a link to the specified node if it is found.

Note how the content node, the reference node and the destination node are used so that the correct meta information is used, the node is correctly resolved and the correct relative link is calculated respectively!

class Replacer

  def self.call(context)
    if !context.content_node['replace_key'].to_s.empty?
      context.content.gsub!(/#{context.content_node['replace_key']}:([\w\/.]+)/ ) do |match|
        link_node = context.ref_node.resolve($1, context.content_node.lang)
        if link_node
          context.dest_node.link_to(link_node, context.content_node.lang)
        else
          match
        end
      end
    end
    context
  rescue Exception => e
    raise "Error while replacing special key: #{e.message}"
  end

end

website.ext.content_processor.register Replacer, :name => 'replacer'

Public Instance Methods

call(name, context) click to toggle source

Call the content processor object identified by the given name with the given context.

    # File lib/webgen/content_processor.rb
102 def call(name, context)
103   extension(name).call(context)
104 rescue Webgen::Error => e
105   e.path = context.dest_node if e.path.to_s.empty?
106   e.location = "content_processor.#{name}" unless e.location
107   raise
108 rescue Exception => e
109   raise Webgen::RenderError.new(e, "content_processor.#{name}", context.dest_node)
110 end
extension_map(name = nil) click to toggle source

Return the mapping of pre-processed file extension names to post-processed file extension names for the given content processor or a combination of all mappings if name is nil.

An empty map is returned if the content processor is not registered.

    # File lib/webgen/content_processor.rb
137 def extension_map(name = nil)
138   if name.nil?
139     @extension_map ||= registered_extensions.inject({}) {|hash, data| hash.update(data.last.extension_map)}
140   elsif registered?(name)
141     ext_data(name).extension_map
142   else
143     {}
144   end
145 end
is_binary?(name) click to toggle source

Return whether the content processor is processing binary data.

    # File lib/webgen/content_processor.rb
129 def is_binary?(name)
130   registered?(name) && ext_data(name).type == :binary
131 end
map_extension(ext) click to toggle source

Return the content processor name and the mapped extension of a pre-processed file extension or nil if the extension cannot be mapped.

    # File lib/webgen/content_processor.rb
149 def map_extension(ext)
150   registered_extensions.each do |name, data|
151     mapped_ext = data.extension_map[ext]
152     return [name, mapped_ext] if mapped_ext
153   end
154   nil
155 end
normalize_pipeline(pipeline) click to toggle source

Normalize the content processor pipeline.

The pipeline parameter can be a String in the format 'a,b,c' or 'a, b, c' or an array '[a, b, c]' with content processor names a, b and c.

Raises an error if an unknown content processor is found.

Returns an array with valid content processors.

    # File lib/webgen/content_processor.rb
120 def normalize_pipeline(pipeline)
121   pipeline = (pipeline.kind_of?(String) ? pipeline.split(/,\s*/) : pipeline.to_a)
122   pipeline.each do |processor|
123     raise Webgen::Error.new("Unknown content processor '#{processor}'") if !registered?(processor)
124   end
125   pipeline
126 end
register(klass, options={}, &block) click to toggle source

Register a content processor.

The parameter klass can either be a String containing the name of a class/module (which has to respond to :call) or an object that responds to :call. If the class is located under this namespace, only the class name without the hierarchy part is needed, otherwise the full class/module name including parent module/class names is needed.

Instead of registering an object that responds to #call, you can also provide a block that has to take one parameter (the context object).

Options:

:name

The name for the content processor. If not set, it defaults to the snake-case version of the class name (without the hierarchy part). It should only contain letters.

:type

Defines which type of content the content processor can process. Can be set to either :text (the default) or :binary.

:ext_map

Defines a mapping of pre-processed file extension names to post-processed file extension names (e.g. {'sass' => 'css'}).

Examples:

content_processor.register('Kramdown')     # registers Webgen::ContentProcessor::Kramdown

content_processor.register('::Kramdown')   # registers Kramdown !!!

content_processor.register('MyModule::Doit', type: :binary)

content_processor.register('doit') do |context|
  context.content = 'Nothing left.'
end
   # File lib/webgen/content_processor.rb
95 def register(klass, options={}, &block)
96   name = do_register(klass, options, true, &block)
97   ext_data(name).type = options[:type] || :text
98   ext_data(name).extension_map = options[:ext_map] || {}
99 end