nanoc3 3.0.9 → 3.1.0a1

data/lib/nanoc3/base/item_rep.rb

@@ -2,70 +2,73 @@
 
 module Nanoc3
 
-  # A Nanoc3::ItemRep is a single representation (rep) of an item
-  # (Nanoc3::Item). An item can have multiple representations. A representation
-  # has its own output file. A single item can therefore have multiple output
-  # files, each run through a different set of filters with a different
-  # layout.
+  # A single representation (rep) of an item ({Nanoc3::Item}). An item can
+  # have multiple representations. A representation has its own output file.
+  # A single item can therefore have multiple output files, each run through
+  # a different set of filters with a different layout.
   #
   # An item representation is observable. The following events will be
   # notified:
   #
-  # * :compilation_started
-  # * :compilation_ended
-  # * :filtering_started
-  # * :filtering_ended
+  # * `:compilation_started`
+  # * `:compilation_ended`
+  # * `:filtering_started`
+  # * `:filtering_ended`
   #
   # The compilation-related events have one parameters (the item
   # representation); the filtering-related events have two (the item
   # representation, and a symbol containing the filter class name).
   class ItemRep
 
-    # The item (Nanoc3::Item) to which this representation belongs.
+    # @return [Nanoc3::Item] The item to which this rep belongs
     attr_reader   :item
 
-    # This item representation's unique name.
+    # @return [Symbol] The representation's unique name
     attr_reader   :name
 
-    # Indicates whether this rep is forced to be dirty by the user.
+    # @return [Boolean] true if this rep is forced to be dirty (e.g. because
+    #   of the `--force` commandline option); false otherwise
     attr_accessor :force_outdated
 
-    # Indicates whether this rep's output file has changed the last time it
-    # was compiled.
+    # @return [Boolean] true if this rep’s output file has changed since the
+    #   last time it was compiled; false otherwise
     attr_accessor :modified
     alias_method :modified?, :modified
 
-    # Indicates whether this rep's output file was created the last time it
-    # was compiled.
+    # @return [Boolean] true if this rep’s output file was created during the
+    #   current or last compilation session; false otherwise
     attr_accessor :created
     alias_method :created?, :created
 
-    # Indicates whether this rep has already been compiled.
+    # @return [Boolean] true if this representation has already been
+    #   compiled during the current or last compilation session; false
+    #   otherwise
     attr_accessor :compiled
     alias_method :compiled?, :compiled
 
-    # Indicates whether this rep's compiled content has been written during
-    # the current or last compilation session.
+    # @return [Boolean] true if this representation’s compiled content has
+    #   been written during the current or last compilation session; false
+    #   otherwise
     attr_reader :written
     alias_method :written?, :written
 
-    # The item rep's path, as used when being linked to. It starts with a
-    # slash and it is relative to the output directory. It does not include
-    # the path to the output directory. It will not include the filename if
-    # the filename is an index filename.
+    # @return [String] The item rep's path, as used when being linked to. It
+    #   starts with a slash and it is relative to the output directory. It
+    #   does not include the path to the output directory. It will not include
+    #   the filename if the filename is an index filename.
     attr_accessor :path
 
-    # The item rep's raw path. It is relative to the current working directory
-    # and includes the path to the output directory. It also includes the
-    # filename, even if it is an index filename.
+    # @return [String] The item rep's raw path. It is relative to the current
+    #   working directory and includes the path to the output directory. It
+    #   also includes the filename, even if it is an index filename.
     attr_accessor :raw_path
 
     # Creates a new item representation for the given item.
     #
-    # +item+:: The item (Nanoc3::Item) to which the new representation will
-    #          belong.
+    # @param [Nanoc3::Item] item The item to which the new representation will
+    #   belong.
     #
-    # +name+:: The unique name for the new item representation.
+    # @param [Symbol] name The unique name for the new item representation.
     def initialize(item, name)
       # Set primary attributes
       @item = item
@@ -77,6 +80,7 @@ module Nanoc3
         :last => @item.raw_content,
         :pre  => @item.raw_content
       }
+      @old_content = nil
 
       # Reset flags
       @compiled       = false
@@ -86,8 +90,8 @@ module Nanoc3
       @force_outdated = false
     end
 
-    # Returns true if this item rep's output file is outdated and must be
-    # regenerated, false otherwise.
+    # @return [Boolean] true if this item rep's output file is outdated and
+    #   must be regenerated, false otherwise
     def outdated?
       # Outdated if we don't know
       return true if @item.mtime.nil?
@@ -126,7 +130,8 @@ module Nanoc3
       return false
     end
 
-    # Returns the assignments that should be available when compiling the content.
+    # @return [Hash] The assignments that should be available when compiling
+    #   the content.
     def assigns
       {
         :content    => @content[:last],
@@ -139,22 +144,54 @@ module Nanoc3
       }
     end
 
-    # Returns the item representation content at the given snapshot.
+    # Returns the compiled content from a given snapshot.
     #
-    # +snapshot+:: The snapshot from which the content should be fetched. To
-    #              get the raw, uncompiled content, use +:raw+.
-    def content_at_snapshot(snapshot=:pre)
+    # @option params [String] :snapshot The name of the snapshot from
+    #   which to fetch the compiled content. By default, the returned compiled
+    #   content will be the content compiled right before the first layout
+    #   call (if any).
+    def compiled_content(params={})
+      # Notify
       Nanoc3::NotificationCenter.post(:visit_started, self.item)
       Nanoc3::NotificationCenter.post(:visit_ended,   self.item)
 
+      # Debug
       puts "*** Attempting to fetch content for #{self.inspect}" if $DEBUG
 
+      # Require compilation
       raise Nanoc3::Errors::UnmetDependency.new(self) unless compiled?
 
-      @content[snapshot]
+      # Get name of last pre-layout snapshot
+      snapshot_name = params[:snapshot]
+      if @content[:pre]
+        snapshot_name ||= :pre
+      else
+        snapshot_name ||= :last
+      end
+
+      # Get content
+      @content[snapshot_name]
+    end
+
+    # @deprecated Use {Nanoc3::ItemRep#compiled_content} instead.
+    def content_at_snapshot(snapshot=:pre)
+      compiled_content(:snapshot => snapshot)
     end
 
     # Runs the item content through the given filter with the given arguments.
+    # This method will replace the content of the `:last` snapshot with the
+    # filtered content of the last snapshot.
+    #
+    # This method is supposed to be called only in a compilation rule block
+    # (see {Nanoc3::CompilerDSL#compile}).
+    #
+    # @param [Symbol] filter_name The name of the filter to run the item
+    #   representations' content through
+    #
+    # @param [Hash] filter_args The filter arguments that should be passed to
+    #   the filter's #run method
+    #
+    # @return [void]
     def filter(filter_name, filter_args={})
       # Create filter
       klass = Nanoc3::Filter.named(filter_name)
@@ -170,25 +207,24 @@ module Nanoc3
       snapshot(@content[:post] ? :post : :pre)
     end
 
-    # Lays out the item using the given layout.
+    # Lays out the item using the given layout. This method will replace the
+    # content of the `:last` snapshot with the laid out content of the last
+    # snapshot.
+    #
+    # This method is supposed to be called only in a compilation rule block
+    # (see {Nanoc3::CompilerDSL#compile}).
+    #
+    # @param [String] layout_identifier The identifier of the layout the ite
+    #   should be laid out with
+    #
+    # @return [void]
     def layout(layout_identifier)
-      # Get layout
-      layout ||= @item.site.layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
-      raise Nanoc3::Errors::UnknownLayout.new(layout_identifier) if layout.nil?
-
-      # Get filter
-      filter_name, filter_args  = @item.site.compiler.filter_for_layout(layout)
-      raise Nanoc3::Errors::CannotDetermineFilter.new(layout_identifier) if filter_name.nil?
-
-      # Get filter class
-      filter_class = Nanoc3::Filter.named(filter_name)
-      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
+      # Create "pre" snapshot
+      snapshot(:pre) unless @content[:pre]
 
       # Create filter
-      filter = filter_class.new(assigns.merge({ :layout => layout }))
-
-      # Create "pre" snapshot
-      snapshot(:pre)
+      layout = layout_with_identifier(layout_identifier)
+      filter, filter_name, filter_args = filter_for_layout(layout)
 
       # Layout
       @item.site.compiler.stack.push(layout)
@@ -202,11 +238,20 @@ module Nanoc3
     end
 
     # Creates a snapshot of the current compiled item content.
+    #
+    # @param [Symbol] snapshot_name The name of the snapshot to create
+    #
+    # @return [void]
     def snapshot(snapshot_name)
       @content[snapshot_name] = @content[:last]
     end
 
     # Writes the item rep's compiled content to the rep's output file.
+    #
+    # This method should not be called directly, even in a compilation block;
+    # the compiler is responsible for calling this method.
+    #
+    # @return [void]
     def write
       # Create parent directory
       FileUtils.mkdir_p(File.dirname(self.raw_path))
@@ -216,7 +261,7 @@ module Nanoc3
 
       # Remember old content
       if File.file?(self.raw_path)
-        old_content = File.read(self.raw_path)
+        @old_content = File.read(self.raw_path)
       end
 
       # Write
@@ -224,13 +269,79 @@ module Nanoc3
       @written = true
 
       # Check if file was modified
-      @modified = File.read(self.raw_path) != old_content
+      @modified = File.read(self.raw_path) != @old_content
+    end
+
+    # Creates and returns a diff between the compiled content before the
+    # current compilation session and the content compiled in the current
+    # compilation session.
+    #
+    # @return [String, nil] The difference between the old and new compiled
+    #   content in `diff(1)` format, or nil if there is no previous compiled
+    #   content
+    def diff
+      # Check if old content exists
+      if @old_content.nil? or self.raw_path.nil?
+        nil
+      else
+        diff_strings(@old_content, @content[:last])
+      end
     end
 
     def inspect
       "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} item.identifier=#{self.item.identifier}>"
     end
 
+  private
+
+    def layout_with_identifier(layout_identifier)
+      layout ||= @item.site.layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
+      raise Nanoc3::Errors::UnknownLayout.new(layout_identifier) if layout.nil?
+      layout
+    end
+
+    def filter_for_layout(layout)
+      # Get filter name and args
+      filter_name, filter_args  = @item.site.compiler.filter_for_layout(layout)
+      raise Nanoc3::Errors::CannotDetermineFilter.new(layout_identifier) if filter_name.nil?
+
+      # Get filter class
+      filter_class = Nanoc3::Filter.named(filter_name)
+      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
+
+      # Create filter
+      filter = filter_class.new(assigns.merge({ :layout => layout }))
+
+      # Done
+      [ filter, filter_name, filter_args ]
+    end
+
+    def diff_strings(a, b)
+      # TODO Rewrite this string-diffing method in pure Ruby. It should not
+      # use the "diff" executable, because this will most likely not work on
+      # operating systems without it, such as Windows.
+
+      require 'tempfile'
+      require 'open3'
+
+      # Create files
+      old_file = Tempfile.new('old')
+      new_file = Tempfile.new('new')
+
+      # Write files
+      old_file.write(a)
+      new_file.write(b)
+
+      # Diff
+      stdin, stdout, stderr = Open3.popen3('diff', '-u', old_file.path, new_file.path)
+      result = stdout.read
+      result == '' ? nil : result
+    rescue Errno::ENOENT
+      warn 'Failed to run `diff`, so no diff with the previously compiled ' \
+           'content will be available.'
+      nil
+    end
+
   end
 
 end

data/lib/nanoc3/base/layout.rb

@@ -2,36 +2,35 @@
 
 module Nanoc3
 
-  # A Nanoc3::Layout represents a layout in a nanoc site. It has content,
-  # attributes (for determining which filter to use for laying out an item),
-  # an identifier (because layouts are organised hierarchically), and a
-  # modification time (to speed up compilation).
+  # Represents a layout in a nanoc site. It has content, attributes, an
+  # identifier and a modification time (to speed up compilation).
   class Layout
 
-    # The Nanoc3::Site this layout belongs to.
+    # @return [Nanoc3::Site] The site this layout belongs to
     attr_accessor :site
 
-    # The raw content of this layout.
+    # @return [String] The raw content of this layout
     attr_reader :raw_content
 
-    # A hash containing this layout's attributes.
+    # @return [Hash] This layout's attributes
     attr_reader :attributes
 
-    # This layout's identifier, starting and ending with a slash.
+    # @return [String] This layout's identifier, starting and ending with a
+    #  slash
     attr_accessor :identifier
 
-    # The time when this layout was last modified.
+    # @return [Time] The time when this layout was last modified
     attr_reader :mtime
 
     # Creates a new layout.
     #
-    # +content+:: The raw content of this layout.
+    # @param [String] content The raw content of this layout.
     #
-    # +attributes+:: A hash containing this layout's attributes.
+    # @param [Hash] attributes A hash containing this layout's attributes.
     #
-    # +identifier+:: This layout's identifier.
+    # @param [String] identifier This layout's identifier.
     #
-    # +mtime+:: The time when this layout was last modified.
+    # @param [Time, nil] mtime The time when this layout was last modified.
     def initialize(raw_content, attributes, identifier, mtime=nil)
       @raw_content  = raw_content
       @attributes   = attributes.symbolize_keys
@@ -40,6 +39,10 @@ module Nanoc3
     end
 
     # Requests the attribute with the given key.
+    #
+    # @param [Symbol] key The name of the attribute to fetch.
+    #
+    # @return [Object] The value of the requested attribute.
     def [](key)
       @attributes[key]
     end

data/lib/nanoc3/base/notification_center.rb

@@ -2,10 +2,9 @@
 
 module Nanoc3
 
-  # Nanoc3::NotificationCenter provides a way to send notifications between
-  # objects. It allows blocks associated with a certain notification name to
-  # be registered; these blocks will be called when the notification with the
-  # given name is posted.
+  # Provides a way to send notifications between objects. It allows blocks
+  # associated with a certain notification name to be registered; these blocks
+  # will be called when the notification with the given name is posted.
   #
   # It is a slightly different implementation of the Observer pattern; the
   # table of subscribers is not stored in the observable object itself, but in
@@ -17,11 +16,17 @@ module Nanoc3
       # Adds the given block to the list of blocks that should be called when
       # the notification with the given name is received.
       #
-      # +name+:: The name of the notification that will be posted.
+      # @param [String, Symbol] name The name of the notification that will
+      #   cause the given block to be called.
       #
-      # +id+:: An identifier for the block. This is only used to be able to
-      #        remove the block (using the remove method) later. Defaults to
-      #        nil.
+      # @param [String, Symbol, nil] id An identifier for the block. This is
+      #   only used to be able to remove the block (using the remove method)
+      #   later. Can be nil, but this is not recommended because it prevents
+      #   the given notification block from being unregistered.
+      #
+      # @yield [*args] Will be executed with the arguments passed to {.post}
+      #
+      # @return [void]
       def on(name, id=nil, &block)
         initialize_if_necessary(name)
 
@@ -29,8 +34,15 @@ module Nanoc3
         @notifications[name] << { :id => id, :block => block }
       end
 
-      # Posts a notification with the given name. All arguments wil be passed
-      # to the blocks handling the notification.
+      # Posts a notification with the given name and the given arguments.
+      #
+      # @param [String, Symbol] name The name of the notification that should
+      #   be posted.
+      #
+      # @param args Arguments that wil be passed to the blocks handling the
+      #   notification.
+      #
+      # @return [void]
       def post(name, *args)
         initialize_if_necessary(name)
 
@@ -44,9 +56,13 @@ module Nanoc3
       # that should be called when the notification with the given name is
       # posted.
       #
-      # +name+:: The name of the notification that will be posted.
+      # @param [String, Symbol] name The name of the notification that should
+      #   no longer be registered.
+      #
+      # @param [String, Symbol] id The identifier of the block that should be
+      #   removed.
       #
-      # +id+:: The identifier of the block that should be removed.
+      # @return [void]
       def remove(name, id)
         initialize_if_necessary(name)
 

data/lib/nanoc3/base/plugin_registry.rb

@@ -0,0 +1,158 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # The class responsible for keeping track of all loaded plugins, such as
+  # filters ({Nanoc3::Filter}), data sources ({Nanoc3::DataSource}) and VCSes
+  # ({Nanoc3::Extra::VCS}).
+  class PluginRegistry
+
+    # A module that contains class methods for plugins. It provides functions
+    # for setting identifiers, registering plugins and finding plugins. Plugin
+    # classes should extend this module.
+    module PluginMethods
+      # Sets the identifiers for this plugin.
+      #
+      # @param [Array<Symbol>] identifier A list of identifiers to assign to
+      #   this plugin.
+      #
+      # @return [void]
+      def identifiers(*identifiers)
+        register(self, *identifiers)
+      end
+
+      # Sets the identifier for this plugin.
+      #
+      # @param [Symbol] identifier An identifier to assign to this plugin.
+      #
+      # @return [void]
+      def identifier(identifier)
+        register(self, identifier)
+      end
+
+      # Registers the given class as a plugin with the given identifier.
+      #
+      # @param [Class, String] class_or_name The class to register, or a
+      #   string containing the class name to register.
+      #
+      # @param [Array<Symbol>] identifiers A list of identifiers to assign to
+      #   this plugin.
+      #
+      # @return [void]
+      def register(class_or_name, *identifiers)
+        Nanoc3::Plugin.register(self, class_or_name, *identifiers)
+      end
+
+      # Returns the plugin with the given name (identifier)
+      #
+      # @param [String] name The name of the plugin class to find
+      #
+      # @return [Class] The plugin class with the given name
+      def named(name)
+        Nanoc3::Plugin.find(self, name)
+      end
+
+    end
+
+    # Returns the shared {PluginRegistry} instance, creating it if none exists
+    # yet.
+    #
+    # @return [Nanoc3::PluginRegistry] The shared plugin registry
+    def self.instance
+      @instance ||= self.new
+    end
+
+    # Creates a new plugin registry. This should usually not be necessary; it
+    # is recommended to use the shared instance (obtained from
+    # {Nanoc3::PluginRegistry.instance}).
+    def initialize
+      @map = {}
+    end
+
+    # Registers the given class as a plugin.
+    #
+    # @param [Class] superclass The superclass of the plugin. For example:
+    #   {Nanoc3::Filter}, {Nanoc3::Extra::VCS}.
+    #
+    # @param [Class, String] class_or_name The class to register. This can be
+    #   a string, in which case it will be automatically converted to a proper
+    #   class at lookup. For example: `Nanoc3::Filters::ERB`,
+    #   `"Nanoc3::Filters::Haml"`.
+    #
+    # @param [Symbol] identifiers One or more symbols identifying the class.
+    #   For example: `:haml`, :`erb`.
+    #
+    # @return [void]
+    def register(superclass, class_or_name, *identifiers)
+      @map[superclass] ||= {}
+
+      identifiers.each do |identifier|
+        @map[superclass][identifier.to_sym] = class_or_name
+      end
+    end
+
+    # Finds the plugin that is a subclass of the given class and has the given
+    # name.
+    #
+    # @param [Symbol] name The name of the plugin to return
+    #
+    # @return [Class, nil] The plugin with the given name
+    def find(klass, name)
+      # Initialize
+      @map[klass] ||= {}
+
+      # Lookup
+      class_or_name = @map[klass][name.to_sym]
+
+      # Get class
+      if class_or_name.is_a?(String)
+        class_or_name.scan(/\w+/).inject(klass) { |memo, part| memo.const_get(part) }
+      else
+        class_or_name
+      end
+    end
+
+    # Returns a list of all plugins. The returned list of plugins is an array
+    # with array elements in the following format:
+    #
+    #     { :class => ..., :superclass => ..., :identifiers => ... }
+    #
+    # @return [Array<Hash>] A list of all plugins in the format described
+    def all
+      plugins = []
+      @map.each_pair do |superclass, submap|
+        submap.each_pair do |identifier, klass|
+          # Find existing plugin
+          existing_plugin = plugins.find do |p|
+            p[:class] == klass && p[:superclass] == superclass
+          end
+
+          if existing_plugin
+            # Add identifier to existing plugin
+            existing_plugin[:identifiers] << identifier
+            existing_plugin[:identifiers] = existing_plugin[:identifiers].sort_by { |s| s.to_s }
+          else
+            # Create new plugin
+            plugins << {
+              :class       => klass,
+              :superclass  => superclass,
+              :identifiers => [ identifier ]
+            }
+          end
+        end
+      end
+
+      plugins
+    end
+
+    # @deprecated Use {Nanoc3::PluginRegistry#find} instead
+    def named(name)
+      find(self, name)
+    end
+
+  end
+
+  # @deprecated Use {Nanoc3::PluginRegistry.instace} instead
+  Plugin = PluginRegistry.instance
+
+end

data/lib/nanoc3/base/rule.rb

@@ -2,19 +2,30 @@
 
 module Nanoc3
 
-  # Nanoc3::Rule contains the processing information for a item.
+  # Contains the processing information for a item.
   class Rule
 
-    # The regex that determines which items this rule can be applied to. This
-    # rule can be applied to items with a identifier matching this regex.
+    # @return [Regexp] The regex that determines which items this rule can be
+    #   applied to. This rule can be applied to items with a identifier
+    #   matching this regex.
     attr_reader :identifier_regex
 
-    # The name of the representation that will be compiled using this rule.
+    # @return [Symbol] The name of the representation that will be compiled
+    #   using this rule
     attr_reader :rep_name
 
-    # Creates a new item compilation rule with the given identifier regex, compiler
-    # and block. The block will be called during compilation with the item rep
-    # as its argument.
+    # Creates a new item compilation rule with the given identifier regex,
+    # compiler and block. The block will be called during compilation with the
+    # item rep as its argument.
+    #
+    # @param [Regexp] identifier_regex A regular expression that will be used
+    #   to determine whether this rule is applicable to certain items.
+    #
+    # @param [String, Symbol] rep_name The name of the item representation
+    #   where this rule can be applied to
+    #
+    # @param [Proc] block A block that will be called when matching items are
+    #   compiled
     def initialize(identifier_regex, rep_name, block)
       @identifier_regex = identifier_regex
       @rep_name         = rep_name.to_sym
@@ -22,12 +33,20 @@ module Nanoc3
       @block = block
     end
 
-    # Returns true if this rule can be applied to the given item rep.
+    # @param [Nanoc3::Item] item The item to check
+    #
+    # @return [Boolean] true if this rule can be applied to the given item
+    #   rep, false otherwise
     def applicable_to?(item)
       item.identifier =~ @identifier_regex
     end
 
     # Applies this rule to the given item rep.
+    #
+    # @param [Nanoc3::ItemRep] rep The item representation where this rule
+    #   should be applied to
+    #
+    # @return [void]
     def apply_to(rep)
       Nanoc3::RuleContext.new(rep).instance_eval &@block
     end