gettalong-webgen 0.5.4.20080929

data/lib/webgen/contentprocessor.rb

@@ -0,0 +1,96 @@
+module Webgen
+
+  # Namespace for all content processors.
+  #
+  # = Implementing a content processor
+  #
+  # Content processors are used to process the content of files, normally of files in Webgen Page
+  # Format. A content processor only needs to respond to one method called +call+ and must not take
+  # any parameters in the +initialize+ method. This method is invoked with a
+  # Webgen::ContentProcessor::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.
+  #
+  # A self-written content processor does not need to be in the Webgen::ContentProcessor namespace
+  # but all shipped ones do.
+  #
+  # After writing the content processor class, one needs to add it to the
+  # <tt>contentprocessor.map</tt> hash so that it is used by webgen. The key for the entry needs to
+  # be a short name without special characters or spaces and the value is the class name, not as
+  # constant but as a string.
+  #
+  # = Sample Content Processor
+  #
+  # The following sample content processor checks for a meta information +replace_key+ and replaces
+  # strings of the form <tt>replace_key:path/to/node</tt> 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 sothat the
+  # correct meta information is used, the node is correctly resolved and the correct relative link
+  # is calculated respectively!
+  #
+  #   class SampleProcessor
+  #
+  #     def 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, :lang => context.content_node.lang)
+  #           else
+  #             match
+  #           end
+  #         end
+  #       end
+  #       context
+  #     rescue Exception => e
+  #       raise "Error while replacing special key: #{e.message}"
+  #     end
+  #
+  #   end
+  #
+  #   WebsiteAccess.website.config['contentprocessor.map']['replacer'] = 'SampleProcessor'
+  #
+  module ContentProcessor
+
+    autoload :Context, 'webgen/contentprocessor/context'
+    autoload :Tags, 'webgen/contentprocessor/tags'
+    autoload :Blocks, 'webgen/contentprocessor/blocks'
+    autoload :Maruku, 'webgen/contentprocessor/maruku'
+    autoload :RedCloth, 'webgen/contentprocessor/redcloth'
+    autoload :Erb, 'webgen/contentprocessor/erb'
+    autoload :Haml, 'webgen/contentprocessor/haml'
+    autoload :Sass, 'webgen/contentprocessor/sass'
+    autoload :RDoc, 'webgen/contentprocessor/rdoc'
+    autoload :Builder, 'webgen/contentprocessor/builder'
+    autoload :Erubis, 'webgen/contentprocessor/erubis'
+    autoload :RDiscount, 'webgen/contentprocessor/rdiscount'
+
+    # Return the list of all available content processors.
+    def self.list
+      WebsiteAccess.website.config['contentprocessor.map'].keys
+    end
+
+    # Return the content processor object identified by +name+.
+    def self.for_name(name)
+      klass = WebsiteAccess.website.config['contentprocessor.map'][name]
+      klass.nil? ? nil : WebsiteAccess.website.cache.instance(klass)
+    end
+
+    # Helper class for accessing content processors in a Webgen::ContentProcessor::Context object.
+    class AccessHash
+
+      # Check if a content processor called +name+ exists.
+      def has_key?(name)
+        Webgen::ContentProcessor.list.include?(name)
+      end
+
+      # Return (and proboably initialize) the content processor called +name+.
+      def [](name)
+        Webgen::ContentProcessor.for_name(name)
+      end
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/blocks.rb

@@ -0,0 +1,46 @@
+require 'webgen/loggable'
+
+module Webgen::ContentProcessor
+
+  # Replaces special xml tags with the rendered content of a node.
+  class Blocks
+
+    include Webgen::Loggable
+
+    BLOCK_RE = /<webgen:block\s+name=('|")(\w+)\1\s*(?:\schain=('|")([^'"]+)\3\s*)?\s*\/>/
+
+    # Replace that webgen:block xml tags with the rendered content of a node.
+    def call(context)
+      chain = context[:chain]
+      new_chain = (chain.length > 1 ? chain[1..-1] : chain)
+
+      context.content.gsub!(BLOCK_RE) do |match|
+        block_name = $2
+        if $4.nil?
+          used_chain = new_chain
+        else
+          paths = $4.split(';')
+          used_chain = paths.collect do |path|
+            temp_node = context.ref_node.resolve(path.strip, context.dest_node.lang)
+            log(:error) { "Could not resolve <#{path.strip}> in <#{context.ref_node.absolute_lcn}> in '#{match.to_s}'" } if temp_node.nil?
+            temp_node
+          end.compact
+          next match if used_chain.length != paths.length
+          dest_node = context.content_node
+        end
+        block_node = used_chain.first
+
+        if !block_node.node_info[:page].blocks.has_key?(block_name)
+          raise "Node <#{block_node.absolute_lcn}> has no block named '#{block_name}'"
+        end
+
+        context.dest_node.node_info[:used_nodes] << block_node.absolute_lcn
+        tmp_context = block_node.node_info[:page].blocks[block_name].render(context.clone(:chain => used_chain, :dest_node => dest_node))
+        tmp_context.content
+      end
+      context
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/builder.rb

@@ -0,0 +1,26 @@
+module Webgen::ContentProcessor
+
+  # Processes content that is valid Ruby to build an XML tree. This is done by using the +builder+
+  # library.
+  class 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 call(context)
+      require 'builder'
+
+      node = context.content_node
+      ref_node = context.ref_node
+      dest_node = context.dest_node
+
+      xml = ::Builder::XmlMarkup.new(:indent => 2)
+      eval(context.content, binding, context.ref_node.absolute_lcn)
+      context.content = xml.target!
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error using Builder in <#{context.ref_node.absolute_lcn}> to generate XML: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/context.rb

@@ -0,0 +1,90 @@
+require 'webgen/contentprocessor'
+require 'webgen/websiteaccess'
+
+module Webgen::ContentProcessor
+
+  # The context object that is passed to the +call+ method of a content processor.
+  #
+  # The needed context variables are stored in the +options+ hash. You can set any options you like,
+  # however, there are three noteworthy options:
+  #
+  # <tt>:content</tt>:: The content string that should be processed.
+  # <tt>:processors</tt>:: Normally an AccessHash object providing access to all available content processors.
+  # <tt>:chain</tt>:: The chain of nodes that is processed. There are some utiltity methods for getting
+  #                   special nodes of the chain (see #ref_node, #content_node).
+  class Context
+
+    include Webgen::WebsiteAccess
+    public :website
+
+    # Processing options
+    attr_accessor :options
+
+    # Create a new Context object. You can use the +options+ hash to set needed options. The
+    # <tt>:content</tt> option is set to an empty string if not specified in +options+ and
+    # <tt>:processors</tt> is set to a new AccessHash if not specified in +options+.
+    def initialize(options = {})
+      @options = {
+        :content => '',
+        :processors => Webgen::ContentProcessor::AccessHash.new
+      }.merge(options)
+    end
+
+    # Create a copy of the current object. You can use the +options+ parameter to override options
+    # of the current Context object in the newly created Context object.
+    def clone(options = {})
+      self.class.new(@options.merge(options))
+    end
+
+    # Return the value of the option +name+.
+    def [](name)
+      @options[name]
+    end
+
+    # Set the option +name+ to the given +value.
+    def []=(name, value)
+      @options[name] = value
+    end
+
+    # Return the <tt>:content</tt> option.
+    def content
+      @options[:content]
+    end
+
+    # Set the <tt>:content</tt> option to the given +value+.
+    def content=(value)
+      @options[:content] = value
+    end
+
+    # Return the node which represents the file into which everything gets rendered. This is
+    # normally the same node as <tt>#content_node</tt> but can differ in special cases. For example,
+    # when rendering the content of node called <tt>my.page</tt> into the output of the node
+    # <tt>this.page</tt>, <tt>this.page</tt> would be the +dest_node+ and <tt>my.page</tt> would be
+    # the +content_node+.
+    #
+    # The +dest_node+ is not included in the chain but can be set via the option
+    # <tt>:dest_node</tt>!
+    #
+    # The returned node should be used as source node for calculating relative paths to other nodes.
+    def dest_node
+      @options[:dest_node] || self.content_node
+    end
+
+    # Return the reference node, ie. the node which provided the original content for this context
+    # object.
+    #
+    # The returned node should be used, for example, for resolving relative paths.
+    def ref_node
+      @options[:chain] && @options[:chain].first
+    end
+
+    # Return the node that is ultimately rendered.
+    #
+    # This node should be used, for example, for retrieving meta information.
+    def content_node
+      @options[:chain] && @options[:chain].last
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/erb.rb

@@ -0,0 +1,24 @@
+module Webgen::ContentProcessor
+
+  # Processes embedded Ruby statements.
+  class Erb
+
+    # Process the Ruby statements embedded in the content of +context+.
+    def call(context)
+      require 'erb'
+
+      node = context.content_node
+      ref_node = context.ref_node
+      dest_node = context.dest_node
+
+      erb = ERB.new(context.content)
+      erb.filename = context.ref_node.absolute_lcn
+      context.content = erb.result(binding)
+      context
+    rescue Exception => e
+      raise RuntimeError, "Erb processing failed in <#{context.ref_node.absolute_lcn}>: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/erubis.rb

@@ -0,0 +1,40 @@
+require 'webgen/websiteaccess'
+
+module Webgen::ContentProcessor
+
+  # Processes embedded Ruby statements with the +erubis+ library.
+  class Erubis
+
+    include Webgen::WebsiteAccess
+
+    # Process the Ruby statements embedded in the content of +context+.
+    def call(context)
+      require 'erubis'
+      # including Erubis because of problem with resolving Erubis::XmlHelper et al
+      self.class.class_eval "include ::Erubis"
+
+      node = context.content_node
+      ref_node = context.ref_node
+      dest_node = context.dest_node
+
+      options = website.config['contentprocessor.erubis.options']
+      if context[:block]
+        use_pi = context[:block].options['erubis_use_pi']
+        context[:block].options.select {|k,v| k =~ /^erubis_/}.
+          each {|k,v| options[k.sub(/^erubis_/, '').to_sym] = v }
+      end
+      erubis = if (!use_pi.nil? && use_pi) || (use_pi.nil? && website.config['contentprocessor.erubis.use_pi'])
+                    ::Erubis::PI::Eruby.new(context.content, options)
+                  else
+                    ::Erubis::Eruby.new(context.content, options)
+                  end
+      erubis.filename = context.ref_node.absolute_lcn
+      context.content = erubis.result(binding)
+      context
+    rescue Exception => e
+      raise RuntimeError, "Erubis processing failed in <#{context.ref_node.absolute_lcn}>: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/haml.rb

@@ -0,0 +1,25 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Haml markup using the +haml+ library.
+  class Haml
+
+    # Convert the content in +haml+ markup to HTML.
+    def call(context)
+      require 'haml'
+
+      locals = {
+        :context => context,
+        :node => context.content_node,
+        :ref_node => context.ref_node,
+        :dest_node => context.dest_node,
+      }
+      context.content = ::Haml::Engine.new(context.content, :filename => context.ref_node.absolute_lcn).
+        render(Object.new, locals)
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error converting Haml markup to HTML in <#{context.ref_node.absolute_lcn}>: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/maruku.rb

@@ -0,0 +1,18 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Markdown format using the +maruku+ library.
+  class Maruku
+
+    # Convert the content in +context+ to HTML.
+    def call(context)
+      require 'maruku'
+      $uid = 0 #fix for invalid fragment ids on second run
+      context.content = ::Maruku.new(context.content, :on_error => :raise).to_html
+      context
+    rescue Exception => e
+      raise RuntimeError, "Maruku to HTML conversion failed for <#{context.ref_node.absolute_lcn}>: #{e.message}", e.backtrace
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/rdiscount.rb

@@ -0,0 +1,15 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Markdown markup with the fast +rdiscount+ library.
+  class RDiscount
+
+    # Convert the content in +context+ to HTML.
+    def call(context)
+      require 'rdiscount'
+      context.content = ::RDiscount.new(context.content).to_html
+      context
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/rdoc.rb

@@ -0,0 +1,17 @@
+module Webgen::ContentProcessor
+
+  # Converts content in RDoc markup (the native Ruby documentation format) to HTML. Needs the newer
+  # RDoc implementation provided as +rdoc+ gem!
+  class RDoc
+
+    # Convert the content in RDoc markup to HTML.
+    def call(context)
+      require 'rdoc/markup/to_html'
+
+      context.content = ::RDoc::Markup::ToHtml.new.convert(context.content)
+      context
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/redcloth.rb

@@ -0,0 +1,15 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Textile format using the +redcloth+ library.
+  class RedCloth
+
+    # Convert the content in +context+ to HTML.
+    def call(context)
+      require 'redcloth'
+      context.content = ::RedCloth.new(context.content).to_html
+      context
+    end
+
+  end
+
+end

data/lib/webgen/contentprocessor/sass.rb

@@ -0,0 +1,18 @@
+module Webgen::ContentProcessor
+
+  # Processes content in Sass markup (used for writing CSS files) using the +haml+ library.
+  class Sass
+
+    # Convert the content in +sass+ markup to CSS.
+    def call(context)
+      require 'sass'
+
+      context.content = ::Sass::Engine.new(context.content, :filename => context.ref_node.absolute_lcn).render
+      context
+    rescue Exception => e
+      raise RuntimeError, "Error converting Sass markup to CSS in <#{context.ref_node.absolute_lcn}>: #{e.message}", e.backtrace
+    end
+
+  end
+
+end