webgen 0.5.8 → 0.5.9

data/lib/webgen/output.rb

@@ -18,8 +18,10 @@ module Webgen
   #   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.
+  # [<tt>read(path, mode = 'rb')</tt>]
+  #   Return the content of the given path if it exists or raise an error otherwise. The parameter
+  #   +mode+ specifies the mode in which the path should be opened and defaults to reading in binary
+  #   mode.
   #
   #   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
@@ -52,7 +54,7 @@ module Webgen
   #       @data[path] = [(io.kind_of?(String) ? io : io.data), type]
   #     end
   #
-  #     def read(path)
+  #     def read(path, mode = 'rb')
   #       path = File.join('/', path)
   #       raise "No such file #{path}" unless @data[path] && @data[path].last == :file
   #       @data[path].first

data/lib/webgen/output/filesystem.rb

@@ -50,7 +50,7 @@ module Webgen::Output
         if data.kind_of?(String)
           File.open(dest, 'wb') {|f| f.write(data) }
         else
-          data.stream do |source|
+          data.stream('rb') do |source|
             File.open(dest, 'wb') {|f| FileUtils.copy_stream(source, f) }
           end
         end
@@ -59,9 +59,9 @@ module Webgen::Output
       end
     end
 
-    # Return the content of the given +path+.
-    def read(path)
-      File.open(File.join(@root, path), 'rb') {|f| f.read}
+    # Return the content of the given +path+ which is opened in +mode+.
+    def read(path, mode = 'rb')
+      File.open(File.join(@root, path), mode) {|f| f.read}
     end
 
   end

data/lib/webgen/page.rb

@@ -49,7 +49,7 @@ module Webgen
 
 
     # Raised during parsing of data in Webgen Page Format if the data is invalid.
-    class FormatError < RuntimeError; end
+    class FormatError < StandardError; end
 
 
     # :stopdoc:
@@ -57,7 +57,7 @@ module Webgen
     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
+    RE_BLOCKS = /(?:(#{RE_BLOCKS_START})|\A)\n?(.*?)(?:(?=#{RE_BLOCKS_START})|\z)/m
     # :startdoc:
 
     class << self
@@ -100,7 +100,7 @@ module Webgen
               raise FormatError, "Invalid structure of meta information block: expected YAML hash but found #{meta_info.class}"
             end
           rescue ArgumentError => e
-            raise FormatError, e.message
+            raise FormatError, "Invalid YAML syntax in meta information block: #{e.message}"
           end
           meta_info
         end
@@ -126,7 +126,7 @@ module Webgen
           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!
+          content.chomp!("\n") unless index + 1 == scanned.length
           blocks[name] = blocks[index+1] = Block.new(name, content, options)
         end
         meta_info.delete('blocks')

data/lib/webgen/path.rb

@@ -1,11 +1,33 @@
 # -*- encoding: utf-8 -*-
 
+require 'pathname'
 require 'webgen/languages'
 
 module Webgen
 
-  # A path object provides information about a specific path as well as methods for accessing its
-  # content.
+  # == General Information
+  #
+  # A Path object provides information about a path that is used to create one or more nodes as well
+  # as methods for accessing the path's content. So a Path object always refers to a source path. In
+  # contrast, output paths are always strings and just specify the location where a specific node
+  # should be written to.
+  #
+  # Note the +path+ and +source_path+ attributes of a Path object:
+  #
+  # * The +source_path+ specifies a path string that was directly created by a Source object. Each
+  #   Path object must have such a valid source path sothat webgen can infer the Path the lead to
+  #   the creation of a Node object later.
+  #
+  # * In contrast, the +path+ attribute specifies the path that is used to create the canonical name
+  #   (and by default the output path) of a Node object. Normally it is the same as the
+  #   +source_path+ but can differ (e.g. when fragment nodes are created for page file nodes).
+  #
+  # A Path object can represent one of three different things: a directory, a file or a fragment. If
+  # the +path+ ends with a slash character, then the path object represents a directory, if the path
+  # contains a hash character anywhere, then the path object represents a fragment and else it
+  # represents a file. Have a look at the webgen manual to see the exact format of a path!
+  #
+  # == Relation to Source classes
   #
   # A webgen source class needs to derive a specialized path class from this class and implement an
   # approriate #changed? method that returns +true+ if the path's content has changed since the last
@@ -13,30 +35,48 @@ module Webgen
   class Path
 
     # Helper class for easy access to the content of a path.
+    #
+    # This class is used sothat the creation of the real IO object for #stream can be delayed till
+    # it is actually needed. This is done by not directly requiring the user of this class to supply
+    # the IO object, but by requiring a block that creates the real IO object.
     class SourceIO
 
-      # Create a new SourceIO object. A block has to be specified that returns an IO object.
+      # Create a new SourceIO object. A block has to be specified that returns the to-be-wrapped IO
+      # object.
       def initialize(&block)
         @block = block
-        raise ArgumentError, 'Need to provide a block which returns an IO object' if @block.nil?
+        raise ArgumentError, 'You need to provide a block which returns an IO object' if @block.nil?
       end
 
-      # Provide direct access to the wrapped IO object.
-      def stream
-        io = @block.call
+      # Provide direct access to the wrapped IO object by yielding it. After the method block
+      # returns the IO object is automatically closed.
+      #
+      # The parameter +mode+ specifies the mode in which the wrapped IO object should be opened.
+      # This can be used, for example, to open a file in binary mode (or specify a certain input
+      # encoding under Ruby 1.9).
+      def stream(mode = 'r')
+        io = @block.call(mode)
         yield(io)
       ensure
         io.close
       end
 
-      # Return the content of the wrapped IO object as string.
-      def data
-        stream {|io| io.read}
+      # Return the whole content of the wrapped IO object as string. For a description of the
+      # parameter +mode+ see #stream.
+      def data(mode = 'r')
+        stream(mode) {|io| io.read}
       end
 
     end
 
 
+    # Make the given +path+ absolute by prepending the absolute directory path +base+ if necessary.
+    # Also resolves all '..' and '.' references in +path+.
+    def self.make_absolute(base, path)
+      raise(ArgumentError, 'base has to be an absolute path, ie. needs to start with a slash') unless base =~ /\//
+      Pathname.new(path =~ /^\// ? path : File.join(base, path)).cleanpath.to_s
+    end
+
     # Return +true+ if the given +path+ matches the given +pattern+ (trailing slashes of directories
     # are not respected). For information on which patterns are supported, have a look at the
     # documentation of File.fnmatch.
@@ -49,66 +89,86 @@ module Webgen
 
     include Comparable
 
-    # The full path.
-    attr_accessor :path
+    # The full path for which this Path object was created.
+    attr_reader :path
 
-    # The source path that lead to the creation of this path.
-    attr_accessor :source_path
+    # A string specifying the path that lead to the creation of this path.
+    attr_reader :source_path
 
-    # The basename part of the path.
-    attr_accessor :basename
+    # The string specifying the parent path
+    attr_reader :parent_path
 
-    # The directory part of the path.
-    attr_accessor :directory
-
-    # The canonical name without the extension.
-    attr_accessor :cnbase
+    # The canonical name of the path without the extension.
+    attr_accessor :basename
 
-    # The extension.
+    # The extension of the +path+.
     attr_accessor :ext
 
     # Extracted meta information for the path.
     attr_accessor :meta_info
 
+    # Specifies whether this path should be used during the "tree update" phase of a webgen run or
+    # only later during node resolution.
+    attr_writer :passive
+
+    # Is this path only used later during node resolution? Defaults to +false+, i.e. used during the
+    # "tree update" phase.
+    def passive?; @passive; end
+
+
     # Create a new Path object for +path+. The optional +source_path+ parameter specifies the path
-    # that lead to the creation of this path. The optional block needs to return an IO object for
-    # the content of the path.
+    # string that lead to the creation of this path. The optional block needs to return an IO object
+    # for getting the content of the path.
+    #
+    # The +path+ needs to be in a well defined format which can be looked up in the webgen manual.
     def initialize(path, source_path = path, &ioblock)
       @meta_info = {}
       @io = block_given? ? SourceIO.new(&ioblock) : nil
       @source_path = source_path
+      @passive = false
       analyse(path)
     end
 
-    # Mount this path at the mount point +mp+ optionally stripping +prefix+ from the path and return
-    # the new path object.
+    # Mount this path at the mount point +mp+, optionally stripping +prefix+ from the parent path,
+    # and return the new path object.
+    #
+    # The parameters +mp+ and +prefix+ have to be absolute directory paths, ie. they have to start
+    # and end with a slash and must not contain any hash characters!
+    #
+    #--
+    # Can't use self.class.new(...) here because the semantics of the sub constructors is not know
+    #++
     def mount_at(mp, prefix = nil)
+      raise(ArgumentError, "The mount point (#{mp}) must be a valid directory path") if mp =~ /^[^\/]|#|[^\/]$/
+      raise(ArgumentError, "The strip prefix (#{prefix}) must be a valid directory path") if !prefix.nil? && prefix =~ /^[^\/]|#|[^\/]$/
+
       temp = dup
-      temp.path = temp.path.sub(/^#{Regexp.escape(prefix.chomp("/"))}/, '') if prefix     #"
-      reanalyse = (@path == '/' || temp.path == '/')
-      temp.path = File.join(mp, temp.path)
-      temp.source_path = temp.path if @path == @source_path
+      strip_re = /^#{Regexp.escape(prefix.to_s)}/
+      temp.instance_variable_set(:@path, temp.path.sub(strip_re, ''))
+      reanalyse = (@path == '/' || temp.path == '')
+      temp.instance_variable_set(:@path, File.join(mp, temp.path))
+      temp.instance_variable_set(:@source_path, temp.path) if @path == @source_path
       if reanalyse
         temp.send(:analyse, temp.path)
       else
-        temp.directory = File.join(File.dirname(temp.path), '/')
+        temp.instance_variable_set(:@parent_path, File.join(mp, temp.parent_path.sub(strip_re, '')))
       end
       temp
     end
 
-    # Has the content of this path changed since the last webgen run? This default implementation
-    # always returns +true+, a specialized sub class needs to override this behaviour!
-    def changed?
-      true
-    end
-
     # Duplicate the path object.
     def dup
       temp = super
-      temp.meta_info = @meta_info.dup
+      temp.instance_variable_set(:@meta_info, @meta_info.dup)
       temp
     end
 
+    # Has the content of this path changed since the last webgen run? This default implementation
+    # always returns +true+, a specialized sub class needs to override this behaviour!
+    def changed?
+      true
+    end
+
     # The SourceIO object associated with the path.
     def io
       if @io
@@ -118,26 +178,45 @@ module Webgen
       end
     end
 
-    # The canonical name created from the filename (created from cnbase and extension).
+    # The canonical name created from the +path+ (namely from the parts +basename+ and +extension+).
     def cn
-      @cnbase + (@ext.length > 0 ? '.' + @ext : '')
+      @basename + (@ext.length > 0 ? '.' + @ext : '') + (@basename != '/' && @path =~ /.\/$/ ? '/' : '')
     end
 
-    # Utility method for creating the lcn from +cn+ and the language +lang+.
+    # Utility method for creating the lcn from the +cn+ and the language +lang+.
     def self.lcn(cn, lang)
       if lang.nil?
         cn
       else
-        cn.split('.').insert(1, lang.to_s).join('.')
+        cn.split('.').insert((cn =~ /^\./ ? 2 : 1), lang.to_s).join('.')
       end
     end
 
-    # The localized canonical name created from the filename.
+    # The localized canonical name created from the +path+.
     def lcn
       self.class.lcn(cn, @meta_info['lang'])
     end
 
-    # Compare this object to another Path or a String.
+    # The absolute canonical name of this path.
+    def acn
+      if @path =~ /#/
+        self.class.new(@parent_path).acn + cn
+      else
+        @parent_path + cn
+      end
+    end
+
+    # The absolute localized canonical name of this path.
+    def alcn
+      if @path =~ /#/
+        self.class.new(@parent_path).alcn + lcn
+      else
+        @parent_path + lcn
+      end
+    end
+
+    # Equality -- Return +true+ if +other+ is a Path object with the same #path or if +other+ is a
+    # String equal to the #path. Else return +false+.
     def ==(other)
       if other.kind_of?(Path)
         other.path == @path
@@ -149,13 +228,12 @@ module Webgen
     end
     alias_method(:eql?, :==)
 
-    # Implemented sothat a Path looks like a String when used as key in a hash.
+    # Compare the #path of this object to <tt>other.path</tt>
     def <=>(other)
-      @path <=> other.to_str
+      @path <=> other.path
     end
 
-    # Implemented sothat a Path looks like a String when used as key in a hash.
-    def hash
+    def hash #:nodoc:
       @path.hash
     end
 
@@ -172,21 +250,46 @@ module Webgen
     private
     #######
 
-    FILENAME_RE = /^(?:(\d+)\.)?([^.]*?)(?:\.(\w\w\w?)(?=.))?(?:\.(.*))?$/
-
     # Analyse the +path+ and fill the object with the extracted information.
     def analyse(path)
       @path = path
-      @basename = File.basename(path)
-      @directory = File.join(File.dirname(path), '/')
-      matchData = FILENAME_RE.match(@basename)
+      if @path =~ /#/
+        analyse_fragment
+      elsif @path =~ /\/$/
+        analyse_directory
+      else
+        analyse_file
+      end
+      @meta_info['title'] = @basename.tr('_-', ' ').capitalize
+      @ext ||= ''
+      raise "The basename of a path may not be empty: #{@path}" if @basename.empty? || @basename == '#'
+      raise "The parent path must start with a slash: #{@path}" if @path !~ /^\// && @path != '/'
+    end
 
-      @meta_info['sort_info'] = (matchData[1].nil? ? nil : matchData[1].to_i)
-      @cnbase                 = matchData[2]
-      @meta_info['lang']      = Webgen::LanguageManager.language_for_code(matchData[3])
-      @ext                    = (@meta_info['lang'].nil? && !matchData[3].nil? ? matchData[3].to_s + '.' : '') + matchData[4].to_s
+    # Analyse the path assuming it is a directory.
+    def analyse_directory
+      @parent_path = (@path == '/' ? '' : File.join(File.dirname(@path), '/'))
+      @basename = File.basename(@path)
+    end
+
+    FILENAME_RE = /^(?:(\d+)\.)?(\.?[^.]*?)(?:\.(\w\w\w?)(?=\.))?(?:\.(.*))?$/
+
+    # Analyse the path assuming it is a file.
+    def analyse_file
+      @parent_path = File.join(File.dirname(@path), '/')
+      match_data = FILENAME_RE.match(File.basename(@path))
+
+      @meta_info['sort_info'] = (match_data[1].nil? ? nil : match_data[1].to_i)
+      @basename               = match_data[2]
+      @meta_info['lang']      = Webgen::LanguageManager.language_for_code(match_data[3])
+      @ext                    = (@meta_info['lang'].nil? && !match_data[3].nil? ? match_data[3].to_s : '') + match_data[4].to_s
+    end
 
-      @meta_info['title']     = @cnbase.tr('_-', ' ').capitalize
+    # Analyse the path assuming it is a fragment.
+    def analyse_fragment
+      @parent_path, @basename =  @path.scan(/^(.*?)(#.*?)$/).first
+      raise "The parent path of a fragment path must be a file path and not a directory path: #{@path}" if @parent_path =~ /\/$/
+      raise "A fragment path must only contain one hash character: #{path}" if @path.count("#") > 1
     end
 
   end

data/lib/webgen/source.rb

@@ -10,9 +10,13 @@ module Webgen
   #
   # 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). 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.
+  # +true+ if the paths has changed since the last webgen run). If a path represents a directory, it
+  # needs to have a trailing slash! 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.
+  #
+  # Also note that the returned Path objects should have the meta information <tt>modified_at</tt>
+  # set to the correct last modification time of the path, ie. the value has to be a Time object!
   #
   # == Sample Source Class
   #
@@ -36,10 +40,9 @@ module Webgen
   #   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):
+  # <tt>ext/init.rb</tt>) by updating the <tt>sources</tt> configuration option:
   #
-  #   WebsiteAccess.website.config['sources'] << ['/', MemorySource]
+  #   WebsiteAccess.website.config['sources'] << ['/', 'MemorySource']
   #
   module Source
 

data/lib/webgen/source/filesystem.rb

@@ -14,7 +14,7 @@ module Webgen
 
       # Create a new object with absolute path +path+ for the file system path +fs_path+.
       def initialize(path, fs_path)
-        super(path) { File.open(fs_path, 'rb') }
+        super(path) {|mode| File.open(fs_path, mode) }
         @fs_path = fs_path
         WebsiteAccess.website.cache[[:fs_path, @fs_path]] = File.mtime(@fs_path)
         @meta_info['modified_at'] = File.mtime(@fs_path)