nanoc3 3.1.9 → 3.2.0a1

data/lib/nanoc3/base/errors.rb

@@ -14,7 +14,7 @@ module Nanoc3
     class UnknownDataSource < Generic
 
       # @param [String] data_source_name The data source name for which no
-      # data source could be found
+      #   data source could be found
       def initialize(data_source_name)
         super("The data source specified in the site’s configuration file, “#{data_source_name}”, does not exist.".make_compatible_with_env)
       end
@@ -26,7 +26,7 @@ module Nanoc3
     class UnknownLayout < Generic
 
       # @param [String] layout_identifier The layout identifier for which no
-      # layout could be found
+      #   layout could be found
       def initialize(layout_identifier)
         super("The site does not have a layout with identifier “#{layout_identifier}”.".make_compatible_with_env)
       end
@@ -38,7 +38,7 @@ module Nanoc3
     class UnknownFilter < Generic
 
       # @param [Symbol] filter_name The filter name for which no filter could
-      # be found
+      #   be found
       def initialize(filter_name)
         super("The requested filter, “#{filter_name}”, does not exist.".make_compatible_with_env)
       end
@@ -51,7 +51,7 @@ module Nanoc3
     class CannotDetermineFilter < Generic
 
       # @param [String] layout_identifier The identifier of the layout for
-      # which the filter could not be determined
+      #   which the filter could not be determined
       def initialize(layout_identifier)
         super("The filter to be used for the “#{layout_identifier}” layout could not be determined. Make sure the layout does have a filter.".make_compatible_with_env)
       end
@@ -63,12 +63,12 @@ module Nanoc3
     class DataNotYetAvailable < Generic
 
       # @param [String] type The name of the data type that is not yet
-      # available. For example: `"site"`, `"items"`.
+      #   available. For example: `"site"`, `"items"`.
       #
       # @param [Boolean] plural True if the given type is plural, false
-      # otherwise. This only has an effect on the exception message. For
-      # example, if the given type is `"site"`, plural would be `false`; if
-      # the given type is `"items"`, plural would be `true`.
+      #   otherwise. This only has an effect on the exception message. For
+      #   example, if the given type is `"site"`, plural would be `false`; if
+      #   the given type is `"items"`, plural would be `true`.
       def initialize(type, plural)
         super("#{type} #{plural ? 'are' : 'is'} not available yet. You may be missing a Nanoc3::Site#load_data call.".make_compatible_with_env)
       end
@@ -80,7 +80,7 @@ module Nanoc3
     class RecursiveCompilation < Generic
 
       # @param [Array<Nanoc3::ItemRep>] reps A list of item representations
-      # that mutually depend on each other
+      #   that mutually depend on each other
       def initialize(reps)
         super("The site cannot be compiled because the following items mutually depend on each other: #{reps.inspect}.".make_compatible_with_env)
       end
@@ -102,7 +102,7 @@ module Nanoc3
     class NoMatchingCompilationRuleFound < Generic
 
       # @param [Nanoc3::Item] item The item for which no compilation rule
-      # could be found
+      #   could be found
       def initialize(item)
         super("No compilation rules were found for the “#{item.identifier}” item.".make_compatible_with_env)
       end
@@ -114,7 +114,7 @@ module Nanoc3
     class NoMatchingRoutingRuleFound < Generic
 
       # @param [Nanoc3::Item] item The item for which no routing rule could be
-      # found
+      #   found
       def initialize(rep)
         super("No routing rules were found for the “#{rep.item.identifier}” item (rep “#{rep.name}”).".make_compatible_with_env)
       end
@@ -126,11 +126,11 @@ module Nanoc3
     class UnmetDependency < Generic
 
       # @return [Nanoc3::ItemRep] The item representation that cannot yet be
-      # compiled
+      #   compiled
       attr_reader :rep
 
       # @param [Nanoc3::ItemRep] The item representation that cannot yet be
-      # compiled
+      #   compiled
       def initialize(rep)
         @rep = rep
         super("The current item cannot be compiled yet because of an unmet dependency on the “#{rep.item.identifier}” item (rep “#{rep.name}”).".make_compatible_with_env)
@@ -142,7 +142,7 @@ module Nanoc3
     class CannotLayoutBinaryItem < Generic
 
       # @param [Nanoc3::ItemRep] The item representation that was attempted to
-      # be laid out
+      #   be laid out
       def initialize(rep)
         super("The “{rep.item.identifier}” item (rep “#{rep.name}”) cannot be laid out because it is a binary item. If you are getting this error for an item that should be textual instead of binary, make sure that its extension is included in the text_extensions array in the site configuration.".make_compatible_with_env)
       end
@@ -154,7 +154,7 @@ module Nanoc3
     class CannotUseTextualFilter < Generic
 
       # @param [Nanoc3::ItemRep] rep The item representation that was
-      # attempted to be filtered
+      #   attempted to be filtered
       #
       # @param [Class] filter_class The filter class that was used
       def initialize(rep, filter_class)
@@ -168,7 +168,7 @@ module Nanoc3
     class CannotUseBinaryFilter < Generic
 
       # @param [Nanoc3::ItemRep] rep The item representation that was
-      # attempted to be filtered
+      #   attempted to be filtered
       #
       # @param [Class] filter_class The filter class that was used
       def initialize(rep, filter_class)
@@ -177,6 +177,10 @@ module Nanoc3
 
     end
 
+    # Error that is raised when an internal consistency error is detected.
+    class InternalConsistency < Generic
+    end
+
   end
 
 end

data/lib/nanoc3/base/item.rb

@@ -13,78 +13,71 @@ module Nanoc3
     # @return [Hash] This item's attributes
     attr_accessor :attributes
 
-    # A string that uniquely identifies an item in a site.
-    #
-    # Identifiers start and end with a slash. They are comparable to paths on
-    # the filesystem, with the difference that file system paths usually do
-    # not have a trailing slash. The item hierarchy (parent and children of
-    # items) is determined by the item identifier.
-    #
-    # The root page (the home page) has the identifier “/”, which means
-    # that it is the ancestor of all other items.
-    #
     # @return [String] This item's identifier
     attr_accessor :identifier
 
-    # @return [Time] The time when this item was last modified
+    # @return [Time] The time where this item was last modified
     attr_reader   :mtime
 
+    # @return [String] The checksum of this item that was in effect during the
+    #   previous site compilation
+    attr_accessor :old_checksum
+
+    # @return [String] The current, up-to-date checksum of this item
+    attr_reader   :new_checksum
+
     # @return [Array<Nanoc3::ItemRep>] This item’s list of item reps
     attr_reader   :reps
 
     # @return [String] This item's raw, uncompiled content of this item (only
-    # available for textual items)
+    #   available for textual items)
     attr_reader   :raw_content
 
     # @return [String] The filename pointing to the file containing this
-    # item’s content (only available for binary items)
+    #   item’s content (only available for binary items)
     attr_reader   :raw_filename
 
     # @return [Nanoc3::Item, nil] The parent item of this item. This can be
-    # nil even for non-root items.
+    #   nil even for non-root items.
     attr_accessor :parent
 
     # @return [Array<Nanoc3::Item>] The child items of this item
     attr_accessor :children
 
     # @return [Boolean] Whether or not this item is outdated because of its
-    # dependencies are outdated
+    #   dependencies are outdated
     attr_accessor :outdated_due_to_dependencies
     alias_method :outdated_due_to_dependencies?, :outdated_due_to_dependencies
 
     # Creates a new item with the given content or filename, attributes and
     # identifier.
     #
-    # Note that the API in 3.1 has changed a bit since 3.0; the API remains
-    # backwards compatible, however. Passing the modification time as the 4th
-    # parameter is deprecated; pass it as the `:mtime` method option instead.
-    #
     # @param [String] raw_content_or_raw_filename The uncompiled item content
-    # (if it is a textual item) or the path to the filename containing the
-    # content (if it is a binary item).
+    #   (if it is a textual item) or the path to the filename containing the
+    #   content (if it is a binary item).
     #
     # @param [Hash] attributes A hash containing this item's attributes.
     #
     # @param [String] identifier This item's identifier.
     #
-    # @param [Time, Hash, nil] params_or_mtime Extra parameters for the item,
-    # or the time when this item was last modified (deprecated).
-    #
-    # @option params_or_mtime [Time, nil] :mtime (nil) The time when this item
-    # was last modified
-    #
-    # @option params_or_mtime [Symbol, nil] :binary (true) Whether or not this
-    # item is binary
-    def initialize(raw_content_or_raw_filename, attributes, identifier, params_or_mtime=nil)
-      # Get params and mtime
-      # TODO [in nanoc 4.0] clean this up
-      if params_or_mtime.nil? || params_or_mtime.is_a?(Time)
-        params = {}
-        @mtime = params_or_mtime
-      elsif params_or_mtime.is_a?(Hash)
-        params = params_or_mtime
-        @mtime = params[:mtime]
-      end
+    # @param [Time, Hash] params Extra parameters. For backwards
+    #   compatibility, this can be a Time instance indicating the time when
+    #   this item was last modified (mtime).
+    #
+    # @option params [Time, nil] :mtime (nil) The time when this item was last
+    #   modified
+    #
+    # @option params [Symbol, nil] :binary (true) Whether or not this item is
+    #   binary
+    #
+    # @option params [String, nil] :checksum (nil) The current, up-to-date
+    #   checksum of this item
+    def initialize(raw_content_or_raw_filename, attributes, identifier, params=nil)
+      # Get mtime and checksum
+      params ||= {}
+      params = { :mtime => params } if params.is_a?(Time)
+      @new_checksum = params[:checksum]
+      @mtime        = params[:mtime]
 
       # Get type and raw content or raw filename
       @is_binary = params.has_key?(:binary) ? params[:binary] : false
@@ -96,7 +89,7 @@ module Nanoc3
 
       # Get rest of params
       @attributes   = attributes.symbolize_keys
-      @identifier   = identifier.cleaned_identifier.freeze
+      @identifier   = identifier.cleaned_identifier
 
       @parent       = nil
       @children     = []
@@ -118,17 +111,17 @@ module Nanoc3
     # content easier.
     #
     # @option params [String] :rep (:default) The name of the representation
-    # from which the compiled content should be fetched. By default, the
-    # compiled content will be fetched from the default representation.
+    #   from which the compiled content should be fetched. By default, the
+    #   compiled content will be fetched from the default representation.
     #
     # @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).
+    #   fetch the compiled content. By default, the returned compiled content
+    #   will be the content compiled right before the first layout call (if
+    #   any).
     #
     # @return [String] The compiled content of the given rep (or the default
-    # rep if no rep is specified) at the given snapshot (or the default
-    # snapshot if no snapshot is specified)
+    #   rep if no rep is specified) at the given snapshot (or the default
+    #   snapshot if no snapshot is specified)
     #
     # @see ItemRep#compiled_content
     def compiled_content(params={})
@@ -148,11 +141,11 @@ module Nanoc3
     # method that makes fetching the path of a rep easier.
     #
     # @option params [String] :rep (:default) The name of the representation
-    # from which the path should be fetched. By default, the path will be
-    # fetched from the default representation.
+    #   from which the path should be fetched. By default, the path will be
+    #   fetched from the default representation.
     #
     # @return [String] The path of the given rep ( or the default rep if no
-    # rep is specified)
+    #   rep is specified)
     def path(params={})
       rep_name = params[:rep] || :default
 
@@ -201,6 +194,21 @@ module Nanoc3
       @reps.any? { |r| r.outdated? }
     end
 
+    # Returns the type of this object. Will always return `:item`, because
+    # this is an item. For layouts, this method returns `:layout`.
+    #
+    # @return [Symbol] :item
+    def type
+      :item
+    end
+
+    # Returns an object that can be used for uniquely identifying objects.
+    #
+    # @return [Object] An unique reference to this object
+    def reference
+      [ type, self.identifier ]
+    end
+
     def inspect
       "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier} binary?=#{self.binary?}>"
     end