webgen 0.5.17 → 1.0.0.beta1

data/lib/webgen/content_processor.rb

@@ -0,0 +1,160 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/extension_manager'
+require 'webgen/error'
+
+module Webgen
+
+  # 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'
+  #
+  class ContentProcessor
+
+    include Webgen::ExtensionManager
+
+    # 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
+    #
+    def register(klass, options={}, &block)
+      name = do_register(klass, options, true, &block)
+      ext_data(name).type = options[:type] || :text
+      ext_data(name).extension_map = options[:ext_map] || {}
+    end
+
+    # Call the content processor object identified by the given name with the given context.
+    def call(name, context)
+      extension(name).call(context)
+    rescue Webgen::Error => e
+      e.path = context.dest_node if e.path.to_s.empty?
+      raise
+    rescue Exception => e
+      ext = extension(name)
+      raise Webgen::RenderError.new(e, (ext.respond_to?(:name) ? ext.name : nil), context.dest_node)
+    end
+
+    # 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 processors a, b and c.
+    #
+    # Raises an error if an unknown content processor is found.
+    #
+    # Returns an array with valid content processors.
+    def normalize_pipeline(pipeline)
+      pipeline = (pipeline.kind_of?(String) ? pipeline.split(/,\s*/) : pipeline)
+      pipeline.each do |processor|
+        raise Webgen::Error.new("Unknown content processor '#{processor}'") if !registered?(processor)
+      end
+      pipeline
+    end
+
+    # Return whether the content processor is processing binary data.
+    def is_binary?(name)
+      registered?(name) && ext_data(name).type == :binary
+    end
+
+    # 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.
+    def extension_map(name = nil)
+      if name.nil?
+        @extension_map ||= registered_extensions.inject({}) {|hash, data| hash.update(data.last.extension_map)}
+      elsif registered?(name)
+        ext_data(name).extension_map
+      else
+        {}
+      end
+    end
+
+    # Return the content processor name and the mapped extension of a pre-processed file extension
+    # or +nil+ if the extension cannot be mapped.
+    def map_extension(ext)
+      registered_extensions.each do |name, data|
+        mapped_ext = data.extension_map[ext]
+        return [name, mapped_ext] if mapped_ext
+      end
+      nil
+    end
+
+  end
+
+end

data/lib/webgen/content_processor/blocks.rb

@@ -0,0 +1,96 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+require 'webgen/error'
+
+module Webgen
+  class ContentProcessor
+
+    # Replaces special XML tags with the rendered content of a node block.
+    #
+    # The module provides a ::call method so that it can be used by the content processor extension.
+    # However, it also provides the ::render_block method that contains the actual logic for
+    # rendering a block of a node given a render context.
+    module Blocks
+
+      BLOCK_RE = /<webgen:block\s*?((?:\s\w+=('|")[^'"]+\2)+)\s*\/>/ # :nodoc:
+      BLOCK_ATTR_RE = /(\w+)=('|")([^'"]+)\2/ # :nodoc:
+
+      # Replace the webgen:block xml tags with the rendered content of the specified node.
+      def self.call(context)
+        context.content.gsub!(BLOCK_RE) do |match|
+          attr = {}
+          match_object = $~
+          attr[:line_nr_proc] = lambda { match_object.pre_match.scan("\n").size + 1 }
+          match.scan(BLOCK_ATTR_RE) {|name, sep, content| attr[name.to_sym] = content}
+          render_block(context, attr)
+        end
+        context
+      end
+
+      # Render a block of a page node and return the result.
+      #
+      # The Webgen::Context object +context+ is used as the render context and the +options+ hash
+      # needs to hold all relevant information, that is:
+      #
+      # [:name (mandatory)]
+      #   The name of the block that should be used.
+      #
+      # [:chain]
+      #   The node chain used for rendering. If this is not specified, the node chain from the
+      #   context is used. It needs to be a String in the format '(A)LCN;(A)LCN;...' or an array of
+      #   nodes.
+      #
+      # [:node]
+      #   Defines which node in the node chain should be used. Valid values are +next+ (= default
+      #   value; the next node in the node chain), +first+ (the first node in the node chain with a
+      #   block called +name+) or +current+ (the currently rendered node, ignores the +chain+ option).
+      #
+      # [:notfound]
+      #   If this property is set to +ignore+, a missing block will not raise an error. It is unset by
+      #   default, so missing blocks will raise errors.
+      #
+      def self.render_block(context, options)
+        if options[:chain].nil?
+          used_chain = (context[:chain].length > 1 ? context[:chain][1..-1] : context[:chain].dup)
+        elsif options[:chain].kind_of?(Array)
+          used_chain = options[:chain]
+          dest_node = context.dest_node
+        else
+          paths = options[:chain].split(';')
+          used_chain = paths.collect do |path|
+            context.ref_node.resolve(path.strip, context.dest_node.lang, true)
+          end.compact
+          return '' if used_chain.length != paths.length
+          dest_node = context.dest_node
+        end
+
+        if options[:node] == 'first'
+          used_chain.shift while used_chain.length > 0 && !used_chain.first.blocks.has_key?(options[:name])
+        elsif options[:node] == 'current'
+          used_chain = context[:chain].dup
+        end
+        block_node = used_chain.first
+
+        if !block_node || !block_node.blocks.has_key?(options[:name])
+          if options[:notfound] == 'ignore'
+            return ''
+          elsif block_node
+            raise Webgen::RenderError.new("No block named '#{options[:name]}' found in <#{block_node}>",
+                                          self.name, context.dest_node,
+                                          context.ref_node, (options[:line_nr_proc].call if options[:line_nr_proc]))
+          else
+            raise Webgen::RenderError.new("No node in the render chain has a block named '#{options[:name]}'",
+                                          self.name, context.dest_node,
+                                          context.ref_node, (options[:line_nr_proc].call if options[:line_nr_proc]))
+          end
+        end
+
+        tmp_context = block_node.render_block(options[:name], context.clone(:chain => used_chain, :dest_node => dest_node))
+        tmp_context.content
+      end
+
+    end
+
+  end
+end

data/lib/webgen/content_processor/builder.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+webgen_require 'builder'
+
+module Webgen
+  class ContentProcessor
+
+    # Processes content that is valid Ruby to build an XML tree. This is done by using the +builder+
+    # library.
+    module Builder
+
+      # Process the content of +context+ which needs to be valid Ruby code. The special variable +xml+
+      # should be used to construct the XML content.
+      def self.call(context)
+        xml = ::Builder::XmlMarkup.new(:indent => 2)
+        eval(context.content, binding, context.ref_node.alcn)
+        context.content = xml.target!
+        context
+      end
+
+    end
+
+  end
+end

data/lib/webgen/content_processor/erb.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+require 'erb'
+
+module Webgen
+  class ContentProcessor
+
+    # Processes embedded Ruby statements.
+    module Erb
+
+      extend ERB::Util
+
+      # Process the Ruby statements embedded in the content of +context+.
+      def self.call(context)
+        erb = ERB.new(context.content)
+        erb.filename = context.ref_node.alcn
+        context.content = erb.result(binding)
+        context
+      end
+
+    end
+
+  end
+end

data/lib/webgen/content_processor/erubis.rb

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+webgen_require 'erubis'
+
+module Webgen
+  class ContentProcessor
+
+    # Processes embedded Ruby statements with the +erubis+ library.
+    module Erubis
+
+      # Including Erubis because of problem with resolving Erubis::XmlHelper et al
+      include ::Erubis
+
+      # Process the Ruby statements embedded in the content of +context+.
+      def self.call(context)
+        options = context.website.config['content_processor.erubis.options']
+        erubis = if context.website.config['content_processor.erubis.use_pi']
+                   ::Erubis::PI::Eruby.new(context.content, options)
+                 else
+                   ::Erubis::Eruby.new(context.content, options)
+                 end
+        erubis.filename = context.ref_node.alcn
+        context.content = erubis.result(binding)
+        context
+      end
+
+    end
+
+  end
+end

data/lib/webgen/content_processor/fragments.rb

@@ -0,0 +1,82 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+require 'webgen/path'
+
+module Webgen
+  class ContentProcessor
+
+    # Uses the HTML headers h1, h2, ..., h6 (only those with valid IDs) to generate nested fragment
+    # nodes.
+    module Fragments
+
+      # Create the nested fragment nodes from the content under the content node but only if there
+      # is no associated block or the block is named +content+.
+      def self.call(context)
+        if !context[:block_name] || context[:block_name] == 'content'
+          sections = parse_html_headers(context.content)
+          create_fragment_nodes(context, sections, context.content_node)
+        end
+        context
+      end
+
+      HTML_HEADER_REGEXP = /<h([123456])(?:>|\s([^>]*)>)(.*?)<\/h\1\s*>/i
+      HTML_ATTR_REGEXP = /\s*(\w+)\s*=\s*('|")(.+?)\2\s*/
+
+      # Parse the string +content+ for headers +h1+, ..., +h6+ and return the found, nested
+      # sections.
+      #
+      # Only those headers are used which have an +id+ attribute set. The method returns a list of
+      # arrays with entries 'level, id, title, sub sections' where 'sub sections' is such a list
+      # again.
+      def self.parse_html_headers(content)
+        sections = []
+        stack = []
+        content.scan(HTML_HEADER_REGEXP).each do |level,attrs,title|
+          next if attrs.nil?
+          id_attr = attrs.scan(HTML_ATTR_REGEXP).find {|name,sep,value| name == 'id'}
+          next if id_attr.nil?
+          id = id_attr[2]
+
+          section = [level.to_i, id, title, []]
+          success = false
+          while !success
+            if stack.empty?
+              sections << section
+              stack << section
+              success = true
+            elsif stack.last.first < section.first
+              stack.last.last << section
+              stack << section
+              success = true
+            else
+              stack.pop
+            end
+          end
+        end
+        sections
+      end
+
+      # Create nested fragment nodes under +parent+ from +sections+ (which can be created using
+      # #parse_html_headers).
+      #
+      # The meta info +sort_info+ is calculated from the base +si+ value.
+      def self.create_fragment_nodes(context, sections, parent, si = 1000)
+        sections.each do |level, id, title, sub_sections|
+          path = Webgen::Path.new(parent.alcn.sub(/#.*$/, '') + '#' + id)
+          path['parent_alcn'] = parent.alcn
+          path['handler'] = 'copy'
+          path['pipeline'] = []
+          path['no_output'] = true
+          path['title'] = title
+          path['sort_info'] = si = si.succ
+          node = context.website.ext.path_handler.create_secondary_nodes(path, '', context.content_node.alcn).first
+
+          create_fragment_nodes(context, sub_sections, node, si.succ)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/webgen/content_processor/haml.rb

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/content_processor'
+webgen_require 'haml'
+
+module Webgen
+  class ContentProcessor
+
+    # Processes content in Haml markup using the +haml+ library.
+    module Haml
+
+      # Convert the content in +haml+ markup to HTML.
+      def self.call(context)
+        context.content = ::Haml::Engine.new(context.content, :filename => context.ref_node.alcn).
+          render(Object.new, :context => context)
+        context
+      rescue ::Haml::Error => e
+        line = (e.line ? e.line + 1 : Webgen::Error.error_line(e))
+        raise Webgen::RenderError.new(e, self.class.name, context.dest_node, nil, line)
+      end
+
+    end
+
+  end
+end