webgen 0.5.7 → 0.5.8

data/lib/webgen/node.rb

@@ -10,6 +10,13 @@ require 'pathname'
 module Webgen
 
   # Represents a file, a directory or a fragment. A node always belongs to a Tree.
+  #
+  # All needed meta and processing information is associated with a Node. The meta information is
+  # available throught the #[] and #meta_info accessors, the processing information through the
+  # #node_info accessor.
+  #
+  # Although node information should be changed by code, it is not advised to change meta
+  # information values in code since this may lead to unwanted behaviour!
   class Node
 
     include WebsiteAccess
@@ -50,18 +57,18 @@ module Webgen
 
     # Create a new Node instance.
     #
-    # +parent+ (immutable)::
+    # [+parent+ (immutable)]
     #    The parent node under which this nodes should be created.
-    # +path+ (immutable)::
+    # [+path+ (immutable)]
     #    The full output path for this node. If this node is a directory, the path must have a
     #    trailing slash (<tt>dir/</tt>). If it is a fragment, the hash sign must be the first
     #    character of the path (<tt>#fragment</tt>). This can also be an absolute path like
     #    <tt>http://myhost.com/</tt>.
-    # +cn+ (immutable)::
+    # [+cn+ (immutable)]
     #    The canonical name for this node. Needs to be of the form <tt>basename.ext</tt> or
     #    <tt>basename</tt> where +basename+ does not contain any dots. Also, the +basename+ must not
     #    include a language part!
-    # +meta_info+::
+    # [+meta_info+]
     #    A hash with meta information for the new node.
     #
     # The language of a node is taken from the meta information +lang+ and the entry is deleted from
@@ -121,13 +128,13 @@ module Webgen
 
     # Check if the node is flagged with one of the following:
     #
-    # :created:: Has the node been created or has it been read from the cache?
-    # :reinit:: Does the node need to be reinitialized?
-    # :dirty:: Set by other objects to +true+ if they think the object has changed since the last
+    # [:created] Has the node been created or has it been read from the cache?
+    # [:reinit] Does the node need to be reinitialized?
+    # [:dirty] Set by other objects to +true+ if they think the object has changed since the last
     #          run. Must not be set to +false+ once it is +true+!
-    # :dirty_meta_info:: Set by other objects to +true+ if the meta information of the node has
+    # [:dirty_meta_info] Set by other objects to +true+ if the meta information of the node has
     #                    changed since the last run. Must not be set to +false+ once it is +true+!
-    def flagged(key)
+    def flagged?(key)
       @flags.include?(key)
     end
 
@@ -154,10 +161,11 @@ module Webgen
     def changed?
       if_not_checked(:node) do
         flag(:dirty) if meta_info_changed? ||
-          node_info[:used_nodes].any? {|n| n != @absolute_lcn && (!tree[n] || tree[n].changed?)}
-        website.blackboard.dispatch_msg(:node_changed?, self) unless flagged(:dirty)
+          node_info[:used_nodes].any? {|n| n != @absolute_lcn && (!tree[n] || tree[n].changed?)} ||
+          node_info[:used_meta_info_nodes].any? {|n| n != @absolute_lcn && (!tree[n] || tree[n].meta_info_changed?)}
+        website.blackboard.dispatch_msg(:node_changed?, self) unless flagged?(:dirty)
       end
-      flagged(:dirty)
+      flagged?(:dirty)
     end
 
     # Return +true+ if the meta information of the node has changed.
@@ -168,12 +176,9 @@ module Webgen
     # dirty.
     def meta_info_changed?
       if_not_checked(:meta_info) do
-        flag(:dirty_meta_info) if node_info[:used_meta_info_nodes].any? do |n|
-          n != @absolute_lcn && (!tree[n] || tree[n].meta_info_changed?)
-        end
-        website.blackboard.dispatch_msg(:node_meta_info_changed?, self) unless flagged(:dirty_meta_info)
+        website.blackboard.dispatch_msg(:node_meta_info_changed?, self) unless flagged?(:dirty_meta_info)
       end
-      flagged(:dirty_meta_info)
+      flagged?(:dirty_meta_info)
     end
 
     # Return an informative representation of the node.
@@ -199,7 +204,7 @@ module Webgen
     end
 
     # Construct the absolute (localized) canonical name by using the +parent+ node and +name+ (which
-    # can be a cn or an lcn). The +type+ can be either +:alcn+ or +:acn+.
+    # can be a cn or an lcn). The +type+ can be either <tt>:alcn</tt> or <tt>:acn</tt>.
     def self.absolute_name(parent, name, type)
       if parent.kind_of?(Tree)
         ''
@@ -326,7 +331,7 @@ module Webgen
     #
     # If the special value <tt>:lang</tt> is present in the attributes, it will be used as parameter
     # to the <tt>node.routing_node</tt> call for getting the linked-to node instead of this node's
-    # +lang+ attribute. Note: this is only useful when linking to a directory.
+    # +lang+ attribute. *Note*: this is only useful when linking to a directory.
     def link_to(node, attr = {})
       attr = node['link_attrs'].merge(attr) if node['link_attrs'].kind_of?(Hash)
       rnode = node.routing_node(attr[:lang] || @lang)

data/lib/webgen/output.rb

@@ -4,22 +4,65 @@ module Webgen
 
   # Namespace for all classes that know how to write out node content.
   #
-  # = Implementing an output class
+  # == Implementing an output class
   #
   # Output classes know how to write rendered node data to an output location.
   #
   # An output class must respond to three methods
   #
-  # <tt>exists?(path)</tt>::
+  # [<tt>exists?(path)</tt>]
   #   Return +true+ if the output path exists.
-  # <tt>delete(path)</tt>::
+  # [<tt>delete(path)</tt>]
   #   Delete the given output path.
-  # <tt>write(path, data, type)</tt>::
-  #   Write the data to the given output path. The parameter +type+ specifies the type of the
-  #   to be written path: <tt>:file</tt> or <tt>:directory</tt>.
-  # <tt>read(path)</tt>:
+  # [<tt>write(path, data, type)</tt>]
+  #   Write the +data+ to the given output +path+. The parameter +data+ is either a String with the
+  #   content or a Webgen::Path::SourceIO object. The parameter +type+ specifies the type of the to
+  #   be written path: <tt>:file</tt> or <tt>:directory</tt>.
+  # [<tt>read(path)</tt>]
   #   Return the content of the given path if it exists or raise an error otherwise.
   #
+  #   It seems a bit odd that an output instance has to implement reading functionality. However,
+  #   consider the case where you want webgen to render a website programmatically and *use* the
+  #   output. In this case you need a way to get to content of the written files! This functionality
+  #   is used, for example, in the webgui.
+  #
+  # == Sample Output Class
+  #
+  # Following is a simple but actually used (by the webgui) output class which stores the written
+  # nodes in a hash in memory:
+  #
+  #   class MemoryOutput
+  #     include Webgen::WebsiteAccess
+  #
+  #     attr_reader :data
+  #
+  #     def initialize
+  #       @data = {}
+  #     end
+  #
+  #     def exists?(path)
+  #       @data.has_key?(path)
+  #     end
+  #
+  #     def delete(path)
+  #       @data.delete(path)
+  #     end
+  #
+  #     def write(path, io, type = :file)
+  #       @data[path] = [(io.kind_of?(String) ? io : io.data), type]
+  #     end
+  #
+  #     def read(path)
+  #       path = File.join('/', path)
+  #       raise "No such file #{path}" unless @data[path] && @data[path].last == :file
+  #       @data[path].first
+  #     end
+  #   end
+  #
+  #   WebsiteAccess.website.config.output(['MemoryOutput'])
+  #
+  # The last line is used to tell webgen to use this new output class instead of the default one.
+  #
   module Output
 
     autoload :FileSystem, 'webgen/output/filesystem'

data/lib/webgen/page.rb

@@ -4,52 +4,61 @@ require 'yaml'
 
 module Webgen
 
-  # A single block within a Page object. The content of the block can be rendered using the #render method.
-  class Block
+  # A Page object wraps a meta information hash and an array of Block objects. It is normally
+  # generated from a file or string in Webgen Page Format using the provided class methods.
+  class Page
 
-    # The name of the block.
-    attr_reader :name
+    # A single block within a Page object. The content of the block can be rendered using the #render method.
+    class Block
 
-    # The content of the block.
-    attr_reader :content
+      # The name of the block.
+      attr_reader :name
 
-    # The options set specifically for this block.
-    attr_reader :options
+      # The content of the block.
+      attr_reader :content
 
-    # Create a new block with the name +name+ and the given +content+ and +options+.
-    def initialize(name, content, options)
-      @name, @content, @options = name, content, options
-    end
+      # The options set specifically for this block.
+      attr_reader :options
 
-    # Render the block using the provided context object. Uses the content processors specified in
-    # the +pipeline+ key of the +options+ attribute to do the actual rendering.
-    #
-    # Returns the given context with the rendered content.
-    def render(context)
-      context[:content] = @content.dup
-      context[:block] = self
-      @options['pipeline'].to_s.split(/,/).each do |processor|
-        raise "No such content processor available: #{processor}" unless context[:processors].has_key?(processor)
-        context[:processors][processor].call(context)
+      # Create a new block with the name +name+ and the given +content+ and +options+.
+      def initialize(name, content, options)
+        @name, @content, @options = name, content, options
       end
-      context
-    end
 
-  end
+      # Render the block using the provided context object.
+      #
+      # The context object needs to respond to <tt>#[]</tt> and <tt>#[]=</tt> (e.g. a Hash is a valid
+      # context object) and the key <tt>:processors</tt> needs to contain a Hash which maps processor
+      # names to processor objects that respond to <tt>#call</tt>.
+      #
+      # Uses the content processors specified in the +pipeline+ key of the +options+ attribute to do
+      # the actual rendering.
+      #
+      # Returns the given context with the rendered content.
+      def render(context)
+        context[:content] = @content.dup
+        context[:block] = self
+        @options['pipeline'].to_s.split(/,/).each do |processor|
+          raise "No such content processor available: #{processor}" unless context[:processors].has_key?(processor)
+          context[:processors][processor].call(context)
+        end
+        context
+      end
 
+    end
 
-  # Raised during parsing of data in Webgen Page Format if the data is invalid.
-  class WebgenPageFormatError < RuntimeError; end
 
-  # A Page object wraps a meta information hash and an array of Block objects. It is normally
-  # generated from a file or string in Webgen Page Format using the provided class methods.
-  class Page
+    # Raised during parsing of data in Webgen Page Format if the data is invalid.
+    class FormatError < RuntimeError; end
+
 
+    # :stopdoc:
     RE_META_INFO_START = /\A---\s*(?:\n|\r|\r\n)/m
     RE_META_INFO = /\A---\s*(?:\n|\r|\r\n).*?(?:\n|\r|\r\n)(?=---.*?(?:\n|\r|\r\n)|\Z)/m
     RE_BLOCKS_OPTIONS = /^--- *?(?: *((?:\w+:[^\s]* *)*))?$|^$/
     RE_BLOCKS_START = /^--- .*?$|^--- *$/
     RE_BLOCKS = /(?:(#{RE_BLOCKS_START})|\A)(.*?)(?:(?=#{RE_BLOCKS_START})|\Z)/m
+    # :startdoc:
 
     class << self
 
@@ -81,17 +90,17 @@ module Webgen
       # original +data+ is used for checking the validness of the meta information block.
       def parse_meta_info(mi_data, data)
         if mi_data.nil? && data =~ RE_META_INFO_START
-          raise WebgenPageFormatError, 'Found start line for meta information block but no valid meta information block'
+          raise FormatError, 'Found start line for meta information block but no valid meta information block'
         elsif mi_data.nil?
           {}
         else
           begin
             meta_info = YAML::load(mi_data.to_s)
             unless meta_info.kind_of?(Hash)
-              raise WebgenPageFormatError, "Invalid structure of meta information block: expected YAML hash but found #{meta_info.class}"
+              raise FormatError, "Invalid structure of meta information block: expected YAML hash but found #{meta_info.class}"
             end
           rescue ArgumentError => e
-            raise WebgenPageFormatError, e.message
+            raise FormatError, e.message
           end
           meta_info
         end
@@ -101,20 +110,20 @@ module Webgen
       # which is used for setting the block names and options.
       def parse_blocks(data, meta_info)
         scanned = data.scan(RE_BLOCKS)
-        raise(WebgenPageFormatError, 'No content blocks specified') if scanned.length == 0
+        raise(FormatError, 'No content blocks specified') if scanned.length == 0
 
         blocks = {}
         scanned.each_with_index do |block_data, index|
           options, content = *block_data
           md = RE_BLOCKS_OPTIONS.match(options.to_s)
-          raise(WebgenPageFormatError, "Found invalid blocks starting line for block #{index+1}: #{options}") if content =~ /\A---/ || md.nil?
+          raise(FormatError, "Found invalid blocks starting line for block #{index+1}: #{options}") if content =~ /\A---/ || md.nil?
           options = Hash[*md[1].to_s.scan(/(\w+):([^\s]*)/).map {|k,v| [k, (v == '' ? nil : YAML::load(v))]}.flatten]
           options = (meta_info['blocks']['default'] || {} rescue {}).
             merge((meta_info['blocks'][index+1] || {} rescue {})).
             merge(options)
 
           name = options.delete('name') || (index == 0 ? 'content' : 'block' + (index + 1).to_s)
-          raise(WebgenPageFormatError, "Previously used name '#{name}' also used for block #{index+1}") if blocks.has_key?(name)
+          raise(FormatError, "Previously used name '#{name}' also used for block #{index+1}") if blocks.has_key?(name)
           content ||= ''
           content.gsub!(/^(\\+)(---.*?)$/) {|m| "\\" * ($1.length / 2) + $2}
           content.strip!

data/lib/webgen/path.rb

@@ -109,7 +109,7 @@ module Webgen
       temp
     end
 
-    # The IO object associated with the path.
+    # The SourceIO object associated with the path.
     def io
       if @io
         @io

data/lib/webgen/source.rb

@@ -4,15 +4,42 @@ module Webgen
 
   # Namespace for all classes that provide source paths.
   #
-  # = Implementing a source class
+  # == Implementing a source class
   #
   # Source classes provide access to the source paths on which the source handlers act.
   #
   # A source class only needs to respond to the method +paths+ which needs to return a set of paths
   # for the source. The returned paths must respond to the method <tt>changed?</tt> (has to return
-  # +true+ if the paths has changed since the last webgen run) which is not implemented in the
-  # default Path class. One can either derive a specialized path class or define singleton methods
-  # on each path object.
+  # +true+ if the paths has changed since the last webgen run). The default implementation in the
+  # Path class just returns +true+. One can either derive a specialized path class or define
+  # singleton methods on each path object.
+  #
+  # == Sample Source Class
+  #
+  # Following is a simple source class which has stored the paths and their contents in a hash:
+  #
+  #   require 'stringio'
+  #
+  #   class MemorySource
+  #
+  #     CONTENT = {
+  #       '/directory/' => nil,
+  #       '/directory/file.page' => "This is the content of the file"
+  #     }
+  #
+  #     def paths
+  #       CONTENT.collect do |path, content|
+  #         Webgen::Path.new(path) { StringIO.new(content.to_s) }
+  #       end.to_set
+  #     end
+  #
+  #   end
+  #
+  # You can use this source class in your website (after placing the code in, for example,
+  # <tt>ext/init.rb</tt>) by updating the <tt>sources</tt> configuration option (the following code
+  # has to be placed after the definition of the +MemorySource+ class):
+  #
+  #   WebsiteAccess.website.config['sources'] << ['/', MemorySource]
   #
   module Source
 
@@ -20,6 +47,7 @@ module Webgen
     autoload :FileSystem, 'webgen/source/filesystem'
     autoload :Stacked, 'webgen/source/stacked'
     autoload :Resource, 'webgen/source/resource'
+    autoload :TarArchive, 'webgen/source/tararchive'
 
   end
 

data/lib/webgen/source/resource.rb

@@ -5,15 +5,15 @@ require 'webgen/source'
 
 module Webgen::Source
 
-  # This class is used to provide access to source provided by resources.
+  # This class is used to provide access to sources provided by resources.
   class Resource
 
     include Webgen::WebsiteAccess
 
-    # The glob specifying the resources.
+    # The glob (see File.fnmatch) specifying the resources.
     attr_reader :glob
 
-    # The glob specifying the paths that should be used from the resources.
+    # The glob (see File.fnmatch) specifying the paths that should be used from the resources.
     attr_reader :paths_glob
 
     # The prefix that should optionally be stripped from the paths.

data/lib/webgen/source/stacked.rb

@@ -9,7 +9,7 @@ module Webgen::Source
   # * First, it can be used to access more than one source. This is useful when your website
   #   consists of more than one source directory and you want to use all of them.
   #
-  # * Second, sources can mounted on specific directories. For example, a folder with images that
+  # * Second, sources can be mounted on specific directories. For example, a folder with images that
   #   you don't want to copy to the website source directory can be mounted under <tt>/images</tt>
   #   sothat they are available nonetheless.
   #

data/lib/webgen/source/tararchive.rb

@@ -0,0 +1,73 @@
+# -*- encoding: utf-8 -*-
+
+require 'pathname'
+require 'webgen/websiteaccess'
+require 'webgen/path'
+require 'open-uri'
+require 'zlib'
+require 'archive/tar/minitar'
+
+module Webgen
+
+  # This class is used to read source paths from a (gzipped) tar archive. The archive can be remote
+  # (http(s) or ftp) or local.
+  #
+  # For example, the following are all valid URIs:
+  #   http://example.com/directory/file.tgz
+  #   /home/test/my.tar.gz
+  #   ftp://ftp.example.com/archives/archive.tar
+  #
+  class Source::TarArchive
+
+    # A special Webgen::Path class for handling paths from a tar archive.
+    class Path < Webgen::Path
+
+      # Create a new tar archive path object for the entry +entry+.
+      def initialize(path, data, mtime, uri)
+        super(path) { StringIO.new(data.to_s) }
+        @uri = uri
+        @mtime = mtime
+        WebsiteAccess.website.cache[[:tararchive_path, @uri, path]] = @mtime if WebsiteAccess.website
+        @meta_info['modified_at'] = @mtime
+      end
+
+      # Return +true+ if the tar archive path used by the object has been modified.
+      def changed?
+        !WebsiteAccess.website || @mtime > WebsiteAccess.website.cache[[:tararchive_path, @uri, path]]
+      end
+
+    end
+
+    # The URI of the tar archive.
+    attr_reader :uri
+
+    # The glob (see File.fnmatch for details) that is used to specify which paths in the archive should
+    # be returned by #paths.
+    attr_reader :glob
+
+    # Create a new tar archive source for the URI string +uri+.
+    def initialize(uri, glob = '**/*')
+      @uri = uri
+      @glob = glob
+    end
+
+    # Return all paths in the tar archive available at #uri.
+    def paths
+      if !defined?(@paths)
+        stream = open(@uri)
+        stream = Zlib::GzipReader.new(stream) if @uri =~ /(\.tar\.gz|\.tgz)$/
+        Archive::Tar::Minitar::Input.open(stream) do |input|
+          @paths = input.collect do |entry|
+            path = entry.full_name
+            next unless File.fnmatch(@glob, path, File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)
+            path += '/' if entry.directory? && path[-1] != ?/
+            Path.new(path, entry.read, Time.at(entry.mtime), @uri)
+          end.compact.to_set
+        end
+      end
+      @paths
+    end
+
+  end
+
+end