nanoc 3.2.4 → 3.3.0

data/lib/nanoc/base/context.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Provides a context and a binding for use in filters such as the ERB and
+  # Haml ones.
+  class Context
+
+    # Creates a new context based off the contents of the hash.
+    #
+    # Each pair in the hash will be converted to an instance variable and an
+    # instance method. For example, passing the hash `{ :foo => 'bar' }` will
+    # cause `@foo` to have the value `"bar"`, and the instance method `#foo`
+    # to return the same value `"bar"`.
+    #
+    # @param [Hash] hash A list of key-value pairs to make available
+    #
+    # @example Defining a context and accessing values
+    #
+    #     context = Nanoc::Context.new(
+    #       :name     => 'Max Payne',
+    #       :location => 'in a cheap motel'
+    #     )
+    #     context.instance_eval do
+    #       "I am #{name} and I am hiding #{@location}."
+    #     end
+    #     # => "I am Max Payne and I am hiding in a cheap motel."
+    def initialize(hash)
+      hash.each_pair do |key, value|
+        # Build instance variable
+        instance_variable_set('@' + key.to_s, value)
+
+        # Define method
+        metaclass = (class << self ; self ; end)
+        metaclass.send(:define_method, key) { value }
+      end
+    end
+
+    # Returns a binding for this instance.
+    #
+    # @return [Binding] A binding for this instance
+    def get_binding
+      binding
+    end
+
+  end
+end

data/lib/nanoc/base/core_ext.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require 'nanoc/base/core_ext/array'
+require 'nanoc/base/core_ext/hash'
+require 'nanoc/base/core_ext/pathname'
+require 'nanoc/base/core_ext/string'

data/lib/nanoc/base/core_ext/array.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+module Nanoc::ArrayExtensions
+
+  # Returns a new array where all items' keys are recursively converted to
+  # symbols by calling {Nanoc::ArrayExtensions#symbolize_keys} or
+  # {Nanoc::HashExtensions#symbolize_keys}.
+  #
+  # @return [Array] The converted array
+  def symbolize_keys
+    inject([]) do |array, element|
+      array + [ element.respond_to?(:symbolize_keys) ? element.symbolize_keys : element ]
+    end
+  end
+
+  # Returns a new array where all items' keys are recursively converted to
+  # strings by calling {Nanoc::ArrayExtensions#stringify_keys} or
+  # {Nanoc::HashExtensions#stringify_keys}.
+  #
+  # @return [Array] The converted array
+  def stringify_keys
+    inject([]) do |array, element|
+      array + [ element.respond_to?(:stringify_keys) ? element.stringify_keys : element ]
+    end
+  end
+
+  # Freezes the contents of the array, as well as all array elements. The
+  # array elements will be frozen using {#freeze_recursively} if they respond
+  # to that message, or #freeze if they do not.
+  #
+  # @see Hash#freeze_recursively
+  #
+  # @return [void]
+  #
+  # @since 3.2.0
+  def freeze_recursively
+    return if self.frozen?
+    freeze
+    each do |value|
+      if value.respond_to?(:freeze_recursively)
+        value.freeze_recursively
+      else
+        value.freeze
+      end
+    end
+  end
+
+  # Calculates the checksum for this array. Any change to this array will
+  # result in a different checksum.
+  #
+  # @return [String] The checksum for this array
+  #
+  # @api private
+  def checksum
+    Marshal.dump(self).checksum
+  end
+
+end
+
+class Array
+  include Nanoc::ArrayExtensions
+end

data/lib/nanoc/base/core_ext/hash.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+module Nanoc::HashExtensions
+
+  # Returns a new hash where all keys are recursively converted to symbols by
+  # calling {Nanoc::ArrayExtensions#symbolize_keys} or
+  # {Nanoc::HashExtensions#symbolize_keys}.
+  #
+  # @return [Hash] The converted hash
+  def symbolize_keys
+    inject({}) do |hash, (key, value)|
+      hash.merge(key.to_sym => value.respond_to?(:symbolize_keys) ? value.symbolize_keys : value)
+    end
+  end
+
+  # Returns a new hash where all keys are recursively converted to strings by
+  # calling {Nanoc::ArrayExtensions#stringify_keys} or
+  # {Nanoc::HashExtensions#stringify_keys}.
+  #
+  # @return [Hash] The converted hash
+  def stringify_keys
+    inject({}) do |hash, (key, value)|
+      hash.merge(key.to_s => value.respond_to?(:stringify_keys) ? value.stringify_keys : value)
+    end
+  end
+
+  # Freezes the contents of the hash, as well as all hash values. The hash
+  # values will be frozen using {#freeze_recursively} if they respond to
+  # that message, or #freeze if they do not.
+  #
+  # @see Array#freeze_recursively
+  #
+  # @return [void]
+  #
+  # @since 3.2.0
+  def freeze_recursively
+    return if self.frozen?
+    freeze
+    each_pair do |key, value|
+      if value.respond_to?(:freeze_recursively)
+        value.freeze_recursively
+      else
+        value.freeze
+      end
+    end
+  end
+
+  # Calculates the checksum for this hash. Any change to this hash will result
+  # in a different checksum.
+  #
+  # @return [String] The checksum for this hash
+  #
+  # @api private
+  def checksum
+    array = self.to_a.sort_by { |kv| kv[0].to_s }
+    array.checksum
+  end
+
+end
+
+class Hash
+  include Nanoc::HashExtensions
+end

data/lib/nanoc/base/core_ext/pathname.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+module Nanoc::PathnameExtensions
+
+  # Calculates the checksum for the file referenced to by this pathname. Any
+  # change to the file contents will result in a different checksum.
+  #
+  # @return [String] The checksum for this file
+  #
+  # @api private
+  def checksum
+    digest = Digest::SHA1.new
+    File.open(self.to_s, 'r') do |io|
+      until io.eof
+        data = io.read(2**10)
+        digest.update(data)
+      end
+    end
+    digest.hexdigest
+  end
+
+end
+
+class Pathname
+  include Nanoc::PathnameExtensions
+end

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

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Nanoc::StringExtensions
+
+  # Transforms string into an actual identifier
+  #
+  # @return [String] The identifier generated from the receiver
+  def cleaned_identifier
+    "/#{self}/".gsub(/^\/+|\/+$/, '/')
+  end
+
+  # Replaces Unicode characters with their ASCII decompositions if the
+  # environment does not support Unicode.
+  #
+  # This method is not suited for general usage. If you need similar
+  # functionality, consider using the Iconv library instead.
+  #
+  # @return [String] The decomposed string
+  def make_compatible_with_env
+    # Check whether environment supports Unicode
+    # 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
+    # FIXME this decomposition is not generally usable
+    self.gsub(/“|”/, '"').gsub(/‘|’/, '\'').gsub('…', '...').gsub('©', '(c)')
+  end
+
+  # Calculates the checksum for this string. Any change to this string will
+  # result in a different checksum.
+  #
+  # @return [String] The checksum for this string
+  #
+  # @api private
+  def checksum
+    digest = Digest::SHA1.new
+    digest.update(self)
+    digest.hexdigest
+  end
+
+end
+
+class String
+  include Nanoc::StringExtensions
+end

data/lib/nanoc/base/directed_graph.rb

@@ -0,0 +1,275 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Represents a directed graph. It is used by the dependency tracker for
+  # storing and querying dependencies between items.
+  #
+  # @example Creating and using a directed graph
+  #
+  #   # Create a graph with three vertices
+  #   graph = Nanoc::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.delete_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
+
+    # The set of vertices in this graph.
+    #
+    # @return [Set]
+    attr_reader :vertices
+
+    # @group Creating a graph
+
+    # Creates a new directed graph with the given vertices.
+    def initialize(vertices)
+      @vertices = Set.new(vertices)
+
+      @from_graph = {}
+      @to_graph   = {}
+
+      @vertice_indexes = {}
+      @vertices.each_with_index do |v, i|
+        @vertice_indexes[v] = i
+      end
+
+      @roots = Set.new(@vertices)
+
+      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
+    #
+    # @param to   Vertex where the edge should end
+    #
+    # @return [void]
+    def add_edge(from, to)
+      add_vertex(from)
+      add_vertex(to)
+
+      @from_graph[from] ||= Set.new
+      @from_graph[from] << to
+
+      @to_graph[to] ||= Set.new
+      @to_graph[to]  << from
+
+      @roots.delete(to)
+
+      invalidate_caches
+    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]
+    #
+    # @since 3.2.0
+    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 v The vertex to add to the graph
+    #
+    # @return [void]
+    #
+    # @since 3.2.0
+    def add_vertex(v)
+      return if @vertices.include?(v)
+
+      @vertices << v
+      @vertice_indexes[v] = @vertices.size-1
+
+      @roots    << v
+    end
+
+    # Deletes all edges coming from the given vertex.
+    #
+    # @param from Vertex from which all edges should be removed
+    #
+    # @return [void]
+    #
+    # @since 3.2.0
+    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)
+      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]
+    #
+    # @since 3.2.0
+    def delete_vertex(v)
+      delete_edges_to(v)
+      delete_edges_from(v)
+
+      @vertices.delete(v)
+      @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.
+    #
+    # @param to The vertex of which the predecessors should be calculated
+    #
+    # @return [Array] Direct predecessors of the given vertex
+    def direct_predecessors_of(to)
+      @to_graph[to].to_a
+    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)
+      @from_graph[from].to_a
+    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)
+      @predecessors[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)
+      @successors[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_with_index do |v, i|
+        direct_successors_of(v).map { |v2| @vertice_indexes[v2] }.each do |i2|
+          result << [ i, i2 ]
+        end
+      end
+      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.
+    #
+    # @since 3.2.0
+    def roots
+      @roots
+    end
+
+    # @group Deprecated methods
+
+    # @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
+    # graph representation is changed.
+    def invalidate_caches
+      @predecessors = {}
+      @successors   = {}
+    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 = Set.new
+
+      processed_vertices   = Set.new
+      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.to_a
+    end
+
+  end
+
+end