webgen 0.5.17 → 1.0.0.beta1

data/lib/webgen/path.rb

@@ -1,218 +1,252 @@
 # -*- encoding: utf-8 -*-
 
-require 'pathname'
+require 'uri'
 require 'webgen/languages'
 
 module Webgen
 
-  # == General Information
+  # == About
   #
   # 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.
+  # as methods for accessing/modifying the path's content. Path objects are created by Source
+  # classes but can also be created during the rendering phase (see
+  # PathHandler#create_secondary_nodes).
   #
-  # 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).
+  # So a Path object always refers to a path from which nodes are created! In contrast, destination
+  # paths are just strings and specify the location where a specific node should be written to (see
+  # Node#destination_path).
   #
   # 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!
+  # represents a file. Have a look at the user documentation to see the exact format that can be
+  # used for a path string!
+  #
+  # == Utility methods
   #
-  # == Relation to Source classes
+  # The Path class also provides some general methods for working with path strings which are also
+  # used, for example, by the Node class:
+  #
+  # * Path.url
+  # * Path.append
+  # * Path.matches_pattern
+  # * Path.lcn
   #
-  # 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
-  # webgen run.
   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 the to-be-wrapped IO
-      # object.
-      def initialize(&block)
-        @block = block
-        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 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
+    # This pattern is the the same as URI::UNSAFE except that the hash character (#) is also
+    # not escaped. This is needed so that paths with fragments work correctly.
+    URL_UNSAFE_PATTERN = Regexp.new("[^#{URI::PATTERN::UNRESERVED}#{URI::PATTERN::RESERVED}#]") # :nodoc:
 
-      # 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
+    # Base URI prepended to all internal URLs.
+    WEBGEN_BASE_URI = URI.parse('webgen://webgen.localhost/') # :nodoc:
 
+    # Construct an internal URL for the given +path+ which can be an acn/alcn/absolute path.
+    #
+    # If the parameter +make_absolute+ is +true+, then a relative URL will be made absolute by
+    # prepending the special URL 'webgen:://webgen.localhost/'.
+    def self.url(path, make_absolute = true)
+      url = URI.parse(URI::DEFAULT_PARSER.escape(path, URL_UNSAFE_PATTERN))
+      url = WEBGEN_BASE_URI + url unless url.absolute? || !make_absolute
+      url
     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 + (path =~ /.\/$/ ? '/' : '')
+    # Append the +path+ to the +base+ path.
+    #
+    # The +base+ parameter has to be an acn/alcn/absolute path. If it represents a directory, it
+    # needs to have a trailing slash! The +path+ parameter doesn't need to be absolute and may
+    # contain path patterns.
+    def self.append(base, path)
+      raise(ArgumentError, 'base needs to start with a slash (i.e. be an absolute path)') unless base =~ /^\//
+      url = url(base) + url(path, false)
+      url.path + (url.fragment.nil? ? '' : '#' + url.fragment)
     end
 
-    # Return +true+ if the given +path+ matches the given +pattern+. For information on which
-    # patterns are supported, have a look at the documentation of File.fnmatch.
-    def self.match(path, pattern)
+    # Return +true+ if the given path string matches the given path pattern.
+    #
+    # For information on which patterns are supported, have a look at the API documentation of
+    # File.fnmatch.
+    def self.matches_pattern?(path, pattern, options = File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)
       pattern += '/' if path.to_s =~ /\/$/ && pattern !~ /\/$|^$/
-      File.fnmatch(pattern, path.to_s, File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)
+      File.fnmatch(pattern, path, options)
     end
 
+    # Construct a localized canonical name from a given canonical name and a language.
+    def self.lcn(cn, lang)
+      if lang.nil?
+        cn
+      else
+        cn.split('.').insert((cn =~ /^\./ ? 2 : 1), lang.to_s).join('.')
+      end
+    end
 
-    include Comparable
-
-    # The full path for which this Path object was created.
-    attr_reader :path
-
-    # A string specifying the path that lead to the creation of this path.
-    attr_reader :source_path
-
-    # The string specifying the parent path
-    attr_reader :parent_path
-
-    # The canonical name of the path without the extension.
-    attr_accessor :basename
-
-    # The extension of the +path+.
-    attr_accessor :ext
 
-    # Extracted meta information for the path.
-    attr_accessor :meta_info
+    include Comparable
 
-    # 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
+    # Create a new Path object for +path+ (a string).
+    #
+    # The optional block needs to return an IO object for getting the content of the path (see #io
+    # and #data).
+    #
+    # The +path+ string needs to be in a well defined format which can be looked up in the webgen
+    # user documentation.
+    def initialize(path, meta_info = {}, &ioblock)
+      @path = path.freeze
+      @meta_info = meta_info.dup
+      @ioblock = block_given? ? ioblock : nil
+    end
 
-    # Is this path only used later during node resolution? Defaults to +false+, i.e. used during the
-    # "tree update" phase.
-    def passive?; @passive; end
+    def initialize_copy(orig) #:nodoc:
+      super
+      @meta_info = orig.instance_variable_get(:@meta_info).dup
+    end
 
+    # The original path string from which this Path object was created.
+    attr_reader :path
 
-    # Create a new Path object for +path+. The optional +source_path+ parameter specifies 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.
+    # Meta information about 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)
+    # Triggers analyzation of the path if invoked. See #[]= to setting meta information without
+    # triggering analyzation.
+    def meta_info
+      defined?(@basename) ? @meta_info : (analyse; @meta_info)
     end
 
-    # Mount this path at the mount point +mp+, optionally stripping +prefix+ from the parent path,
-    # and return the new path object.
+    # Get the value of the meta information key.
     #
-    # 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 =~ /^[^\/]|#|[^\/]$/
+    # This method has to be used to get meta information without triggering analyzation of the path
+    # string!
+    def [](key)
+      @meta_info[key]
+    end
 
-      temp = dup
-      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.instance_variable_set(:@parent_path, File.join(mp, temp.parent_path.sub(strip_re, '')))
-      end
-      temp
+    # Set the meta information +key+ to +value+.
+    #
+    # This method has to be used to set meta information without triggering analyzation of the path
+    # string!
+    def []=(key, value)
+      @meta_info[key] = value
     end
 
-    # Duplicate the path object.
-    def dup
-      temp = super
-      temp.instance_variable_set(:@meta_info, @meta_info.dup)
-      temp
+    # The string specifying the parent path.
+    #
+    # Triggers analyzation of the path if invoked.
+    def parent_path
+      defined?(@parent_path) ? @parent_path : (analyse; @parent_path)
     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
+    # The canonical name of the path without the extension.
+    #
+    # Triggers analyzation of the path if invoked.
+    def basename
+      defined?(@basename) ? @basename : (analyse; @basename)
     end
 
-    # The SourceIO object associated with the path.
-    def io
-      if @io
-        @io
-      else
-        raise "No IO object defined for the path #{self}"
-      end
+    # The extension of the path.
+    #
+    # Triggers analyzation of the path if invoked.
+    def ext
+      defined?(@ext) ? @ext : (analyse; @ext)
     end
 
-    # The canonical name created from the +path+ (namely from the parts +basename+ and +extension+).
-    def cn
-      @basename + (@ext.length > 0 ? '.' + @ext : '') + (@basename != '/' && @path =~ /.\/$/ ? '/' : '')
+    # Set the extension of the path.
+    #
+    # Triggers analyzation of the path if invoked.
+    def ext=(value)
+      defined?(@ext) || analyse
+      @ext = value
     end
 
-    # Utility method for creating the lcn from the +cn+ and the language +lang+.
-    def self.lcn(cn, lang)
-      if lang.nil?
-        cn
+    # The canonical name created from the +path+ (namely from the parts +basename+ and +extension+
+    # as well as the meta information +version+).
+    #
+    # Triggers analyzation of the path if invoked.
+    def cn
+      if meta_info['cn'].kind_of?(String)
+        tmp_cn = custom_cn
       else
-        cn.split('.').insert((cn =~ /^\./ ? 2 : 1), lang.to_s).join('.')
+        tmp_cn = basename + (use_version_for_cn? ? "-#{meta_info['version']}" : '') +
+          (ext.length > 0 ? '.' + ext : '')
       end
+      tmp_cn + (@path =~ /.\/$/ ? '/' : '')
     end
 
     # The localized canonical name created from the +path+.
+    #
+    # Triggers analyzation of the path if invoked.
     def lcn
-      self.class.lcn(cn, @meta_info['lang'])
+      self.class.lcn(cn, meta_info['lang'])
     end
 
     # The absolute canonical name of this path.
+    #
+    # Triggers analyzation of the path if invoked.
     def acn
       if @path =~ /#/
-        self.class.new(@parent_path).acn + cn
+        self.class.new(parent_path).acn + cn
       else
-        @parent_path + cn
+        parent_path + cn
       end
     end
 
     # The absolute localized canonical name of this path.
+    #
+    # Triggers analyzation of the path if invoked.
     def alcn
       if @path =~ /#/
-        self.class.new(@parent_path).alcn + lcn
+        self.class.new(parent_path).alcn + lcn
       else
-        @parent_path + lcn
+        parent_path + lcn
       end
     end
 
+
+    # 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!
+    #
+    # Also note that mounting a path is not possible once it is fully initialized, i.e. once some
+    # information extracted from the path string is accessed.
+    def mount_at(mp, prefix = nil)
+      raise(ArgumentError, "Can't mount a fully initialized path") if defined?(@basename)
+      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 = self.class.new(File.join(mp, @path.sub(/^#{Regexp.escape(prefix.to_s)}/, '')), @meta_info, &@ioblock)
+      temp
+    end
+
+    # Provide access to the IO object of the path by yielding it.
+    #
+    # After the method block returns, the IO object is automatically closed. An error is raised, if
+    # no IO object is associated with the Path instance.
+    #
+    # The parameter +mode+ specifies the mode in which the IO object should be opened. This can be
+    # used, for example, to specify a certain input encoding or to use binary mode.
+    def io(mode = 'r') # :yields: io
+      raise "No IO object defined for the path #{self}" if @ioblock.nil?
+      io = @ioblock.call(mode)
+      yield(io)
+    ensure
+      io.close if io
+    end
+
+    # Return the content of the IO object of the path as string.
+    #
+    # For a description of the parameter +mode+ see #io.
+    #
+    # An error is raised, if no IO object is associated with the Path instance.
+    def data(mode = 'r')
+      io(mode) {|io| io.read}
+    end
+
+    # Set the IO block to the provided block.
+    def set_io(&block)
+      @ioblock = block
+    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)
@@ -226,9 +260,9 @@ module Webgen
     end
     alias_method(:eql?, :==)
 
-    # Compare the #path of this object to <tt>other.path</tt>
+    # Compare the #path of this object to 'other.path'.
     def <=>(other)
-      @path <=> other.path
+      @path <=> other.to_str
     end
 
     def hash #:nodoc:
@@ -248,9 +282,8 @@ module Webgen
     private
     #######
 
-    # Analyse the +path+ and fill the object with the extracted information.
-    def analyse(path)
-      @path = path
+    # Analyse the path and extract the needed information.
+    def analyse
       if @path =~ /#/
         analyse_fragment
       elsif @path =~ /\/$/
@@ -258,10 +291,10 @@ module Webgen
       else
         analyse_file
       end
-      @meta_info['title'] = @basename.tr('_-', ' ').capitalize
+      @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 != '/'
+      raise "The parent path must start with a slash: #{@path}" if @path !~ /^\//
     end
 
     # Analyse the path assuming it is a directory.
@@ -270,7 +303,7 @@ module Webgen
       @basename = File.basename(@path)
     end
 
-    FILENAME_RE = /^(?:(\d+)\.)?(\.?[^.]*?)(?:\.(\w\w\w?)(?=\.))?(?:\.(.*))?$/
+    FILENAME_RE = /^(?:(\d+)\.)?(\.?[^.]*?)(?:\.(\w\w\w?)(?=\.))?(?:\.(.*))?$/ #:nodoc:
 
     # Analyse the path assuming it is a file.
     def analyse_file
@@ -281,9 +314,9 @@ module Webgen
         @basename = match_data[1]
         @ext = match_data[2]
       else
-        @meta_info['sort_info'] = (match_data[1].nil? ? nil : match_data[1].to_i)
+        @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])
+        @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
     end
@@ -295,6 +328,35 @@ module Webgen
       raise "A fragment path must only contain one hash character: #{path}" if @path.count("#") > 1
     end
 
+    # Whether the version information should be added to the cn?
+    def use_version_for_cn?
+      meta_info['version'] && meta_info['version'] != 'default'
+    end
+
+    CN_SEGMENTS = /<.*?>|\(.*?\)/ # :nodoc:
+
+    # Construct a custom canonical name given by the 'cn' meta information.
+    def custom_cn
+      replace_segment = lambda do |match|
+        case match
+        when "<basename>"
+          basename
+        when "<ext>"
+          ext.empty? ? '' : '.' << ext
+        when "<version>"
+          use_version_for_cn? ? meta_info['version'] : ''
+        when /\((.*)\)/
+          inner = $1
+          replaced = inner.gsub(CN_SEGMENTS, &replace_segment)
+          removed = inner.gsub(CN_SEGMENTS, "")
+          replaced == removed ? '' : replaced
+        else
+          ''
+        end
+      end
+      self.meta_info['cn'].gsub(CN_SEGMENTS, &replace_segment).gsub(/\/+$/, '')
+    end
+
   end
 
 end