nanoc 3.2.4 → 3.3.0

data/lib/nanoc/base/compilation/compiler_dsl.rb

@@ -0,0 +1,214 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Contains methods that will be executed by the site’s `Rules` file.
+  class CompilerDSL
+
+    # Creates a new compiler DSL for the given collection of rules.
+    #
+    # @api private
+    #
+    # @param [Nanoc::RulesCollection] rules_collection The collection of
+    #   rules to modify when loading this DSL
+    #
+    # @param [Hash] config The site configuration
+    def initialize(rules_collection, config)
+      @rules_collection = rules_collection
+      @config = config
+    end
+
+    # Creates a preprocessor block that will be executed after all data is
+    # loaded, but before the site is compiled.
+    #
+    # @yield The block that will be executed before site compilation starts
+    #
+    # @return [void]
+    def preprocess(&block)
+      @rules_collection.preprocessor = block
+    end
+
+    # Creates a compilation rule for all items whose identifier match the
+    # given identifier, which may either be a string containing the *
+    # wildcard, or a regular expression.
+    #
+    # This rule will be applicable to reps with a name equal to `:default`;
+    # this can be changed by giving an explicit `:rep` parameter.
+    #
+    # An item rep will be compiled by calling the given block and passing the
+    # rep as a block argument.
+    #
+    # @param [String] identifier A pattern matching identifiers of items that
+    #   should be compiled using this rule
+    #
+    # @option params [Symbol] :rep (:default) The name of the representation
+    #   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
+    #
+    # @return [void]
+    #
+    # @example Compiling the default rep of the `/foo/` item
+    #
+    #     compile '/foo/' do
+    #       rep.filter :erb
+    #     end
+    #
+    # @example Compiling the `:raw` rep of the `/bar/` item
+    #
+    #     compile '/bar/', :rep => :raw do
+    #       # do nothing
+    #     end
+    def compile(identifier, params={}, &block)
+      # Require block
+      raise ArgumentError.new("#compile requires a block") unless block_given?
+
+      # Get rep name
+      rep_name = params[:rep] || :default
+
+      # Create rule
+      rule = Rule.new(identifier_to_regex(identifier), rep_name, block)
+      @rules_collection.add_item_compilation_rule(rule)
+    end
+
+    # Creates a routing rule for all items whose identifier match the
+    # given identifier, which may either be a string containing the `*`
+    # wildcard, or a regular expression.
+    #
+    # This rule will be applicable to reps with a name equal to `:default`;
+    # this can be changed by giving an explicit `:rep` parameter.
+    #
+    # The path of an item rep will be determined by calling the given block
+    # and passing the rep as a block argument.
+    #
+    # @param [String] identifier A pattern matching identifiers of items that
+    #   should be routed using this rule
+    #
+    # @option params [Symbol] :rep (:default) The name of the representation
+    #   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
+    #
+    # @return [void]
+    #
+    # @example Routing the default rep of the `/foo/` item
+    #
+    #     route '/foo/' do
+    #       item.identifier + 'index.html'
+    #     end
+    #
+    # @example Routing the `:raw` rep of the `/bar/` item
+    #
+    #     route '/bar/', :rep => :raw do
+    #       '/raw' + item.identifier + 'index.txt'
+    #     end
+    def route(identifier, params={}, &block)
+      # Require block
+      raise ArgumentError.new("#route requires a block") unless block_given?
+
+      # Get rep name
+      rep_name      = params[:rep] || :default
+      snapshot_name = params[:snapshot] || :last
+
+      # Create rule
+      rule = Rule.new(identifier_to_regex(identifier), rep_name, block, :snapshot_name => snapshot_name)
+      @rules_collection.add_item_routing_rule(rule)
+    end
+
+    # Creates a layout rule for all layouts whose identifier match the given
+    # identifier, which may either be a string containing the * wildcard, or a
+    # regular expression. The layouts matching the identifier will be filtered
+    # using the filter specified in the second argument. The params hash
+    # 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
+    #
+    # @param [Symbol] filter_name The name of the filter that should be run
+    #   when processing the layout
+    #
+    # @param [Hash] params Extra filter arguments that should be passed to the
+    #   filter when processing the layout (see {Nanoc::Filter#run})
+    #
+    # @return [void]
+    #
+    # @example Specifying the filter to use for a layout
+    #
+    #     layout '/default/', :erb
+    #
+    # @example Using custom filter arguments for a layout
+    #
+    #     layout '/custom/',  :haml, :format => :html5
+    def layout(identifier, filter_name, params={})
+      @rules_collection.layout_filter_mapping[identifier_to_regex(identifier)] = [ filter_name, params ]
+    end
+
+    # Creates a pair of compilation and routing rules that indicate that the
+    # specified item(s) should be copied to the output folder as-is. The items
+    # are selected using an identifier, which may either be a string
+    # containing the `*` wildcard, or a regular expression.
+    #
+    # This meta-rule will be applicable to reps with a name equal to
+    # `:default`; this can be changed by giving an explicit `:rep` parameter.
+    #
+    # @param [String] identifier A pattern matching identifiers of items that
+    #   should be processed using this meta-rule
+    #
+    # @option params [Symbol] :rep (:default) The name of the representation
+    #   that should be routed using this rule
+    #
+    # @return [void]
+    #
+    # @since 3.2.0
+    #
+    # @example Copying the `/foo/` item as-is
+    #
+    #     passthrough '/foo/'
+    #
+    # @example Copying the `:raw` rep of the `/bar/` item as-is
+    #
+    #     passthrough '/bar/', :rep => :raw
+    def passthrough(identifier, params={})
+      # Require no block
+      raise ArgumentError.new("#passthrough does not require a block") if block_given?
+
+      # Get rep name
+      rep_name = params[:rep] || :default
+
+      # Create compilation rule
+      compilation_block = proc { }
+      compilation_rule = Rule.new(identifier_to_regex(identifier), rep_name, compilation_block)
+      @rules_collection.add_item_compilation_rule(compilation_rule, :before)
+
+      # Create routing rule
+      routing_block = proc do
+        item.identifier.chop + '.' + item[:extension]
+      end
+      routing_rule = Rule.new(identifier_to_regex(identifier), rep_name, routing_block)
+      @rules_collection.add_item_routing_rule(routing_rule, :before)
+    end
+
+  private
+
+    # Converts the given identifier, which can contain the '*' or '+'
+    # wildcard characters, matching zero or more resp. one or more
+    # characters, to a regex. For example, 'foo/*/bar' is transformed
+    # into /^foo\/(.*?)\/bar$/ and 'foo+' is transformed into /^foo(.+?)/.
+    def identifier_to_regex(identifier)
+      if identifier.is_a? String
+        # Add leading/trailing slashes if necessary
+        new_identifier = identifier.dup
+        new_identifier[/^/] = '/' if identifier[0,1] != '/'
+        new_identifier[/$/] = '/' unless [ '*', '/' ].include?(identifier[-1,1])
+
+        /^#{new_identifier.gsub('*', '(.*?)').gsub('+', '(.+?)')}$/
+      else
+        identifier
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/compilation/dependency_tracker.rb

@@ -0,0 +1,200 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # 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 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
+  # {Nanoc::Compiler}) cannot be mutually recursive, the more general
+  # dependencies in Nanoc::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.
+  #
+  # @api private
+  class DependencyTracker < ::Nanoc::Store
+
+    # @return [Array<Nanoc::Item, Nanoc::Layout>] The list of items and
+    #   layouts that are being tracked by the dependency tracker
+    attr_reader :objects
+
+    # @return [Nanoc::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<Nanoc::Item, Nanoc::Layout>] objects The list of items
+    #   and layouts whose dependencies should be managed
+    def initialize(objects)
+      super('tmp/dependencies', 4)
+
+      @objects = objects
+
+      @graph = Nanoc::DirectedGraph.new([ nil ] + @objects)
+    end
+
+    # Starts listening for dependency messages (`:visit_started` and
+    # `:visit_ended`) and start recording dependencies.
+    #
+    # @return [void]
+    def start
+      # 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
+      Nanoc::NotificationCenter.on(:visit_started, self) do |obj|
+        if !@stack.empty?
+          Nanoc::NotificationCenter.post(:dependency_created, @stack.last, obj)
+          self.record_dependency(@stack.last, obj)
+        end
+        @stack.push(obj)
+      end
+
+      # Register end of visits
+      Nanoc::NotificationCenter.on(:visit_ended, self) do |obj|
+        @stack.pop
+      end
+    end
+
+    # Stop listening for dependency messages and stop recording dependencies.
+    #
+    # @return [void]
+    def stop
+      # Unregister
+      Nanoc::NotificationCenter.remove(:visit_started, self)
+      Nanoc::NotificationCenter.remove(:visit_ended,   self)
+    end
+
+    # Returns the direct dependencies for the given object.
+    #
+    # 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).
+    #
+    # The direct predecessors can include nil, which indicates an item that is
+    # no longer present in the site.
+    #
+    # @param [Nanoc::Item, Nanoc::Layout] object The object for
+    #   which to fetch the direct predecessors
+    #
+    # @return [Array<Nanoc::Item, Nanoc::Layout, nil>] The direct
+    # predecessors of
+    #   the given object
+    def objects_causing_outdatedness_of(object)
+      @graph.direct_predecessors_of(object)
+    end
+
+    # Returns the direct inverse dependencies for the given object.
+    #
+    # 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 [Nanoc::Item, Nanoc::Layout] object The object for which to
+    #   fetch the direct successors
+    #
+    # @return [Array<Nanoc::Item, Nanoc::Layout>] The direct successors of
+    #   the given object
+    def objects_outdated_due_to(object)
+      @graph.direct_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 [Nanoc::Item, Nanoc::Layout] src The source of the dependency,
+    #   i.e. the object that will become outdated if dst is outdated
+    #
+    # @param [Nanoc::Item, Nanoc::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)
+      # Warning! dst and src are *reversed* here!
+      @graph.add_edge(dst, src) unless src == dst
+    end
+
+    # 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.
+    #
+    # @api private
+    #
+    # @param [Nanoc::Item, Nanoc::Layout] object The object for which to
+    #   forget all dependencies
+    #
+    # @return [void]
+    def forget_dependencies_for(object)
+      @graph.delete_edges_to(object)
+    end
+
+    # @deprecated Use {#store} instead
+    def store_graph
+      self.store
+    end
+
+    # @deprecated Use {#load} instead
+    def load_graph
+      self.load
+    end
+
+    # @see Nanoc::Store#unload
+    def unload
+      @graph = Nanoc::DirectedGraph.new([ nil ] + @objects)
+    end
+
+  protected
+
+    def data
+      {
+        :edges    => @graph.edges,
+        :vertices => @graph.vertices.map { |obj| obj && obj.reference }
+      }
+    end
+
+    def data=(new_data)
+      # Create new graph
+      @graph = Nanoc::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 = from_index && previous_objects[from_index]
+        to   = to_index   && previous_objects[to_index]
+        @graph.add_edge(from, to)
+      end
+
+      # Record dependency from all items on new items
+      new_objects = (@objects - previous_objects)
+      new_objects.each do |new_obj|
+        @objects.each do |obj|
+          next unless obj.is_a?(Nanoc::Item)
+          @graph.add_edge(new_obj, obj)
+        end
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/compilation/filter.rb

@@ -0,0 +1,165 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Nanoc::Filter is responsible for filtering items. It is the superclass
+  # for all textual filters.
+  #
+  # A filter instance should only be used once. Filters should not be reused
+  # since they store state.
+  #
+  # 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
+
+    # The path to the directory where temporary binary items are stored
+    TMP_BINARY_ITEMS_DIR = 'tmp/binary_items'
+
+    # A hash containing variables that will be made available during
+    # filtering.
+    #
+    # @return [Hash]
+    attr_reader :assigns
+
+    extend Nanoc::PluginRegistry::PluginMethods
+
+    class << self
+
+      # Sets the new type for the filter. The type can be `:binary` (default)
+      # or `:text`. The given argument can either be a symbol indicating both
+      # “from” and “to” types, or a hash where the only key is the “from” type
+      # and the only value is the “to” type.
+      #
+      # @example Specifying a text-to-text filter
+      #
+      #     type :text
+      #
+      # @example Specifying a text-to-binary filter
+      #
+      #     type :text => :binary
+      #
+      # @param [Symbol, Hash] arg The new type of this filter
+      #
+      # @return [void]
+      def type(arg)
+        if arg.is_a?(Hash)
+          @from, @to = arg.keys[0], arg.values[0]
+        else
+          @from, @to = arg, arg
+        end
+      end
+
+      # @return [Boolean] True if this filter can be applied to binary item
+      #   representations, false otherwise
+      def from_binary?
+        (@from || :text) == :binary
+      end
+
+      # @return [Boolean] True if this filter results in a binary item
+      #   representation, false otherwise
+      def to_binary?
+        (@to || :text) == :binary
+      end
+
+    end
+
+    # Creates a new filter that has access to the given assigns.
+    #
+    # @param [Hash] hash A hash containing variables that should be made
+    #   available during filtering.
+    def initialize(hash={})
+      @assigns = hash
+      super
+    end
+
+    # Runs the filter on the given content or filename.
+    #
+    # @abstract
+    #
+    # @param [String] content_or_filename The unprocessed content that should
+    #   be filtered (if the item is a textual item) or the path to the file
+    #   that should be filtered (if the item is a binary item)
+    #
+    # @param [Hash] params A hash containing parameters. Filter subclasses can
+    #   use these parameters to allow modifying the filter's behaviour.
+    #
+    # @return [String, void] If the filter output binary content, the return
+    #   value is undefined; if the filter outputs textual content, the return
+    #   value will be the filtered content.
+    def run(content_or_filename, params={})
+      raise NotImplementedError.new("Nanoc::Filter subclasses must implement #run")
+    end
+
+    # Returns a filename that is used to write data to. This method is only
+    #   used on binary items. When running a binary filter on a file, the
+    #   resulting file must end up in the location returned by this method.
+    #
+    # The returned filename will be absolute, so it is safe to change to
+    #   another directory inside the filter.
+    #
+    # @return [String] The output filename
+    def output_filename
+      @output_filename ||= begin
+        FileUtils.mkdir_p(TMP_BINARY_ITEMS_DIR)
+        tempfile = Tempfile.new(filename.gsub(/[^a-z]/, '-'), TMP_BINARY_ITEMS_DIR)
+        new_filename = tempfile.path
+        tempfile.close!
+
+        File.expand_path(new_filename)
+      end
+    end
+
+    # Returns the filename associated with the item that is being filtered.
+    #   It is in the format `item <identifier> (rep <name>)`.
+    #
+    # @return [String] The filename
+    def filename
+      if assigns[:layout]
+        "layout #{assigns[:layout].identifier}"
+      elsif assigns[:item]
+        "item #{assigns[:item].identifier} (rep #{assigns[:item_rep].name})"
+      else
+        '?'
+      end
+    end
+
+    # Creates a dependency from the item that is currently being filtered onto
+    # the given collection of items. In other words, require the given items
+    # to be compiled first before this items is processed.
+    #
+    # @param [Array<Nanoc::Item>] items The items that are depended on.
+    #
+    # @return [void]
+    def depend_on(items)
+      # Notify
+      items.each do |item|
+        Nanoc::NotificationCenter.post(:visit_started, item)
+        Nanoc::NotificationCenter.post(:visit_ended,   item)
+      end
+
+      # Raise unmet dependency error if necessary
+      items.each do |item|
+        rep = item.reps.find { |r| !r.compiled? }
+        raise Nanoc::Errors::UnmetDependency.new(rep) if rep
+      end
+    end
+
+  end
+
+end