webgen 1.0.0.beta2 → 1.0.0.beta3

data/lib/webgen/page.rb

@@ -112,6 +112,16 @@ module Webgen
       @blocks = blocks
     end
 
+    # Convert the Page object back into a string.
+    def to_s
+      str = ""
+      str << @meta_info.to_yaml
+      blocks.each do |name, value|
+        str << "--- #{name}\n" << value.gsub(/^---.*?$/) {|m| "\\#{m}" } << (value =~ /\n$/ ? "" : "\n")
+      end
+      str
+    end
+
   end
 
 end

data/lib/webgen/path.rb

@@ -29,7 +29,7 @@ module Webgen
   #
   # * Path.url
   # * Path.append
-  # * Path.matches_pattern
+  # * Path.matches_pattern?
   # * Path.lcn
   #
   class Path
@@ -44,7 +44,7 @@ module Webgen
     # 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/'.
+    # 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
@@ -57,9 +57,9 @@ module Webgen
     # 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 =~ /^\//
+      raise(ArgumentError, 'base needs to start with a slash (i.e. be an absolute path)') unless base[0] == ?/
       url = url(base) + url(path, false)
-      url.path + (url.fragment.nil? ? '' : '#' + url.fragment)
+      url.path << (url.fragment.nil? ? '' : "##{url.fragment}")
     end
 
     # Return +true+ if the given path string matches the given path pattern.
@@ -67,7 +67,7 @@ module Webgen
     # 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 !~ /\/$|^$/
+      pattern += '/' if path =~ /\/$/ && pattern !~ /\/$|^$/
       File.fnmatch(pattern, path, options)
     end
 
@@ -162,13 +162,13 @@ module Webgen
     #
     # Triggers analyzation of the path if invoked.
     def cn
-      if meta_info['cn'].kind_of?(String)
+      if meta_info['cn']
         tmp_cn = custom_cn
       else
-        tmp_cn = basename + (use_version_for_cn? ? "-#{meta_info['version']}" : '') +
-          (ext.length > 0 ? '.' + ext : '')
+        tmp_cn = basename.dup << (use_version_for_cn? ? "-#{meta_info['version']}" : '') <<
+          (ext.length > 0 ? ".#{ext}" : '')
       end
-      tmp_cn + (@path =~ /.\/$/ ? '/' : '')
+      tmp_cn << (@path =~ /.\/$/ ? '/' : '')
     end
 
     # The localized canonical name created from the +path+.
@@ -183,7 +183,7 @@ module Webgen
     # 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
       end
@@ -194,7 +194,7 @@ module Webgen
     # 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
       end
@@ -270,7 +270,7 @@ module Webgen
     end
 
     def to_s #:nodoc:
-      @path.dup
+      @path
     end
     alias_method :to_str, :to_s
 
@@ -317,7 +317,7 @@ module Webgen
         @meta_info['sort_info'] ||= match_data[1].to_i unless match_data[1].nil?
         @basename               = match_data[2]
         @meta_info['lang']      ||= Webgen::LanguageManager.language_for_code(match_data[3]) if match_data[3]
-        @ext                    = (@meta_info['lang'].nil? && !match_data[3].nil? ? match_data[3].to_s + '.' : '') + match_data[4].to_s
+        @ext                    = (@meta_info['lang'].nil? && !match_data[3].nil? ? match_data[3] << '.' : '') << match_data[4].to_s
       end
     end
 
@@ -354,7 +354,7 @@ module Webgen
           ''
         end
       end
-      self.meta_info['cn'].gsub(CN_SEGMENTS, &replace_segment).gsub(/\/+$/, '')
+      self.meta_info['cn'].to_s.gsub(CN_SEGMENTS, &replace_segment).gsub(/\/+$/, '')
     end
 
   end

data/lib/webgen/path_handler.rb

@@ -146,19 +146,24 @@ module Webgen
       end
 
       used_secondary_paths = {}
+      written_nodes = Set.new
       @website.blackboard.add_listener(:before_secondary_nodes_created, self) do |path, source_alcn|
         (used_secondary_paths[source_alcn] ||= Set.new) << path if source_alcn
       end
-      @website.blackboard.add_listener(:before_node_written, self) do |node|
+      @website.blackboard.add_listener(:before_all_nodes_written, self) do |node|
         used_secondary_paths = {}
+        written_nodes = Set.new
       end
       @website.blackboard.add_listener(:after_node_written, self) do |node|
-        @secondary_nodes.select do |path, data|
-          data[1] == node.alcn && used_secondary_paths[node.alcn] &&
-            !used_secondary_paths[node.alcn].include?(path)
-        end.each do |path, data|
-          @secondary_nodes.delete(path)
-          data[2].each {|alcn| @website.tree.delete_node(@website.tree[alcn])}
+        written_nodes << node.alcn
+      end
+      @website.blackboard.add_listener(:after_all_nodes_written, self) do |node|
+        @secondary_nodes.delete_if do |path, data|
+          if written_nodes.include?(data[1]) && (!used_secondary_paths[data[1]] ||
+                                                 !used_secondary_paths[data[1]].include?(path))
+            data[2].each {|alcn| @website.tree.delete_node(@website.tree[alcn])}
+            true
+          end
         end
       end
     end
@@ -208,7 +213,7 @@ module Webgen
 
     # Return the instance of the path handler class with the given name.
     def instance(handler)
-      @instances[handler] ||= extension(handler).new(@website)
+      @instances[handler.intern] ||= extension(handler).new(@website)
     end
 
 
@@ -216,7 +221,7 @@ module Webgen
     #
     # Can only be called once because the tree can only be populated once!
     def populate_tree
-      raise Webgen::NodeCreationError.new("Can't populate tree twice", self.class.name) if @website.tree.root
+      raise Webgen::NodeCreationError.new("Can't populate tree twice", 'path_handler') if @website.tree.root
 
       time = Benchmark.measure do
         meta_info, rest = @website.ext.source.paths.partition {|path| path.path =~ /[\/.]metainfo$/}
@@ -268,9 +273,10 @@ module Webgen
             @website.blackboard.dispatch_msg(:after_node_written, node, content)
           rescue Webgen::Error => e
             e.path = node.alcn if e.path.to_s.empty?
+            e.location = "path_handler.#{node.node_info[:path_handler]}" unless e.location
             raise
           rescue Exception => e
-            raise Webgen::RenderError.new(e, nil, node)
+            raise Webgen::RenderError.new(e, "path_handler.#{node.node_info[:path_handler]}", node)
           end
         end
         @website.blackboard.dispatch_msg(:after_all_nodes_written)
@@ -325,7 +331,7 @@ module Webgen
     # alcn from which these nodes are created!
     def create_secondary_nodes(path, content = '', source_alcn = nil)
       if (sn = @secondary_nodes[path]) && sn[1] != source_alcn
-        raise Webgen::NodeCreationError.new("Duplicate secondary path name <#{path}>", self.class.name, path)
+        raise Webgen::NodeCreationError.new("Duplicate secondary path name <#{path}>", 'path_handler', path)
       end
       @website.blackboard.dispatch_msg(:before_secondary_nodes_created, path, source_alcn)
 
@@ -388,10 +394,10 @@ module Webgen
       end
     rescue Webgen::Error => e
       e.path = path.to_s if e.path.to_s.empty?
-      e.location = instance(handler).class.name unless e.location
+      e.location = "path_handler.#{handler}" unless e.location
       raise
     rescue Exception => e
-      raise Webgen::NodeCreationError.new(e, instance(handler).class.name, path)
+      raise Webgen::NodeCreationError.new(e, "path_handler.#{handler}", path)
     end
     private :create_nodes_with_path_handler
 

data/lib/webgen/path_handler/api.rb

@@ -0,0 +1,173 @@
+# -*- encoding: utf-8 -*-
+
+require 'time'
+require 'shellwords'
+require 'webgen/path_handler/base'
+require 'webgen/path_handler/page_utils'
+require 'webgen/context'
+require 'webgen/path'
+require 'webgen/content_processor/r_doc'
+
+module Webgen
+  class PathHandler
+
+    # Path handler for Ruby API documentation via rdoc.
+    class Api
+
+      include Base
+      include PageUtils
+
+      # The mandatory meta info keys that need to be set on an api path.
+      MANDATORY_INFOS = %W[rdoc_options]
+
+      # Create the feed nodes.
+      def create_nodes(path, blocks)
+        if MANDATORY_INFOS.any? {|t| path.meta_info[t].nil?}
+          raise Webgen::NodeCreationError.new("At least one of #{MANDATORY_INFOS.join('/')} is missing",
+                                              "path_handler.api", path)
+        end
+
+        path['api_name'] ||= path.basename
+        path['dir_name'] ||= path.basename
+
+        cache_dir = @website.tmpdir(File.join('path_handler.api', path['api_name']))
+        rdoc = rdoc_object(path['rdoc_options'], cache_dir)
+        output_flag_file = rdoc.output_flag_file(cache_dir)
+
+        dir_node = create_directory(path, Webgen::Path.new(path.parent_path + path['dir_name'] + '/'), false)
+
+        rdoc.store.all_classes_and_modules.sort.each do |klass|
+          klass_node = create_page_node_for_class(path, dir_node, klass, output_flag_file)
+          klass.each_method {|method| create_fragment_node_for_method(path, klass_node, method)}
+        end
+
+        nil
+      end
+
+      # Create a directory for the path, applying needed meta information from the api path.
+      #
+      # Also creates the parent directories when necessary.
+      def create_directory(api_path, path, set_proxy_path = true)
+        if (dir = @website.tree[path.alcn])
+          return dir
+        end
+
+        parent_path = Webgen::Path.new(path.parent_path)
+        if !@website.tree[parent_path.alcn]
+          create_directory(api_path, parent_path)
+        end
+
+        path['modified_at'] = api_path['modified_at']
+        path['handler'] = 'directory'
+        path['proxy_path'] ||= "../#{path.basename}.html" if set_proxy_path
+        @website.ext.path_handler.create_secondary_nodes(path).first
+      end
+      private :create_directory
+
+      # Create the RDoc instance and use it for generating the API data.
+      #
+      # If possible, cached data available under +cache_dir+ is used.
+      def rdoc_object(options, cache_dir)
+        start_time = Time.now
+
+        rdoc = RDoc::RDoc.new
+        rdoc.options = rdoc_options(options)
+        rdoc.store = rdoc_store(rdoc.options, cache_dir)
+
+        rdoc.exclude = rdoc.options.exclude
+        rdoc.last_modified.replace(rdoc.setup_output_dir(cache_dir, false))
+
+        if !(rdoc.parse_files(rdoc.options.files)).empty?
+          rdoc.store.complete(rdoc.options.visibility)
+          rdoc.store.save
+          rdoc.update_output_dir(cache_dir, start_time, rdoc.last_modified)
+        end
+        rdoc.store.load_all
+
+        # We need a dummy generator with some methods
+        rdoc.generator = Object.new
+        def (rdoc.generator).class_dir; nil; end
+        def (rdoc.generator).file_dir; nil; end
+
+        rdoc
+      end
+      protected :rdoc_object
+
+      # Return a fully initialized RDoc::Options object.
+      #
+      # Some of the user specified options may not be used if they would interfere with this class'
+      # job.
+      def rdoc_options(user_options)
+        user_options = Shellwords.split(user_options) if user_options.kind_of?(String)
+        options = RDoc::Options.new
+        options.parse(user_options)
+        options.verbosity = 0
+        options.dry_run = false
+        options.update_output_dir = true
+        options.force_output = false
+        options.finish
+        options
+      end
+      protected :rdoc_options
+
+      # Return a fully initialized RDoc::Store object.
+      def rdoc_store(options, cache_dir)
+        store = RDoc::Store.new(cache_dir)
+        store.encoding = options.encoding
+        store.dry_run = options.dry_run
+        store.main = options.main_page
+        store.title = options.title
+        store.load_cache
+        store
+      end
+      protected :rdoc_store
+
+      # Create a page node for the given class +klass+ and return it.
+      #
+      # A link definition entry for the class is also created.
+      def create_page_node_for_class(api_path, dir_node, klass, output_flag_file)
+        klass_path_str = klass.http_url(dir_node.alcn)
+
+        create_directory(api_path, Webgen::Path.new(File.dirname(klass_path_str) + '/'))
+
+        path = Webgen::Path.new(klass_path_str, 'handler' => 'page', 'modified_at' => api_path['modified_at'],
+                                'title' => "#{klass.type} #{klass.full_name}", 'api_class' => klass.full_name,
+                                'api_name' => api_path['api_name'], 'template' => api_path['api_template'])
+        node = @website.ext.path_handler.create_secondary_nodes(path).first
+
+        node.node_info[:api_class_object] = klass
+        @website.ext.item_tracker.add(node, :file, output_flag_file)
+        add_link_definition(api_path, klass.full_name, node.alcn, klass.full_name)
+
+        node
+      end
+      protected :create_page_node_for_class
+
+      # Create a fragment node for the given method.
+      #
+      # A link definition entry for the method is also created.
+      def create_fragment_node_for_method(api_path, klass_node, method)
+        method_url = "#{klass_node.alcn}##{method.aref}"
+        path = Webgen::Path.new(method_url,
+                                {'handler' => 'copy', 'modified_at' => api_path['modified_at'],
+                                  'pipeline' => [], 'no_output' => true, 'title' => method.name})
+        @website.ext.path_handler.create_secondary_nodes(path)
+        add_link_definition(api_path, method.full_name, method_url, method.full_name)
+      end
+      protected :create_fragment_node_for_method
+
+      # Add a link definition for the given node.
+      def add_link_definition(api_path, link_name, url, title)
+        link = if api_path['prefix_for_link_defs']
+                 "#{api_path['api_name']}:#{link_name}"
+               else
+                 link_name
+               end
+        @website.ext.link_definitions[link] = [url, title]
+      end
+      protected :add_link_definition
+
+    end
+
+  end
+end

data/lib/webgen/path_handler/base.rb

@@ -4,6 +4,7 @@ require 'webgen/path_handler'
 require 'webgen/error'
 require 'webgen/node'
 require 'webgen/path'
+require 'webgen/utils'
 
 module Webgen
   class PathHandler
@@ -27,10 +28,18 @@ module Webgen
     #
     module Base
 
-      # This is the base Node sub class used by the Base#create_node method if a path handler class
-      # does not specify another Node class.
+      # This is the Node sub class used by the Base#create_node method if a path handler class does
+      # not specify another Node class.
       class Node < Webgen::Node
 
+        # Does exactly the same as Node#route_to but also automatically adds the necessary item
+        # tracking information.
+        def route_to(node, lang = @lang)
+          tree.website.ext.item_tracker.add(self, :node_meta_info, node)
+          tree.website.ext.item_tracker.add(self, :node_meta_info, node.proxy_node(lang))
+          super
+        end
+
         # Return the result of the #content method on the associated path handler or +nil+ if the
         # associated path handler does not have a #content method.
         def content
@@ -60,18 +69,19 @@ module Webgen
       # Create a node from +path+, if possible, yield the fully initialized node if a block is given
       # and return it.
       #
-      # The node class to be used for the created node can be specified via the +node_klass+
-      # parameter.
-      #
-      # If no node can be created (e.g. when 'path.meta_info['draft']' is set), +nil+ is returned.
+      # The node class to be used for the to-be-created node can be specified via
+      # `path.meta_info['node_class']`. If this node processing information is not set, the
+      # Base::Node class is used.
       #
       # The parent node under which the new node should be created can optionally be specified via
-      # 'path.meta_info['parent_alcn']'. This meta information has to be set to an alcn of an
-      # existing node.
+      # 'path.meta_info['parent_alcn']'. This node processing information has to be set to the alcn
+      # of an existing node.
+      #
+      # If no node can be created (e.g. when 'path.meta_info['draft']' is set), +nil+ is returned.
       #
       # On the created node, the node information +:path+ is set to the given path and
       # +:path_handler+ to the path handler instance.
-      def create_node(path, node_klass = Node)
+      def create_node(path)
         return nil if path.meta_info['draft']
         parent = parent_node(path)
         dest_path = self.dest_path(parent, path)
@@ -95,7 +105,7 @@ module Webgen
           path.meta_info['modified_at'] = Time.now
         end
 
-        node = node_klass.new(parent, path.cn, dest_path, path.meta_info.dup)
+        node = node_class(path).new(parent, path.cn, dest_path, path.meta_info.dup)
         node.node_info[:path] = path
         node.node_info[:path_handler] = self
 
@@ -220,10 +230,22 @@ module Webgen
       # Check if the node alcn or the destination path, which would be created by #create_node for
       # the given paths, exists.
       def node_exists?(path, dest_path)
-        @website.tree[path.alcn] || (!path.meta_info['no_output'] && @website.tree[dest_path, :dest_path])
+        @website.tree[path.alcn] || (!path.meta_info['no_output'] && @website.tree.node(dest_path, :dest_path))
       end
       protected :node_exists?
 
+      # Retrieve the node class that should be used for the given path.
+      def node_class(path)
+        if String === (klass = path.meta_info['node_class'])
+          Webgen::Utils.const_for_name(klass) rescue Node
+        elsif String === (klass = path.meta_info['base_node_class'])
+          Webgen::Utils.const_for_name(klass) rescue Node
+        else
+          Node
+        end
+      end
+      protected :node_class
+
     end
 
   end