webgen 0.5.17 → 1.0.0.beta1

data/lib/webgen/extension_manager.rb

@@ -0,0 +1,121 @@
+# -*- encoding: utf-8 -*-
+
+require 'ostruct'
+require 'webgen/utils'
+require 'webgen/error'
+
+module Webgen
+
+  # Provides common functionality for extension manager classes.
+  #
+  # This module is intended for mixing into an extension manager class. An example for an extension
+  # manage class is the Webgen::ContentProcessor class which manages all content processors.
+  # Extension manager classes provide methods for registering a certain type of extension and
+  # invoking methods on them via a common interface.
+  #
+  # It is assumed that one wants to associate one or more names with an extension object.
+  module ExtensionManager
+
+    # Create a new extension manager.
+    def initialize
+      @extensions = {}
+    end
+
+    def initialize_copy(orig) #:nodoc:
+      super
+      @extensions = {}
+      orig.instance_eval { @extensions }.each {|k,v| @extensions[k] = v.clone}
+    end
+
+    # Register a new extension.
+    #
+    # **Note** that this method has to be implemented by classes that include this module. It should
+    # register one or more names for an extension object by associating the names with the extension
+    # object data (should be an object that responds at least to :object) via the @extensions hash.
+    #
+    # The simplest way to achieve this is to use the #do_register method.
+    def register(klass, options = {}, &block)
+      raise NotImplementedError
+    end
+
+    # Automatically perform the necessary steps to register the extension +klass+. This involves
+    # normalization of the class name and associating the extension name (derived from the class
+    # name if not set via the key :name in the options hash) with the extension.
+    #
+    # The parameter +klass+ can either be a String or a Class specifying the class that should be
+    # registered.
+    #
+    # The parameter +options+ allows to associate additional information with an extension. The only
+    # recognized key is :name (for the extension name). All other keys are ignored and can/should be
+    # used by the extension manager class itself.
+    #
+    # The parameter +allow_block+ specifies whether the extension manager allows blocks as
+    # extensions. If this parameter is +true+ and a block is provided, the +klass+ parameter is
+    # not used!
+    #
+    # Returns the (possibly automatically generated) name for the extension.
+    def do_register(klass, options = {}, allow_block = true, &block)
+      if !allow_block && block_given?
+        raise ArgumentError, "The extension manager '#{self.class.name}' does not support blocks on #register"
+      end
+      klass, klass_name = normalize_class_name(klass, !block_given?)
+      name = (options[:name] || Webgen::Utils.snake_case(klass_name)).to_sym
+      @extensions[name] = OpenStruct.new(:object => (block_given? ? block : klass))
+      name
+    end
+    private :do_register
+
+    # Return a complete class name (including the hierarchy part) based on +klass+ and the class
+    # name without the hierarchy part.
+    #
+    # If the parameter +do_autoload+ is +true+ and the +klass+ is defined under this class, it is
+    # autoloaded by turning the class name into a path name (See Webgen::Utils.snake_case).
+    def normalize_class_name(klass, do_autoload = true)
+      klass = (klass.kind_of?(Class) || klass.include?('::') ? klass : "#{self.class.name}::#{klass}")
+      klass_name = klass.to_s.split(/::/).last
+      if do_autoload && klass.to_s.start_with?(self.class.name) && klass_name =~ /^[A-Z]/
+        self.class.autoload(klass_name.to_sym, Webgen::Utils.snake_case(klass.to_s))
+      end
+      [klass, klass_name]
+    end
+    private :normalize_class_name
+
+    # Return the registered object for the extension +name+.
+    #
+    # This method also works in the case that +name+ is a String referencing a class. The method
+    # assumes that @extensions[name] is an array where the registered object is the first element!
+    def extension(name)
+      raise Webgen::Error.new("No extension called '#{name}' registered for the '#{self.class.name}' extension manager") unless registered?(name)
+      name = name.to_sym
+      ext = @extensions[name].object
+      ext.kind_of?(String) ? @extensions[name].object = resolve_class(ext) : ext
+    end
+    private :extension
+
+    # Return the extension data for the extension +name+.
+    def ext_data(name)
+      @extensions[name.to_sym]
+    end
+    private :ext_data
+
+    # If +class_or_name+ is a String, it is taken as the name of a class and is resolved. Else
+    # returns +class_or_name+.
+    def resolve_class(class_or_name)
+      String === class_or_name ? Webgen::Utils.const_for_name(class_or_name) : class_or_name
+    end
+    private :resolve_class
+
+    # Return +true+ if an extension with the given name has been registered with this manager
+    # class.
+    def registered?(name)
+      @extensions.has_key?(name.to_sym)
+    end
+
+    # Return the meta data of all extensions registered with this manager class.
+    def registered_extensions
+      @extensions.dup
+    end
+
+  end
+
+end

data/lib/webgen/item_tracker.rb

@@ -0,0 +1,237 @@
+# -*- encoding: utf-8 -*-
+
+require 'set'
+require 'webgen/extension_manager'
+
+module Webgen
+
+  # Namespace for all item trackers.
+  #
+  # == About
+  #
+  # This extension manager class is used to track various "items". Such items can be added as a
+  # dependency to a node and later be checked if they have changed. This allows webgen to
+  # conditionally render a node.
+  #
+  # An item can basically be anything, there only has to be an item tracker extension that knows how
+  # to handle it. Each item tracker extension is uniquely identified by its name (e.g.
+  # :+node_content+, :+node_meta_info+, ...).
+  #
+  # == Implementing an item tracker.
+  #
+  # An item tracker extension class must respond to the following methods:
+  #
+  # [initialize(website)]
+  #   Initializes the extension and provides the website object which can be used to resolve the
+  #   item ID to the referenced item or item data itself.
+  #
+  # [item_id(*item)]
+  #   Return the unique ID for the given item. The returned ID has to be unique for this item
+  #   tracker extension
+  #
+  # [item_data(*item)]
+  #   Return the data for the item so that it can be correctly checked later if it has changed.
+  #
+  # [changed?(item_id, old_data)]
+  #   Return +true+ if the item identified by its unique ID has changed. The parameter +old_data+
+  #   contains the last known data of the item.
+  #
+  # [node_referenced?(item_id, old_data, node_alcn)]
+  #   Return +true+ if the node identified by +node_alcn+ is referenced in the old data identified
+  #   by the unique ID.
+  #
+  # The parameter +item+ for the methods +item_id+ and +item_data+ contains the information needed
+  # to identify the item and is depdendent on the specific item tracker extension class. Therefore
+  # you need to look at the documentation for an item tracker extension to see what it expects as
+  # the item.
+  #
+  # Since these methods are invoked multiple times for different items, these methods should have no
+  # side effects.
+  #
+  # == Sample item tracker
+  #
+  # The following sample item tracker tracks changes in configuration values. It needs the
+  # configuration option name as item.
+  #
+  #   class ConfigTracker
+  #
+  #     def initialize(website)
+  #       @website = website
+  #     end
+  #
+  #     def item_id(config_key)
+  #       config_key
+  #     end
+  #
+  #     def item_data(config_key)
+  #       @website.config[config_key]
+  #     end
+  #
+  #     def changed?(config_key, old_val)
+  #       @website.config[config_key] != old_val
+  #     end
+  #
+  #     def node_referenced?(config_key, config_value, node_alcn)
+  #       false
+  #     end
+  #
+  #   end
+  #
+  #   website.ext.item_tracker.register ConfigTracker, name: :config
+  #
+  class ItemTracker
+
+    include Webgen::ExtensionManager
+
+    # Create a new item tracker for the given website.
+    def initialize(website)
+      super()
+      @instances = {}
+      @node_dependencies = Hash.new {|h,k| h[k] = Set.new}
+      @item_data = {}
+      @cached = {:node_dependencies => {}, :item_data => {}}
+      @written_nodes = []
+      @checked_nodes = Set.new
+
+      @website = website
+
+      @item_changed = {}
+
+      @website.blackboard.add_listener(:website_initialized, self) do
+        @cached = @website.cache[:item_tracker_data] || @cached
+      end
+
+      @website.blackboard.add_listener(:after_tree_populated, self) do |node|
+        @item_data.keys.each do |uid|
+          @item_data[uid] = item_tracker(uid.first).item_data(*uid.last)
+        end
+      end
+
+      @website.blackboard.add_listener(:before_all_nodes_written, self) do
+        # make all used item data from the previous pass current again if applicable
+        @written_nodes.each do |node|
+          next unless @website.tree[node.alcn]
+          @node_dependencies[node.alcn].each do |uid|
+            @item_data[uid] = item_tracker(uid.first).item_data(*uid.last)
+          end
+        end
+        @written_nodes = []
+        @item_changed = {}
+      end
+
+      @website.blackboard.add_listener(:after_node_written, self) do |node|
+        @written_nodes << node
+      end
+
+      @website.blackboard.add_listener(:after_all_nodes_written, self) do
+        # update cached data with data from the run
+        @written_nodes.each do |node|
+          next unless @website.tree[node.alcn]
+          @cached[:node_dependencies][node.alcn] = @node_dependencies[node.alcn]
+          @node_dependencies[node.alcn].each {|uid| @cached[:item_data][uid] = @item_data[uid]}
+        end
+      end
+
+      @website.blackboard.add_listener(:website_generated, self) do
+        @cached[:node_dependencies].reject! {|alcn, data| !@website.tree[alcn]}
+        @cached[:item_data].merge!(@item_data)
+        @cached[:item_data].reject! do |uid, _|
+          !@cached[:node_dependencies].find {|alcn, data| data.include?(uid)}
+        end
+        @website.cache[:item_tracker_data] = @cached
+      end
+    end
+
+    # Register an item tracker.
+    #
+    # The parameter +klass+ has to contain the name of the item tracker class or the class object
+    # itself. If the class is located under this namespace, only the class name without the
+    # hierarchy part is needed, otherwise the full class name including parent module/class names is
+    # needed.
+    #
+    # === Options:
+    #
+    # [:name] The name for the item tracker class. If not set, it defaults to the snake-case version
+    #         (i.e. FileSystem → file_system) of the class name (without the hierarchy part). It
+    #         should only contain letters.
+    #
+    # === Examples:
+    #
+    #   item_tracker.register('Node')   # registers Webgen::ItemTracker::Node
+    #
+    #   item_tracker.register('::Node') # registers Node !!!
+    #
+    #   item_tracker.register('MyModule::Doit', name: 'infos')
+    #
+    def register(klass, options={}, &block)
+      do_register(klass, options, false, &block)
+    end
+
+    # Add the given item that is handled by the item tracker extension +name+ as a dependency to the
+    # node.
+    def add(node, name, *item)
+      uid = unique_id(name, item)
+      @node_dependencies[node.alcn] << uid
+      @item_data[uid] ||= item_tracker(name).item_data(*uid.last)
+    end
+
+    # Return +true+ if the given node has changed.
+    def node_changed?(node)
+      return false if @checked_nodes.include?(node)
+      @checked_nodes << node
+      !@cached[:node_dependencies].has_key?(node.alcn) ||
+        @cached[:node_dependencies][node.alcn].any? {|uid| item_changed_by_uid?(uid)}
+    ensure
+      @checked_nodes.delete(node)
+    end
+
+    # Return +true+ if the given node has been referenced by any item tracker extension.
+    def node_referenced?(node)
+      node_alcn = node.alcn
+      checked_uids = Set.new
+      @cached[:node_dependencies].each do |alcn, uids|
+        next if alcn == node_alcn
+        uids.each do |uid|
+          next if checked_uids.include?(uid)
+          checked_uids << uid
+          return true if item_tracker(uid.first).node_referenced?(uid.last, @cached[:item_data][uid], node_alcn)
+        end
+      end
+      false
+    end
+
+    # Return +true+ if the given item that is handled by the item tracker extension +name+ has
+    # changed.
+    def item_changed?(name, *item)
+      item_changed_by_uid?(unique_id(name, item))
+    end
+
+    #######
+    private
+    #######
+
+    # Return +true+ if the given item has changed. See #add for a description of the item
+    # parameters.
+    def item_changed_by_uid?(uid)
+      return @item_changed[uid] if @item_changed.has_key?(uid)
+      @item_changed[uid] = if !@cached[:item_data].has_key?(uid)
+                             true
+                           else
+                             item_tracker(uid.first).changed?(uid.last, @cached[:item_data][uid])
+                           end
+    end
+
+    # Return the unique ID for the given item handled by the item tracker extension object specified
+    # by name.
+    def unique_id(name, item)
+      [name.to_sym, item_tracker(name).item_id(*item)]
+    end
+
+    # Return the item tracker extension object called name.
+    def item_tracker(name)
+      @instances[name] ||= extension(name).new(@website)
+    end
+
+  end
+
+end

data/lib/webgen/item_tracker/file.rb

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/item_tracker'
+
+module Webgen
+  class ItemTracker
+
+    # This class is used to track changes to a file.
+    #
+    # The item for this tracker is the name of the file, i.e. add an item like this:
+    #
+    #   website.ext.item_tracker.add(some_node, :file, '/home/me/file.jpg')
+    #
+    class File
+
+      def initialize(website) #:nodoc:
+        @website = website
+      end
+
+      def item_id(filename) #:nodoc:
+        filename
+      end
+
+      def item_data(filename) #:nodoc:
+        ::File.mtime(filename)
+      end
+
+      def changed?(filename, old_mtime) #:nodoc:
+        ::File.mtime(filename) > old_mtime
+      end
+
+      def node_referenced?(filename, mtime, node_alcn) #:nodoc:
+        false
+      end
+
+    end
+
+  end
+end

data/lib/webgen/item_tracker/missing_node.rb

@@ -0,0 +1,61 @@
+# -*- encoding: utf-8 -*-
+
+require 'webgen/item_tracker'
+
+module Webgen
+  class ItemTracker
+
+    # This class is used to track unresolved absolute node paths.
+    #
+    # The item for this tracker is the unresolved absolute node path and, optionally, a language.
+    #
+    # For example:
+    #
+    #   website.ext.item_tracker.add(some_node, :missing_node, '/dir/missing.html')
+    #   website.ext.item_tracker.add(some_node, :missing_node, '/dir/missing.html', 'de')
+    #
+    class MissingNode
+
+      def initialize(website) #:nodoc:
+        @website = website
+        @at_least_one_node_created = true
+        @stop_reporting = false
+
+        @website.blackboard.add_listener(:after_node_created, self) do
+          @at_least_one_node_created = true
+        end
+        @website.blackboard.add_listener(:after_all_nodes_written, self) do
+          if @at_least_one_node_created
+            @at_least_one_node_created = false
+          else
+            @stop_reporting = true
+          end
+        end
+        @website.blackboard.add_listener(:website_generated, self) do
+          @at_least_one_node_created = true
+          @stop_reporting = false
+        end
+      end
+
+      def item_id(path, lang = nil) #:nodoc:
+        [path, lang]
+      end
+
+      def item_data(path, lang) #:nodoc:
+        @website.tree.resolve_node(path, lang).nil?
+      end
+
+      def changed?(iid, old_data) #:nodoc:
+        return false if @stop_reporting
+        missing = item_data(*iid)
+        missing || missing != old_data
+      end
+
+      def node_referenced?(iid, missing, node_alcn) #:nodoc:
+        iid.first == node_alcn
+      end
+
+    end
+
+  end
+end