nanoc3 3.1.9 → 3.2.0a1

data/lib/nanoc3/base/compiler_dsl.rb

@@ -33,13 +33,13 @@ module Nanoc3
     # rep as a block argument.
     #
     # @param [String] identifier A pattern matching identifiers of items that
-    # should be compiled using this rule
+    #   should be compiled using this rule
     #
     # @option params [Symbol] :rep (:default) The name of the representation
-    # that should be compiled using this rule
+    #   that should be compiled using this rule
     #
     # @yield The block that will be executed when an item matching this
-    # compilation rule needs to be compiled
+    #   compilation rule needs to be compiled
     #
     # @return [void]
     #
@@ -77,13 +77,13 @@ module Nanoc3
     # and passing the rep as a block argument.
     #
     # @param [String] identifier A pattern matching identifiers of items that
-    # should be routed using this rule
+    #   should be routed using this rule
     #
     # @option params [Symbol] :rep (:default) The name of the representation
-    # that should be routed using this rule
+    #   that should be routed using this rule
     #
     # @yield The block that will be executed when an item matching this
-    # compilation rule needs to be routed
+    #   compilation rule needs to be routed
     #
     # @return [void]
     #
@@ -103,10 +103,11 @@ module Nanoc3
       raise ArgumentError.new("#route requires a block") unless block_given?
 
       # Get rep name
-      rep_name = params[:rep] || :default
+      rep_name      = params[:rep] || :default
+      snapshot_name = params[:snapshot] || :last
 
       # Create rule
-      rule = Rule.new(identifier_to_regex(identifier), rep_name, block)
+      rule = Rule.new(identifier_to_regex(identifier), rep_name, block, :snapshot_name => snapshot_name)
       @site.compiler.item_routing_rules << rule
     end
 
@@ -117,13 +118,13 @@ module Nanoc3
     # contains filter arguments that will be passed to the filter.
     #
     # @param [String] identifier A pattern matching identifiers of layouts
-    # that should be filtered using this rule
+    #   that should be filtered using this rule
     #
     # @param [Symbol] filter_name The name of the filter that should be run
-    # when processing the layout
+    #   when processing the layout
     #
     # @param [Hash] params Extra filter arguments that should be passed to the
-    # filter when processing the layout (see {Nanoc3::Filter#run})
+    #   filter when processing the layout (see {Nanoc3::Filter#run})
     #
     # @return [void]
     #

data/lib/nanoc3/base/core_ext/string.rb

@@ -18,12 +18,12 @@ module Nanoc3::StringExtensions
   # @return [String] The decomposed string
   def make_compatible_with_env
     # Check whether environment supports Unicode
-    # TODO this is ugly, and there most likely are better ways to do this
+    # FIXME this is ugly, and there most likely are better ways to do this
     is_unicode_supported = %w( LC_ALL LC_CTYPE LANG ).any? { |e| ENV[e] =~ /UTF/ }
     return self if is_unicode_supported
 
     # Decompose if necessary
-    # TODO this decomposition is not generally usable
+    # FIXME this decomposition is not generally usable
     self.gsub(/“|”/, '"').gsub(/‘|’/, '\'').gsub('…', '...')
   end
 

data/lib/nanoc3/base/data_source.rb

@@ -21,21 +21,22 @@ module Nanoc3
   # first time.
   #
   # @abstract Subclasses should at least implement {#items} and {#layouts}. If
-  # the data source should support creating items and layouts using the
-  # `create_item` and `create_layout` CLI commands, the {#setup},
-  # {#create_item} and {#create_layout} methods should be implemented as well.
+  #   the data source should support creating items and layouts using the
+  #   `create_item` and `create_layout` CLI commands, the {#setup},
+  #   {#create_item} and {#create_layout} methods should be implemented as
+  #   well.
   class DataSource
 
     # @return [String] The root path where items returned by this data source
-    # should be mounted.
+    #   should be mounted.
     attr_reader :items_root
 
     # @return [String] The root path where layouts returned by this data
-    # source should be mounted.
+    #   source should be mounted.
     attr_reader :layouts_root
 
     # @return [Hash] The configuration for this data source. For example,
-    # online data sources could contain authentication details.
+    #   online data sources could contain authentication details.
     attr_reader :config
 
     extend Nanoc3::PluginRegistry::PluginMethods
@@ -45,12 +46,12 @@ module Nanoc3
     # @param [Nanoc3::Site] site The site this data source belongs to.
     #
     # @param [String] items_root The prefix that should be given to all items
-    # returned by the #items method (comparable to mount points for
-    # filesystems in Unix-ish OSes).
+    #   returned by the #items method (comparable to mount points for
+    #   filesystems in Unix-ish OSes).
     #
     # @param [String] layouts_root The prefix that should be given to all
-    # layouts returned by the #layouts method (comparable to mount points
-    # for filesystems in Unix-ish OSes).
+    #   layouts returned by the #layouts method (comparable to mount points
+    #   for filesystems in Unix-ish OSes).
     #
     # @param [Hash] config The configuration for this data source.
     def initialize(site, items_root, layouts_root, config)
@@ -189,9 +190,9 @@ module Nanoc3
     # @param [String] identifier
     #
     # @param [Hash] params Extra parameters to give to the data source. This
-    # can be used to influence the way items are stored. For example,
-    # filesystem data sources could use this to pass the extension of the
-    # files that should be generated.
+    #   can be used to influence the way items are stored. For example,
+    #   filesystem data sources could use this to pass the extension of the
+    #   files that should be generated.
     #
     # @return [void]
     def create_item(content, attributes, identifier, params={})
@@ -212,9 +213,9 @@ module Nanoc3
     # @param [String] identifier
     #
     # @param [Hash] params Extra parameters to give to the data source. This
-    # can be used to influence the way items are stored. For example,
-    # filesystem data sources could use this to pass the extension of the
-    # files that should be generated.
+    #   can be used to influence the way items are stored. For example,
+    #   filesystem data sources could use this to pass the extension of the
+    #   files that should be generated.
     #
     # @return [void]
     def create_layout(content, attributes, identifier, params={})

data/lib/nanoc3/base/dependency_tracker.rb

@@ -4,18 +4,18 @@ require 'pstore'
 
 module Nanoc3
 
-  # Responsible for remembering dependencies between items. It is used to
-  # speed up compilation by only letting an item be recompiled when it is
-  # outdated or any of its dependencies (or dependencies’ dependencies, etc)
-  # is outdated.
+  # Responsible for remembering dependencies between items and layouts. It is
+  # used to speed up compilation by only letting an item be recompiled when it
+  # is outdated or any of its dependencies (or dependencies’ dependencies,
+  # etc) is outdated.
   #
   # The dependencies tracked by the dependency tracker are not dependencies
-  # based on an item’s content. When one item uses an attribute of another
-  # item, then this is also treated as a dependency. While dependencies based
-  # on an item’s content (handled in {Nanoc3::Compiler}) cannot be mutually
-  # recursive, the more general dependencies in Nanoc3::DependencyTracker can
-  # (e.g. item A can use an attribute of item B and vice versa without
-  # problems).
+  # based on an item’s or a layout’s content. When one object uses an
+  # attribute of another object, then this is also treated as a dependency.
+  # While dependencies based on an item’s or layout’s content (handled in
+  # {Nanoc3::Compiler}) cannot be mutually recursive, the more general
+  # dependencies in Nanoc3::DependencyTracker can (e.g. item A can use an
+  # attribute of item B and vice versa without problems).
   #
   # The dependency tracker remembers the dependency information between runs.
   # Dependency information is stored in the `tmp/dependencies` file. This file
@@ -24,25 +24,26 @@ module Nanoc3
   class DependencyTracker
 
     # @return [String] The name of the file in which dependency information is
-    # stored
+    #   stored
     attr_accessor :filename
 
-    # @return [Array<Nanoc3::Item>] The list of items that is being tracked
-    # by the dependency tracker
-    attr_reader :items
+    # @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 = 2
+    STORE_VERSION = 3
 
-    # Creates a new dependency tracker for the given items.
+    # Creates a new dependency tracker for the given items and layouts.
     #
-    # @param [Array<Nanoc3::Item>] item The list of items whose dependencies
-    # should be managed
-    def initialize(items)
-      @items          = items
-      @filename       = 'tmp/dependencies'
-      @graph          = Nanoc3::DirectedGraph.new([ nil ] + @items)
-      @previous_items = []
+    # @param [Array<Nanoc3::Item, Nanoc3::Layout>] objects The list of items
+    #   and layouts whose dependencies should be managed
+    def initialize(objects)
+      @objects = objects
+
+      @filename         = 'tmp/dependencies'
+      @graph            = Nanoc3::DirectedGraph.new([ nil ] + @objects)
+      @previous_objects = []
     end
 
     # Starts listening for dependency messages (`:visit_started` and
@@ -50,24 +51,19 @@ module Nanoc3
     #
     # @return [void]
     def start
-      # Initialize dependency stack. An item will be pushed onto this stack
-      # when it is visited. Therefore, an item on the stack always depends on
-      # all items pushed above it.
+      # Initialize dependency stack. An object will be pushed onto this stack
+      # when it is visited. Therefore, an object on the stack always depends
+      # on all objects pushed above it.
       @stack = []
 
       # Register start of visits
-      Nanoc3::NotificationCenter.on(:visit_started, self) do |item|
-        # Record possible dependency
-        unless @stack.empty?
-          $stderr.puts "*** Recording dependency on #{item.inspect}" if $DEBUG
-          self.record_dependency(@stack[-1], item)
-        end
-
-        @stack.push(item)
+      Nanoc3::NotificationCenter.on(:visit_started, self) do |obj|
+        self.record_dependency(@stack[-1], obj) unless @stack.empty?
+        @stack.push(obj)
       end
 
       # Register end of visits
-      Nanoc3::NotificationCenter.on(:visit_ended, self) do |item|
+      Nanoc3::NotificationCenter.on(:visit_ended, self) do |obj|
         @stack.pop
       end
     end
@@ -81,71 +77,78 @@ module Nanoc3
       Nanoc3::NotificationCenter.remove(:visit_ended,   self)
     end
 
-    # Returns the direct dependencies for `item`.
+    # Returns the direct dependencies for the given object.
     #
-    # The direct dependencies of `item` include the items that, when outdated
-    # will cause `item` to be marked as outdated. Indirect dependencies will
-    # not be returned (e.g. if A depends on B which depends on C, then the
-    # direct dependencies of A do not include C).
+    # The direct dependencies of the given object include the items
+    # and layouts that, when outdated will cause the given object to be marked
+    # as outdated. Indirect dependencies will not be returned (e.g. if A
+    # depends on B which depends on C, then the direct dependencies of A do
+    # not include C).
     #
-    # @param [Nanoc3::Item] item The item for which to fetch the direct
-    # predecessors
+    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for
+    #   which to fetch the direct predecessors
     #
-    # @return [Array<Nanoc3::Item>] The direct predecessors of the given item
-    def direct_predecessors_of(item)
-      @graph.direct_predecessors_of(item).compact
+    # @return [Array<Nanoc3::Item, Nanoc3::Layout>] The direct predecessors of
+    #   the given object
+    def direct_predecessors_of(object)
+      @graph.direct_predecessors_of(object).compact
     end
 
-    # Returns all dependencies (direct and indirect) for `item`.
+    # Returns all dependencies (direct and indirect) for the given object.
     #
-    # The dependencies of `item` include the items that, when outdated, will
-    # cause `item` to be marked as outdated.
+    # The dependencies of given object include the objects that, when
+    # outdated, will cause the given object to be marked as outdated.
     #
-    # @param [Nanoc3::Item] item The item for which to fetch all direct and
-    # indirect predecessors
+    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
+    #   fetch all direct and indirect predecessors
     #
-    # @return [Array<Nanoc3::Item>] The predecessors of the given item
-    def predecessors_of(item)
-      @graph.predecessors_of(item).compact
+    # @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 `item`.
+    # Returns the direct inverse dependencies for the given object.
     #
-    # The direct inverse dependencies of `item` include the items that will be
-    # marked as outdated when`+item` is outdated. Indirect dependencies will
-    # not be returned (e.g. if A depends on B which depends on C, then the
-    # direct inverse dependencies of C do not include A).
+    # The direct inverse dependencies of the given object include the objects
+    # that will be marked as outdated when the given object is outdated.
+    # Indirect dependencies will not be returned (e.g. if A depends on B which
+    # depends on C, then the direct inverse dependencies of C do not include
+    # A).
     #
-    # @param [Nanoc3::Item] item The item for which to fetch the direct
-    # successors
+    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
+    #   fetch the direct successors
     #
-    # @return [Array<Nanoc3::Item>] The direct successors of the given item
-    def direct_successors_of(item)
-      @graph.direct_successors_of(item).compact
+    # @return [Array<Nanoc3::Item, Nanoc3::Layout>] The direct successors of
+    #   the given object
+    def direct_successors_of(object)
+      @graph.direct_successors_of(object).compact
     end
 
-    # Returns all inverse dependencies (direct and indirect) for `item`.
+    # Returns all inverse dependencies (direct and indirect) for the given
+    # object.
     #
-    # The inverse dependencies of `item` include the items that will be marked
-    # as outdated when `item` is outdated.
+    # 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] item The item for which to fetch all direct and
-    # indirect successors
+    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
+    #   fetch all direct and indirect successors
     #
-    # @return [Array<Nanoc3::Item>] The successors of the given item
-    def successors_of(item)
-      @graph.successors_of(item).compact
+    # @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.
     #
-    # @param [Nanoc3::Item] src The source of the dependency, i.e. the item
-    # that will become outdated if dst is outdated
+    # @param [Nanoc3::Item, Nanoc3::Layout] src The source of the dependency,
+    #   i.e. the object that will become outdated if dst is outdated
     #
-    # @param [Nanoc3::Item] dst The destination of the dependency, i.e. the
-    # item that will cause the source to become outdated if the destination
-    # is outdated
+    # @param [Nanoc3::Item, Nanoc3::Layout] dst The destination of the
+    #   dependency, i.e. the object that will cause the source to become
+    #   outdated if the destination is outdated
     #
     # @return [void]
     def record_dependency(src, dst)
@@ -162,7 +165,7 @@ module Nanoc3
       store = PStore.new(self.filename)
       store.transaction do
         store[:version]  = STORE_VERSION
-        store[:vertices] = @graph.vertices.map { |i| i && i.identifier }
+        store[:vertices] = @graph.vertices.map { |obj| obj && obj.reference }
         store[:edges]    = @graph.edges
       end
     end
@@ -173,7 +176,7 @@ module Nanoc3
     # @return [void]
     def load_graph
       # Create new graph
-      @graph = Nanoc3::DirectedGraph.new([ nil ] + @items)
+      @graph = Nanoc3::DirectedGraph.new([ nil ] + @objects)
 
       # Get store
       return if !File.file?(self.filename)
@@ -185,44 +188,44 @@ module Nanoc3
         return if store[:version] != STORE_VERSION
 
         # Load vertices
-        @previous_items = store[:vertices].map do |v|
-          @items.find { |i| i.identifier == v }
+        @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_items[from_index], @previous_items[to_index]
+          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 items that (directly or
-    # indirectly) depend on an outdated item as outdated.
+    # 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
-      @items.each { |i| i.outdated_due_to_dependencies = false }
+      @objects.each { |o| o.outdated_due_to_dependencies = false }
 
-      # Mark new items as outdated
-      added_items = @items - @previous_items
-      added_items.each { |i| i.outdated_due_to_dependencies = true }
+      # 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 |i|
-        i.outdated_due_to_dependencies = true
+      self.successors_of(nil).each do |o|
+        o.outdated_due_to_dependencies = true
       end
 
-      # Mark successors of outdated items as outdated
+      # Mark successors of outdated objects as outdated
       require 'set'
-      unprocessed = @items.select { |i| i.outdated? }
+      unprocessed = @objects.select { |o| o.outdated? }
       seen        = Set.new(unprocessed)
       until unprocessed.empty?
-        item = unprocessed.shift
+        obj = unprocessed.shift
 
-        self.direct_successors_of(item).each do |successor|
+        self.direct_successors_of(obj).each do |successor|
           next if seen.include?(successor)
           seen << successor
 
@@ -232,32 +235,17 @@ module Nanoc3
       end
     end
 
-    # Empties the list of dependencies for the given item. This is necessary
-    # before recompiling the given item, because otherwise old dependencies
+    # Empties the list of dependencies for the given object. This is necessary
+    # before recompiling the given object, because otherwise old dependencies
     # will stick around and new dependencies will appear twice. This function
     # removes all incoming edges for the given vertex.
     #
-    # @param [Nanoc3::Item] item The item for which to forget all dependencies
-    #
-    # @return [void]
-    def forget_dependencies_for(item)
-      @graph.delete_edges_to(item)
-    end
-
-    # Prints the dependency graph in human-readable form.
+    # @param [Nanoc3::Item, Nanoc3::Layout] object The object for which to
+    #   forget all dependencies
     #
     # @return [void]
-    def print_graph
-      @items.each do |item|
-        puts "#{item.inspect} depends on:"
-
-        predecessors = direct_predecessors_of(item)
-        predecessors.each do |pred|
-          puts "    #{pred.inspect}"
-        end
-        puts "    (nothing!)" if predecessors.empty?
-        puts
-      end
+    def forget_dependencies_for(object)
+      @graph.delete_edges_to(object)
     end
 
     # @deprecated Use {#propagate_outdatedness} instead.
@@ -265,13 +253,6 @@ module Nanoc3
       propagate_outdatedness
     end
 
-  private
-
-    # Returns the item with the given identifier, or nil if no item is found.
-    def item_with_identifier(identifier)
-      @items.find { |i| i.identifier == identifier }
-    end
-
   end
 
 end

data/lib/nanoc3/base/directed_graph.rb

@@ -46,16 +46,19 @@ module Nanoc3
       @to_graph   = {}
 
       @vertice_indexes = {}
-      vertices.each_with_index do |v, i|
+      @vertices.each_with_index do |v, i|
         @vertice_indexes[v] = i
       end
 
+      @roots = Set.new(@vertices)
+
       invalidate_caches
     end
 
     # Adds an edge from the first vertex to the second vertex.
     #
     # @param from Vertex where the edge should start
+    #
     # @param to   Vertex where the edge should end
     #
     # @return [void]
@@ -66,6 +69,8 @@ module Nanoc3
       @to_graph[to] ||= Set.new
       @to_graph[to]  << from
 
+      @roots.delete(to)
+
       invalidate_caches
     end
 
@@ -73,30 +78,75 @@ module Nanoc3
     # edge does not exist, nothing is done.
     #
     # @param from Start vertex of the edge
+    #
     # @param to   End vertex of the edge
     #
     # @return [void]
-    def remove_edge(from, to)
+    def delete_edge(from, to)
       @from_graph[from] ||= Set.new
       @from_graph[from].delete(to)
 
       @to_graph[to] ||= Set.new
       @to_graph[to].delete(from)
 
+      @roots.add(to) if @to_graph[to].empty?
+
       invalidate_caches
     end
 
+    # Adds the given vertex to the graph.
+    #
+    # @param [Vertex] v The vertex to add to the graph
+    #
+    # @return [void]
+    def add_vertex(v)
+      return if @vertices.include?(v)
+
+      @vertices << v
+      @roots    << v
+    end
+
+    # Deletes all edges coming from the given vertex.
+    #
+    # @param from Vertex from which all edges should be removed
+    #
+    # @return [void]
+    def delete_edges_from(from)
+      return if @from_graph[from].nil?
+
+      @from_graph[from].each do |to|
+        @to_graph[to].delete(from)
+        @roots.add(to) if @to_graph[to].empty?
+      end
+      @from_graph.delete(from)
+    end
+
     # Deletes all edges going to the given vertex.
     #
     # @param to Vertex to which all edges should be removed
     #
     # @return [void]
     def delete_edges_to(to)
-      @to_graph[to] ||= Set.new
+      return if @to_graph[to].nil?
+
       @to_graph[to].each do |from|
         @from_graph[from].delete(to)
       end
       @to_graph.delete(to)
+      @roots.add(to)
+    end
+
+    # Removes the given vertex from the graph.
+    #
+    # @param v Vertex to remove from the graph
+    #
+    # @return [void]
+    def delete_vertex(v)
+      delete_edges_to(v)
+      delete_edges_from(v)
+
+      @vertices.delete(v)
+      @roots.delete(v)
     end
 
     # Returns the direct predecessors of the given vertex, i.e. the vertices
@@ -153,6 +203,18 @@ module Nanoc3
       result
     end
 
+    # Returns all root vertices, i.e. vertices where no edge points to.
+    #
+    # @return [Set] The set of all root vertices in this graph.
+    def roots
+      @roots
+    end
+
+    # @deprecated Use {#delete_edge} instead
+    def remove_edge(from, to)
+      delete_edge(from, to)
+    end
+
   private
 
     # Invalidates cached data. This method should be called when the internal