nanoc3 3.2.0a1 → 3.2.0a2

data/lib/nanoc3/base/{dependency_tracker.rb → compilation/dependency_tracker.rb}

@@ -21,29 +21,28 @@ module Nanoc3
   # Dependency information is stored in the `tmp/dependencies` file. This file
   # also contains a version number; when a dependencies file with an
   # incompatible version is found, it is ignored.
-  class DependencyTracker
-
-    # @return [String] The name of the file in which dependency information is
-    #   stored
-    attr_accessor :filename
+  class DependencyTracker < ::Nanoc3::Store
 
     # @return [Array<Nanoc3::Item, Nanoc3::Layout>] The list of items and
     #   layouts that are being tracked by the dependency tracker
     attr_reader :objects
 
-    # The version of the file format used to store dependencies.
-    STORE_VERSION = 3
+    # @return [Nanoc3::Compiler] The compiler that corresponds to this
+    #   dependency tracker
+    attr_accessor :compiler
 
     # Creates a new dependency tracker for the given items and layouts.
     #
     # @param [Array<Nanoc3::Item, Nanoc3::Layout>] objects The list of items
     #   and layouts whose dependencies should be managed
     def initialize(objects)
+      super('tmp/dependencies', 4)
+
       @objects = objects
 
-      @filename         = 'tmp/dependencies'
-      @graph            = Nanoc3::DirectedGraph.new([ nil ] + @objects)
+      @graph = Nanoc3::DirectedGraph.new([ nil ] + @objects)
       @previous_objects = []
+      @objects_outdated_due_to_dependencies = Set.new
     end
 
     # Starts listening for dependency messages (`:visit_started` and
@@ -77,6 +76,18 @@ module Nanoc3
       Nanoc3::NotificationCenter.remove(:visit_ended,   self)
     end
 
+    # Checks whether the given object is outdated due to dependencies, i.e.
+    # check whether there are other objects that are outdated that cause this
+    # object to be outdated.
+    #
+    # @param [Nanoc3::Item, Nanoc3::Layout] obj The object to check
+    #
+    # @return [Boolean] true if the given object is outdated due to
+    #   dependencies, false if not.
+    def outdated_due_to_dependencies?(obj)
+      @objects_outdated_due_to_dependencies.include?(obj)
+    end
+
     # Returns the direct dependencies for the given object.
     #
     # The direct dependencies of the given object include the items
@@ -94,20 +105,6 @@ module Nanoc3
       @graph.direct_predecessors_of(object).compact
     end
 
-    # Returns all dependencies (direct and indirect) for the given object.
-    #
-    # The dependencies of given object include the objects that, when
-    # outdated, will cause the given object to be marked as outdated.
-    #
-    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
-    #   fetch all direct and indirect predecessors
-    #
-    # @return [Array<Nanoc3::Item, Nanoc3::Layout>] The predecessors of the
-    #   given object
-    def predecessors_of(object)
-      @graph.predecessors_of(object).compact
-    end
-
     # Returns the direct inverse dependencies for the given object.
     #
     # The direct inverse dependencies of the given object include the objects
@@ -125,21 +122,6 @@ module Nanoc3
       @graph.direct_successors_of(object).compact
     end
 
-    # Returns all inverse dependencies (direct and indirect) for the given
-    # object.
-    #
-    # The inverse dependencies of the given object include the objects that
-    # will be marked as outdated when the given object is outdated.
-    #
-    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
-    #   fetch all direct and indirect successors
-    #
-    # @return [Array<Nanoc3::Item, Nanoc3::Layout>] The successors of the
-    #   given object
-    def successors_of(object)
-      @graph.successors_of(object).compact
-    end
-
     # Records a dependency from `src` to `dst` in the dependency graph. When
     # `dst` is oudated, `src` will also become outdated.
     #
@@ -156,71 +138,21 @@ module Nanoc3
       @graph.add_edge(dst, src) unless src == dst
     end
 
-    # Stores the dependency graph into the file specified by the {#filename}
-    # attribute.
-    #
-    # @return [void]
-    def store_graph
-      FileUtils.mkdir_p(File.dirname(self.filename))
-      store = PStore.new(self.filename)
-      store.transaction do
-        store[:version]  = STORE_VERSION
-        store[:vertices] = @graph.vertices.map { |obj| obj && obj.reference }
-        store[:edges]    = @graph.edges
-      end
-    end
-
-    # Loads the dependency graph from the file specified by the {#filename}
-    # attribute. This method will overwrite an existing dependency graph.
-    #
-    # @return [void]
-    def load_graph
-      # Create new graph
-      @graph = Nanoc3::DirectedGraph.new([ nil ] + @objects)
-
-      # Get store
-      return if !File.file?(self.filename)
-      store = PStore.new(self.filename)
-
-      # Load dependencies
-      store.transaction do
-        # Verify version
-        return if store[:version] != STORE_VERSION
-
-        # Load vertices
-        @previous_objects = store[:vertices].map do |reference|
-          @objects.find { |obj| reference == obj.reference }
-        end
-
-        # Load edges
-        store[:edges].each do |edge|
-          from_index, to_index = *edge
-          from, to = @previous_objects[from_index], @previous_objects[to_index]
-          @graph.add_edge(from, to)
-        end
-      end
-    end
-
     # Traverses the dependency graph and marks all objects that (directly or
     # indirectly) depend on an outdated object as outdated.
     #
     # @return [void]
     def propagate_outdatedness
       # Unmark everything
-      @objects.each { |o| o.outdated_due_to_dependencies = false }
+      @objects_outdated_due_to_dependencies.clear
 
       # Mark new objects as outdated
       added_objects = @objects - @previous_objects
-      added_objects.each { |o| o.outdated_due_to_dependencies = true }
-
-      # Mark successors of nil as outdated
-      self.successors_of(nil).each do |o|
-        o.outdated_due_to_dependencies = true
-      end
+      @objects_outdated_due_to_dependencies.merge(added_objects)
 
       # Mark successors of outdated objects as outdated
       require 'set'
-      unprocessed = @objects.select { |o| o.outdated? }
+      unprocessed = [ nil ] + @objects.select { |o| compiler.outdated?(o) }
       seen        = Set.new(unprocessed)
       until unprocessed.empty?
         obj = unprocessed.shift
@@ -229,7 +161,7 @@ module Nanoc3
           next if seen.include?(successor)
           seen << successor
 
-          successor.outdated_due_to_dependencies = true
+          @objects_outdated_due_to_dependencies << successor
           unprocessed << successor
         end
       end
@@ -240,6 +172,8 @@ module Nanoc3
     # will stick around and new dependencies will appear twice. This function
     # removes all incoming edges for the given vertex.
     #
+    # @api private
+    #
     # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
     #   forget all dependencies
     #
@@ -253,6 +187,42 @@ module Nanoc3
       propagate_outdatedness
     end
 
+    # @deprecated Use {#store} instead
+    def store_graph
+      self.store
+    end
+
+    # @deprecated Use {#load} instead
+    def load_graph
+      self.load
+    end
+
+  protected
+
+    def data
+      {
+        :edges    => @graph.edges,
+        :vertices => @graph.vertices.map { |obj| obj && obj.reference }
+      }
+    end
+
+    def data=(new_data)
+      # Create new graph
+      @graph = Nanoc3::DirectedGraph.new([ nil ] + @objects)
+
+      # Load vertices
+      @previous_objects = new_data[:vertices].map do |reference|
+        @objects.find { |obj| reference == obj.reference }
+      end
+
+      # Load edges
+      new_data[:edges].each do |edge|
+        from_index, to_index = *edge
+        from, to = @previous_objects[from_index], @previous_objects[to_index]
+        @graph.add_edge(from, to)
+      end
+    end
+
   end
 
 end

data/lib/nanoc3/base/compilation/item_rep_proxy.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+require 'forwardable'
+
+module Nanoc3
+
+  # Represents an item representation, but provides an interface that is
+  # easier to use when writing compilation and routing rules. It is also
+  # responsible for fetching the necessary information from the compiler, such
+  # as assigns.
+  #
+  # The API provided by item representation proxies allows layout identifiers
+  # to be given as literals instead of as references to {Nanoc3::Layout}.
+  class ItemRepProxy
+
+    extend Forwardable
+
+    def_delegators :@item_rep, :item, :name, :binary, :binary?, :compiled_content, :has_snapshot?, :raw_path, :path
+    def_delegator  :@item_rep, :snapshot
+
+    # @param [Nanoc3::ItemRep] item_rep The item representation that this
+    #   proxy should behave like
+    #
+    # @param [Nanoc3::Compiler] compiler The compiler that will provide the
+    #   necessary compilation-related functionality.
+    def initialize(item_rep, compiler)
+      @item_rep = item_rep
+      @compiler = compiler
+    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}).
+    #
+    # @see Nanoc3::ItemRep#filter
+    #
+    # @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(name, args={})
+      set_assigns
+      @item_rep.filter(name, args)
+    end
+
+    # 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}).
+    #
+    # @see Nanoc3::ItemRep#layout
+    #
+    # @param [String] layout_identifier The identifier of the layout to use
+    #
+    # @return [void]
+    def layout(layout_identifier)
+      set_assigns
+
+      layout = layout_with_identifier(layout_identifier)
+      filter_name, filter_args = @compiler.filter_for_layout(layout)
+
+      @item_rep.layout(layout, filter_name, filter_args)
+    end
+
+  private
+
+    def set_assigns
+      @item_rep.assigns = @compiler.assigns_for(@item_rep)
+    end
+
+    def layout_with_identifier(layout_identifier)
+      layout ||= @compiler.site.layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
+      raise Nanoc3::Errors::UnknownLayout.new(layout_identifier) if layout.nil?
+      layout
+    end
+
+  end
+
+end

data/lib/nanoc3/base/compilation/outdatedness_checker.rb

@@ -0,0 +1,86 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Responsible for determining whether an item or a layout is outdated.
+  #
+  # @api private
+  class OutdatednessChecker
+
+    # @option params [Nanoc3::Site] :site (nil) The site this outdatedness
+    #   checker belongs to.
+    #
+    # @option params [Nanoc3::ChecksumStore] :checksum_store (nil) The
+    #   checksum store where checksums of items, layouts, … are stored.
+    def initialize(params={})
+      @site           = params[:site]           if params.has_key?(:site)
+      @checksum_store = params[:checksum_store] if params.has_key?(:checksum_store)
+
+      @outdatedness_reasons = {}
+    end
+
+    # Checks whether the given object is outdated and therefore needs to be
+    # recompiled.
+    #
+    # @param [Nanoc3::Item, Nanoc3::ItemRep, Nanoc3::Layout] obj The object
+    #   whose outdatedness should be checked.
+    #
+    # @return [Boolean] true if the object is outdated, false otherwise
+    def outdated?(obj)
+      !outdatedness_reason_for(obj).nil?
+    end
+
+    # Calculates the reason why the given object is outdated.
+    #
+    # @param [Nanoc3::Item, Nanoc3::ItemRep, Nanoc3::Layout] obj The object
+    #   whose outdatedness reason should be calculated.
+    #
+    # @return [Nanoc3::OutdatednessReasons::Generic, nil] The reason why the
+    #   given object is outdated, or nil if the object is not outdated.
+    def outdatedness_reason_for(obj)
+      case obj.type
+        when :item_rep
+          # Outdated if checksums are missing or different
+          return Nanoc3::OutdatednessReasons::NotEnoughData if !checksum_store.checksums_available?(obj.item)
+          return Nanoc3::OutdatednessReasons::SourceModified if !checksum_store.checksums_identical?(obj.item)
+
+          # Outdated if compiled file doesn't exist (yet)
+          return Nanoc3::OutdatednessReasons::NotWritten if obj.raw_path && !File.file?(obj.raw_path)
+
+          # Outdated if code snippets outdated
+          return Nanoc3::OutdatednessReasons::CodeSnippetsModified if @site.code_snippets.any? do |cs|
+            checksum_store.object_modified?(cs)
+          end
+
+          # Outdated if configuration outdated
+          return Nanoc3::OutdatednessReasons::ConfigurationModified if checksum_store.object_modified?(@site.config)
+
+          # Outdated if rules outdated
+          return Nanoc3::OutdatednessReasons::RulesModified if checksum_store.object_modified?(@site.compiler.rules_with_reference)
+
+          # Not outdated
+          return nil
+        when :item
+          obj.reps.find { |rep| outdatedness_reason_for(rep) }
+        when :layout
+          # Outdated if checksums are missing or different
+          return Nanoc3::OutdatednessReasons::NotEnoughData if !checksum_store.checksums_available?(obj)
+          return Nanoc3::OutdatednessReasons::SourceModified if !checksum_store.checksums_identical?(obj)
+
+          # Not outdated
+          return nil
+        else
+          raise RuntimeError, "do not know how to check outdatedness of #{obj.inspect}"
+      end
+    end
+
+  private
+
+    # @return [Nanoc3::ChecksumStore] The checksum store
+    def checksum_store
+      @checksum_store
+    end
+
+  end
+
+end

data/lib/nanoc3/base/compilation/outdatedness_reasons.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Module that contains all outdatedness reasons.
+  module OutdatednessReasons
+
+    # A generic outdatedness reason. An outdatedness reason is basically a
+    # descriptive message that explains why a given object is outdated.
+    class Generic
+
+      # @return [String] A descriptive message for this outdatedness reason
+      attr_reader :message
+
+      # @param [String] message The descriptive message for this outdatedness
+      #   reason
+      def initialize(message)
+        @message = message
+      end
+
+    end
+
+    NotEnoughData = Generic.new(
+      'Not enough data is present to correctly determine whether the item is outdated.')
+
+    NotWritten = Generic.new(
+      'This item representation has not yet been written to the output directory (but it does have a path).')
+
+    SourceModified = Generic.new(
+      'The source file of this item has been modified since the last time the site was compiled.')
+
+    CodeSnippetsModified = Generic.new(
+      'The code snippets have been modified since the last time the site was compiled.')
+
+    ConfigurationModified = Generic.new(
+      'The site configuration has been modified since the last time the site was compiled.')
+
+    RulesModified = Generic.new(
+      'The rules file has been modified since the last time the site was compiled.')
+
+  end
+
+end

data/lib/nanoc3/base/{rule.rb → compilation/rule.rb}

@@ -55,9 +55,15 @@ module Nanoc3
     # @param [Nanoc3::ItemRep] rep The item representation where this rule
     #   should be applied to
     #
+    # @option params [Nanoc3::Compiler] :compiler The compiler
+    #
+    # @raise [ArgumentError] if no compiler is passed
+    #
     # @return [void]
-    def apply_to(rep)
-      Nanoc3::RuleContext.new(rep).instance_eval &@block
+    def apply_to(rep, params={})
+      compiler = params[:compiler] or raise ArgumentError, "Required :compiler option is missing"
+      rep = Nanoc3::ItemRepProxy.new(rep, compiler)
+      Nanoc3::RuleContext.new(:rep => rep, :compiler => compiler).instance_eval &@block
     end
 
   end

data/lib/nanoc3/base/{rule_context.rb → compilation/rule_context.rb}

@@ -12,26 +12,29 @@ module Nanoc3
   # * `config`  ({Hash})                    - The site configuration
   # * `items`   ({Array}<{Nanoc3::Item}>)   - A list of all items
   # * `layouts` ({Array}<{Nanoc3::Layout}>) - A list of all layouts
+  #
+  # @api private
   class RuleContext < Context
 
-    # Creates a new rule context for the given iterm representation.
+    # @option params [Nanoc3::ItemRep] :rep The item representation that will
+    #   be processed in this rule context
+    #
+    # @option params [Nanoc3::Compiler] :compiler The compiler that is being
+    #   used to compile the site
     #
-    # @param [Nanoc3::ItemRep] rep The item representation for which to create
-    #   a new rule context.
-    def initialize(rep)
-      item    = rep.item
-      site    = item.site
-      config  = site.config
-      items   = site.items
-      layouts = site.layouts
+    # @raise [ArgumentError] if the `:rep` or the `:compiler` option is
+    #   missing
+    def initialize(params={})
+      rep      = params[:rep]      or raise ArgumentError, "Required :rep option is missing"
+      compiler = params[:compiler] or raise ArgumentError, "Required :compiler option is missing"
 
       super({
         :rep     => rep,
-        :item    => item,
-        :site    => site,
-        :config  => config,
-        :items   => items,
-        :layouts => layouts
+        :item    => rep.item,
+        :site    => compiler.site,
+        :config  => compiler.site.config,
+        :items   => compiler.site.items,
+        :layouts => compiler.site.layouts
       })
     end
 

data/lib/nanoc3/base/directed_graph.rb

@@ -38,6 +38,8 @@ module Nanoc3
     # @return [Array]
     attr_reader :vertices
 
+    # @group Creating a graph
+
     # Creates a new directed graph with the given vertices.
     def initialize(vertices)
       @vertices = vertices
@@ -55,6 +57,8 @@ module Nanoc3
       invalidate_caches
     end
 
+    # @group Modifying the graph
+
     # Adds an edge from the first vertex to the second vertex.
     #
     # @param from Vertex where the edge should start
@@ -149,6 +153,8 @@ module Nanoc3
       @roots.delete(v)
     end
 
+    # @group Querying the graph
+
     # Returns the direct predecessors of the given vertex, i.e. the vertices
     # x where there is an edge from x to the given vertex y.
     #
@@ -210,6 +216,8 @@ module Nanoc3
       @roots
     end
 
+    # @group Deprecated methods
+
     # @deprecated Use {#delete_edge} instead
     def remove_edge(from, to)
       delete_edge(from, to)

data/lib/nanoc3/base/errors.rb

@@ -58,23 +58,6 @@ module Nanoc3
 
     end
 
-    # Error that is raised when data is requested when the data is not yet
-    # available (possibly due to a missing {Nanoc3::Site#load_data}).
-    class DataNotYetAvailable < Generic
-
-      # @param [String] type The name of the data type that is not yet
-      #   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`.
-      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
-
-    end
-
     # Error that is raised during site compilation when an item (directly or
     # indirectly) includes its own item content, leading to endless recursion.
     class RecursiveCompilation < Generic
@@ -181,6 +164,15 @@ module Nanoc3
     class InternalConsistency < Generic
     end
 
+    # @deprecated No longer necessary, but kept for backwards compatibility.
+    class DataNotYetAvailable < Generic
+
+      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
+
+    end
+
   end
 
 end

data/lib/nanoc3/base/plugin_registry.rb

@@ -159,7 +159,7 @@ module Nanoc3
 
   end
 
-  # @deprecated Use {Nanoc3::PluginRegistry.instace} instead
+  # @deprecated Use {Nanoc3::PluginRegistry.instance} instead
   Plugin = PluginRegistry.instance
 
 end