nanoc3 3.0.9 → 3.1.0a1

data/lib/nanoc3/base/directed_graph.rb

@@ -0,0 +1,252 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Nanoc3::DirectedGraph represents a directed graph. It is used by the
+  # dependency tracker for storing and querying dependencies between items.
+  # Internally, the graph will be stored as an adjacency matrix. For this,
+  # the {Nanoc3::DirectedGraph::SquareBooleanMatrix} class is used.
+  #
+  # @example Creating and using a directed graph
+  #
+  #   # Create a graph with three vertices
+  #   graph = DirectedGraph.new(%w( a b c d ))
+  #   
+  #   # Add edges
+  #   graph.add_edge('a', 'b')
+  #   graph.add_edge('b', 'c')
+  #   graph.add_edge('c', 'd')
+  #   
+  #   # Get (direct) predecessors
+  #   graph.direct_predecessors_of('d').sort
+  #     # => %w( c )
+  #   graph.predecessors_of('d').sort
+  #     # => %w( a b c )
+  #   
+  #   # Modify edges
+  #   graph.remove_edge('a', 'b')
+  #   
+  #   # Get (direct) predecessors again
+  #   graph.direct_predecessors_of('d').sort
+  #     # => %w( c )
+  #   graph.predecessors_of('d').sort
+  #     # => %w( b c )
+  class DirectedGraph
+
+    # Nanoc3::DirectedGraph::SquareBooleanMatrix is, as the name says, a
+    # square matrix that contains boolean values. It is used as an adjacency
+    # matrix by the {Nanoc3::DirectedGraph} class.
+    class SquareBooleanMatrix
+
+      # Creates a new matrix with the given number of rows/columns.
+      #
+      # @param [Number] size The number of elements along both sides of the
+      #   matrix (in other words, the square root of the number of elements)
+      def initialize(size)
+        @size = size
+      end
+
+      # Gets the value at the given x/y coordinates.
+      #
+      # @param [Number] x The X coordinate
+      # @param [Number] y The Y coordinate
+      #
+      # @return The value at the given coordinates
+      def [](x, y)
+        @data ||= {}
+        @data[x] ||= {}
+        @data[x].has_key?(y) ? @data[x][y] : false
+      end
+
+      # Sets the value at the given x/y coordinates.
+      #
+      # @param [Number] x The X coordinate
+      # @param [Number] y The Y coordinate
+      # @param value The value to set at the given coordinates
+      #
+      # @return [void]
+      def []=(x, y, value)
+        @data ||= {}
+        @data[x] ||= {}
+        @data[x][y] = value
+      end
+
+      # Returns a string representing this matrix in ASCII art.
+      #
+      # @return [String] The string representation of this matrix
+      def to_s
+        s = ''
+
+        # Calculate column width
+        width = (@size-1).to_s.size
+
+        # Add header
+        s << ' ' + ' '*width + ' '
+        @size.times { |i| s << '| ' + format("%#{width}i", i) + ' ' }
+        s << "\n"
+
+        # Add rows
+        @size.times do |x|
+          # Add line
+          s << '-' + '-'*width + '-'
+          @size.times { |i| s << '+-' + '-'*width + '-' }
+          s << "\n"
+
+          # Add actual row
+          s << ' ' + format("%#{width}i", x)+ ' '
+          @size.times do |y|
+            s << '| ' + format("%#{width}s", self[x, y] ? '*' : ' ') + ' '
+          end
+          s << "\n"
+        end
+
+        # Done
+        s
+      end
+
+    end
+
+    # The list of vertices in this graph.
+    #
+    # @return [Array]
+    attr_reader :vertices
+
+    # Creates a new directed graph with the given vertices.
+    def initialize(vertices)
+      @vertices = vertices
+
+      @matrix = SquareBooleanMatrix.new(@vertices.size)
+    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]
+    def add_edge(from, to)
+      from_index, to_index = indices_of(from, to)
+      @matrix[from_index, to_index] = true
+    end
+
+    # Removes the edge from the first vertex to the second vertex. If the
+    # 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)
+      from_index, to_index = indices_of(from, to)
+      @matrix[from_index, to_index] = false
+    end
+
+    # 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.
+    #
+    # @param to The vertex of which the predecessors should be calculated
+    #
+    # @return [Array] Direct predecessors of the given vertex
+    def direct_predecessors_of(to)
+      @vertices.select do |from|
+        from_index, to_index = indices_of(from, to)
+        @matrix[from_index, to_index] == true
+      end
+    end
+
+    # Returns the direct successors of the given vertex, i.e. the vertices y
+    # where there is an edge from the given vertex x to y.
+    #
+    # @param from The vertex of which the successors should be calculated
+    #
+    # @return [Array] Direct successors of the given vertex
+    def direct_successors_of(from)
+      @vertices.select do |to|
+        from_index, to_index = indices_of(from, to)
+        @matrix[from_index, to_index] == true
+      end
+    end
+
+    # Returns the predecessors of the given vertex, i.e. the vertices x for
+    # which there is a path from x to the given vertex y.
+    #
+    # @param to The vertex of which the predecessors should be calculated
+    #
+    # @return [Array] Predecessors of the given vertex
+    def predecessors_of(to)
+      recursively_find_vertices(to, :direct_predecessors_of)
+    end
+
+    # Returns the successors of the given vertex, i.e. the vertices y for
+    # which there is a path from the given vertex x to y.
+    #
+    # @param from The vertex of which the successors should be calculated
+    #
+    # @return [Array] Successors of the given vertex
+    def successors_of(from)
+      recursively_find_vertices(from, :direct_successors_of)
+    end
+
+    # Returns an array of tuples representing the edges. The result of this
+    # method may take a while to compute and should be cached if possible.
+    #
+    # @return [Array] The list of all edges in this graph.
+    def edges
+      result = []
+
+      @vertices.each do |from|
+        @vertices.each do |to|
+          from_index, to_index = indices_of(from, to)
+          next if @matrix[from_index, to_index] == false
+
+          result << [ from_index, to_index ]
+        end
+      end
+
+      result
+    end
+
+    # Returns a string representing this graph in ASCII art (or, to be more
+    # precise, the string representation of the matrix backing this graph).
+    #
+    # @return [String] The string representation of this graph
+    def to_s
+      @matrix.to_s
+    end
+
+  private
+
+    # Returns an array of indices for the given vertices. Raises an error if
+    # one or more given objects are not vertices.
+    def indices_of(*vertices)
+      vertices.map { |v| @vertices.index(v) or raise RuntimeError, "#{v.inspect} not a vertex" }
+    end
+
+    # Recursively finds vertices, starting at the vertex start, using the
+    # given method, which should be a symbol to a method that takes a vertex
+    # and returns related vertices (e.g. predecessors, successors).
+    def recursively_find_vertices(start, method)
+      all_vertices = []
+
+      processed_vertices   = []
+      unprocessed_vertices = [ start ]
+
+      until unprocessed_vertices.empty?
+        # Get next unprocessed vertex
+        vertex = unprocessed_vertices.pop
+        next if processed_vertices.include?(vertex)
+        processed_vertices << vertex
+
+        # Add predecessors of this vertex
+        send(method, vertex).each do |v|
+          all_vertices << v unless all_vertices.include?(v)
+          unprocessed_vertices << v
+        end
+      end
+
+      all_vertices
+    end
+
+  end
+
+end

data/lib/nanoc3/base/errors.rb

@@ -2,6 +2,7 @@
 
 module Nanoc3
 
+  # Module that contains all nanoc-specific errors.
   module Errors
 
     # Generic error. Superclass for all nanoc-specific errors.
@@ -11,83 +12,130 @@ module Nanoc3
     # Error that is raised when a site is loaded that uses a data source with
     # an unknown identifier.
     class UnknownDataSource < Generic
+
+      # @param [String] data_source_name The data source name for which no
+      #   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.")
       end
+
     end
 
     # Error that is raised during site compilation when an item uses a layout
     # that is not present in the site.
     class UnknownLayout < Generic
+
+      # @param [String] layout_identifier The layout identifier for which no
+      #   layout could be found
       def initialize(layout_identifier)
         super("The site does not have a layout with identifier '#{layout_identifier}'.")
       end
+
     end
 
     # Error that is raised during site compilation when an item uses a filter
     # that is not known.
     class UnknownFilter < Generic
+
+      # @param [Symbol] filter_name The filter name for which no filter could
+      #   be found
       def initialize(filter_name)
         super("The requested filter, #{filter_name}, does not exist.")
       end
+
     end
 
     # Error that is raised during site compilation when a layout is compiled
     # for which the filter cannot be determined. This is similar to the
-    # UnknownFilterError, but specific for filters for layouts.
+    # {UnknownFilter} error, but specific for filters for layouts.
     class CannotDetermineFilter < Generic
+
+      # @param [String] layout_identifier The identifier of the layout for
+      #   which the filter could not be determined
       def initialize(layout_identifier)
         super("The filter to be used for the '#{layout_identifier}' could not be determined. Make sure the layout does have a filter.")
       end
+
     end
 
     # Error that is raised when data is requested when the data is not yet
-    # available (possibly due to a missing Nanoc::Site#load_data).
+    # 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 Nanoc::Site#load_data call.")
+        super("#{type} #{plural ? 'are' : 'is'} not available yet. You may be missing a Nanoc3::Site#load_data call.")
       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
+
+      # @param [Array<Nanoc3::ItemRep>] reps A list of item representations
+      #   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}.")
       end
+
     end
 
     # Error that is raised when no rules file can be found in the current
     # working directory.
     class NoRulesFileFound < Generic
+
       def initialize
         super("This site does not have a rules file, which is required for nanoc sites.")
       end
+
     end
 
     # Error that is raised when no compilation rule that can be applied to the
     # current item can be found.
     class NoMatchingCompilationRuleFound < Generic
+
+      # @param [Nanoc3::Item] item The item for which no compilation rule
+      #   could be found
       def initialize(item)
         super("No compilation rules were found for the '#{item.identifier}' item.")
       end
+
     end
 
     # Error that is raised when no routing rule that can be applied to the
     # current item can be found.
     class NoMatchingRoutingRuleFound < Generic
+
+      # @param [Nanoc3::Item] item The item for which no routing rule could be
+      #   found
       def initialize(rep)
         super("No routing rules were found for the '#{rep.item.identifier}' item (rep '#{rep.name}').")
       end
+
     end
 
-    # Error that is raised when an rep cannot be compiled because it depends on other representations.
+    # Error that is raised when an rep cannot be compiled because it depends
+    # on other representations.
     class UnmetDependency < Generic
+
+      # @return [Nanoc3::ItemRep] The item representation that cannot yet be
+      #   compiled
       attr_reader :rep
+
+      # @param [Nanoc3::ItemRep] The item representation that cannot yet be
+      #   compiled
       def initialize(rep)
         @rep = rep
         super("The '#{rep.item.identifier}' item (rep '#{rep.name}') cannot currently be compiled yet due to an unmet dependency.")
       end
+
     end
 
   end

data/lib/nanoc3/base/filter.rb

@@ -2,49 +2,64 @@
 
 module Nanoc3
 
-  # Nanoc3::Filter is responsible for filtering items. It is
-  # the (abstract) superclass for all textual filters. Subclasses should
-  # override the +run+ method.
-  class Filter < Plugin
+  # Nanoc3::Filter is responsible for filtering items. It is the superclass
+  # for all textual filters.
+  #
+  # When creating a filter with a hash containing assigned variables, those
+  # variables will be made available in the `@assigns` instance variable and
+  # the {#assigns} method. The assigns itself will also be available as
+  # instance variables and instance methods.
+  #
+  # @example Accessing assigns in different ways
+  #
+  #     filter = SomeFilter.new({ :foo => 'bar' })
+  #     filter.instance_eval { @assigns[:foo] }
+  #       # => 'bar'
+  #     filter.instance_eval { assigns[:foo] }
+  #       # => 'bar'
+  #     filter.instance_eval { @foo }
+  #       # => 'bar'
+  #     filter.instance_eval { foo }
+  #       # => 'bar'
+  #
+  # @abstract Subclass and override {#run} to implement a custom filter.
+  class Filter < Context
 
     # A hash containing variables that will be made available during
     # filtering.
-    attr_reader :assigns
-
-    # Creates a new filter with the given assigns.
     #
-    # +a_assigns+:: A hash containing variables that should be made available
-    #               during filtering.
-    def initialize(a_assigns={})
-      @assigns = a_assigns
-    end
+    # @return [Hash]
+    attr_reader :assigns
 
-    # Sets the identifiers for this filter.
-    def self.identifiers(*identifiers)
-      Nanoc3::Filter.register(self, *identifiers)
-    end
+    extend Nanoc3::PluginRegistry::PluginMethods
 
-    # Sets the identifier for this filter.
-    def self.identifier(identifier)
-      Nanoc3::Filter.register(self, identifier)
-    end
-
-    # Registers the given class as a filter with the given identifier.
-    def self.register(class_or_name, *identifiers)
-      Nanoc3::Plugin.register(Nanoc3::Filter, class_or_name, *identifiers)
+    # Creates a new filter that has access to the given assigns.
+    #
+    # @param [Hash] a_assigns A hash containing variables that should be made
+    #   available during filtering.
+    def initialize(hash={})
+      @assigns = hash
+      super
     end
 
-    # Runs the filter. This method returns the filtered content.
+    # Runs the filter on the given content.
+    #
+    # @abstract
     #
-    # +content+:: The unprocessed content that should be filtered.
+    # @param [String] content The unprocessed content that should be filtered.
     #
-    # Subclasses must implement this method.
+    # @param [Hash] params A hash containing parameters. Filter subclasses can
+    #   use these parameters to allow modifying the filter's behaviour.
+    #
+    # @return [String] The filtered content
     def run(content, params={})
       raise NotImplementedError.new("Nanoc3::Filter subclasses must implement #run")
     end
 
     # Returns the filename associated with the item that is being filtered.
-    # The returned filename is in the format "item <identifier> (rep <name>)".
+    # It is in the format `item <identifier> (rep <name>)`.
+    #
+    # @return [String] The filename
     def filename
       if assigns[:layout]
         "layout #{assigns[:layout].identifier}"

data/lib/nanoc3/base/item.rb

@@ -2,47 +2,48 @@
 
 module Nanoc3
 
-  # Nanoc3::Item represents a compileable item in a site. It has content and
-  # attributes, as well as an identifier. It can also store the modification
-  # time to speed up compilation.
+  # Represents a compileable item in a site. It has content and attributes, as
+  # well as an identifier (which starts and ends with a slash). It can also
+  # store the modification time to speed up compilation.
   class Item
 
-    # The Nanoc3::Site this item belongs to.
+    # @return [Nanoc3::Site] The site this item belongs to
     attr_accessor :site
 
-    # A hash containing this item's attributes.
+    # @return [Hash] This item's attributes
     attr_accessor :attributes
 
-    # This item's identifier.
+    # @return [String] This item's identifier
     attr_accessor :identifier
 
-    # The time when this item was last modified.
+    # @return [Time] The time when this item was last modified
     attr_reader   :mtime
 
-    # This item's list of item representations.
+    # @return [Array<Nanoc3::ItemRep>] This item’s list of item reps
     attr_reader   :reps
 
-    # This item's raw, uncompiled content.
+    # @return [String] This item's raw, uncompiled content
     attr_reader   :raw_content
 
-    # The parent item of this item. This can be nil even for non-root items.
+    # @return [Nanoc3::Item, nil] The parent item of this item. This can be
+    #   nil even for non-root items.
     attr_accessor :parent
 
-    # The child items of this item.
+    # @return [Array<Nanoc3::Item>] The child items of this item
     attr_accessor :children
 
-    # A boolean indicating whether or not this item is outdated because of its dependencies are outdated.
-    attr_accessor :dependencies_outdated
+    # @return [Boolean] Whether or not this item is outdated because of its
+    #   dependencies are outdated
+    attr_accessor :outdated_due_to_dependencies
+    alias_method :outdated_due_to_dependencies?, :outdated_due_to_dependencies
 
-    # Creates a new item.
+    # @param [String] raw_content The uncompiled item content.
     #
-    # +raw_content+:: The uncompiled item content.
+    # @param [Hash] attributes A hash containing this item's attributes.
     #
-    # +attributes+:: A hash containing this item's attributes.
+    # @param [String] identifier This item's identifier.
     #
-    # +identifier+:: This item's identifier.
-    #
-    # +mtime+:: The time when this item was last modified.
+    # @param [String, nil] mtime The time when this item was last modified.
     def initialize(raw_content, attributes, identifier, mtime=nil)
       @raw_content  = raw_content
       @attributes   = attributes.symbolize_keys
@@ -55,7 +56,72 @@ module Nanoc3
       @reps         = []
     end
 
+    # Returns the rep with the given name.
+    #
+    # @param [Symbol] rep_name The name of the representation to return
+    #
+    # @return [Nanoc3::ItemRep] The representation with the given name
+    def rep(rep_name)
+      @reps.find { |r| r.name == rep_name }
+    end
+
+    # Returns the compiled content from a given representation and a given
+    # snapshot. This is a convenience method that makes fetching compiled
+    # 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.
+    #
+    # @option params [String] :snapshot (:last) The name of the snapshot from
+    #   which to fetch the compiled content. By default, the fully compiled
+    #   content will be fetched, with all filters and layouts applied--not the
+    #   pre-layout content.
+    #
+    # @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)
+    def compiled_content(params={})
+      # Get rep
+      rep_name = params[:rep] || :default
+      rep = reps.find { |r| r.name == rep_name }
+      if rep.nil?
+        raise Nanoc3::Errors::Generic,
+          "No rep named #{rep_name.inspect} was found."
+      end
+
+      # Get rep's content
+      rep.compiled_content(params)
+    end
+
+    # Returns the path from a given representation. This is a convenience
+    # 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.
+    #
+    # @return [String] The path of the given rep ( or the default rep if no
+    #   rep is specified)
+    def path(params={})
+      rep_name = params[:rep] || :default
+
+      # Get rep
+      rep = reps.find { |r| r.name == rep_name }
+      if rep.nil?
+        raise Nanoc3::Errors::Generic,
+          "No rep named #{rep_name.inspect} was found."
+      end
+
+      # Get rep's path
+      rep.path
+    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)
       Nanoc3::NotificationCenter.post(:visit_started, self)
       Nanoc3::NotificationCenter.post(:visit_ended,   self)
@@ -64,20 +130,22 @@ module Nanoc3
     end
 
     # Sets the attribute with the given key to the given value.
+    #
+    # @param [Symbol] key The name of the attribute to set
+    #
+    # @param [Object] value The value of the attribute to set
     def []=(key, value)
       @attributes[key] = value
     end
 
-    # True if any reps are outdated; false otherwise.
+    # Determines whether this item (or rather, its reps) is outdated and
+    # should be recompiled (or rather, its reps should be recompiled).
+    #
+    # @return [Boolean] true if any reps are outdated; false otherwise.
     def outdated?
       @reps.any? { |r| r.outdated? }
     end
 
-    # Alias for #dependencies_outdated.
-    def dependencies_outdated?
-      self.dependencies_outdated
-    end
-
     def inspect
       "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier}>"
     end