nanoc 3.2.4 → 3.3.0

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

@@ -0,0 +1,73 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Contains the processing information for a item.
+  class Rule
+
+    # @return [Regexp] The regex that determines which items this rule can be
+    #   applied to. This rule can be applied to items with a identifier
+    #   matching this regex.
+    attr_reader :identifier_regex
+
+    # @return [Symbol] The name of the representation that will be compiled
+    #   using this rule
+    attr_reader :rep_name
+
+    # @return [Symbol] The name of the snapshot this rule will apply to.
+    #   Ignored for compilation rules, but used for routing rules.
+    #
+    # @since 3.2.0
+    attr_reader :snapshot_name
+
+    # Creates a new item compilation rule with the given identifier regex,
+    # compiler and block. The block will be called during compilation with the
+    # item rep as its argument.
+    #
+    # @param [Regexp] identifier_regex A regular expression that will be used
+    #   to determine whether this rule is applicable to certain items.
+    #
+    # @param [String, Symbol] rep_name The name of the item representation
+    #   where this rule can be applied to
+    #
+    # @param [Proc] block A block that will be called when matching items are
+    #   compiled
+    #
+    # @option params [Symbol, nil] :snapshot (nil) The name of the snapshot
+    #   this rule will apply to. Ignored for compilation rules, but used for
+    #   routing rules.
+    def initialize(identifier_regex, rep_name, block, params={})
+      @identifier_regex = identifier_regex
+      @rep_name         = rep_name.to_sym
+      @snapshot_name    = params[:snapshot_name]
+
+      @block = block
+    end
+
+    # @param [Nanoc::Item] item The item to check
+    #
+    # @return [Boolean] true if this rule can be applied to the given item
+    #   rep, false otherwise
+    def applicable_to?(item)
+      item.identifier =~ @identifier_regex
+    end
+
+    # Applies this rule to the given item rep.
+    #
+    # @param [Nanoc::ItemRep] rep The item representation where this rule
+    #   should be applied to
+    #
+    # @option params [Nanoc::Compiler] :compiler The compiler
+    #
+    # @raise [ArgumentError] if no compiler is passed
+    #
+    # @return [void]
+    def apply_to(rep, params={})
+      compiler = params[:compiler] or raise ArgumentError, "Required :compiler option is missing"
+      rep = Nanoc::ItemRepProxy.new(rep, compiler) unless rep.is_proxy?
+      Nanoc::RuleContext.new(:rep => rep, :compiler => compiler).instance_eval &@block
+    end
+
+  end
+
+end

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

@@ -0,0 +1,84 @@
+module Nanoc
+
+  # Provides a context in which compilation and routing rules can be executed.
+  # It provides access to the item representation that is being compiled or
+  # routed.
+  #
+  # The following variables will be available in this rules context:
+  #
+  # * `rep`     ({Nanoc::ItemRep})         - The current item rep
+  # * `item`    ({Nanoc::Item})            - The current item
+  # * `site`    ({Nanoc::Site})            - The site
+  # * `config`  ({Hash})                    - The site configuration
+  # * `items`   ({Array}<{Nanoc::Item}>)   - A list of all items
+  # * `layouts` ({Array}<{Nanoc::Layout}>) - A list of all layouts
+  #
+  # @api private
+  class RuleContext < Context
+
+    # @option params [Nanoc::ItemRep] :rep The item representation that will
+    #   be processed in this rule context
+    #
+    # @option params [Nanoc::Compiler] :compiler The compiler that is being
+    #   used to compile the site
+    #
+    # @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    => rep.item,
+        :site    => compiler.site,
+        :config  => compiler.site.config,
+        :items   => compiler.site.items,
+        :layouts => compiler.site.layouts
+      })
+    end
+
+    # Filters the current representation (calls {Nanoc::ItemRep#filter} with
+    # the given arguments on the rep).
+    #
+    # @see Nanoc::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(filter_name, filter_args={})
+      rep.filter(filter_name, filter_args)
+    end
+
+    # Layouts the current representation (calls {Nanoc::ItemRep#layout} with
+    # the given arguments on the rep).
+    #
+    # @see Nanoc::ItemRep#layout
+    #
+    # @param [String] layout_identifier The identifier of the layout the item
+    #   should be laid out with
+    #
+    # @return [void]
+    def layout(layout_identifier)
+      rep.layout(layout_identifier)
+    end
+
+    # Creates a snapshot of the current compiled item content. Calls
+    # {Nanoc::ItemRep#snapshot} with the given arguments on the rep.
+    #
+    # @see Nanoc::ItemRep#snapshot
+    #
+    # @param [Symbol] snapshot_name The name of the snapshot to create
+    #
+    # @return [void]
+    def snapshot(snapshot_name)
+      rep.snapshot(snapshot_name)
+    end
+
+  end
+
+end

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

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Calculates rule memories for objects that can be run through a rule (item
+  # representations and layouts).
+  #
+  # @api private
+  class RuleMemoryCalculator
+
+    extend Nanoc::Memoization
+
+    # @option params [Nanoc::RulesCollection] rules_collection The rules
+    #   collection
+    def initialize(params={})
+      @rules_collection = params[:rules_collection] or
+        raise ArgumentError, "Required :rules_collection option is missing"
+    end
+
+    # @param [#reference] obj The object to calculate the rule memory for
+    #
+    # @return [Array] The caluclated rule memory for the given object
+    def [](obj)
+      result = case obj.type
+        when :item_rep
+          @rules_collection.new_rule_memory_for_rep(obj)
+        when :layout
+          @rules_collection.new_rule_memory_for_layout(obj)
+        else
+          raise RuntimeError,
+            "Do not know how to calculate the rule memory for #{obj.inspect}"
+      end
+
+      result
+    end
+    memoize :[]
+
+  end
+
+end

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

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Stores rule memories for objects that can be run through a rule (item
+  # representations and layouts).
+  #
+  # @api private
+  class RuleMemoryStore < ::Nanoc::Store
+
+    # @option params [Nanoc::Site] site The site where this rule memory store
+    #   belongs to
+    def initialize(params={})
+      super('tmp/rule_memory', 1)
+
+      @site = params[:site] if params.has_key?(:site)
+
+      @rule_memories = {}
+    end
+
+    # @param [Nanoc::ItemRep, Nanoc::Layout] obj The item representation or
+    #   the layout to get the rule memory for
+    #
+    # @return [Array] The rule memory for the given object
+    def [](obj)
+      @rule_memories[obj.reference]
+    end
+
+    # @param [Nanoc::ItemRep, Nanoc::Layout] obj The item representation or
+    #   the layout to set the rule memory for
+    #
+    # @param [Array] rule_memory The new rule memory to be stored
+    #
+    # @return [void]
+    def []=(obj, rule_memory)
+      @rule_memories[obj.reference] = rule_memory
+    end
+
+  protected
+
+    # @see Nanoc::Store#data
+    def data
+      @rule_memories
+    end
+
+    # @see Nanoc::Store#data=
+    def data=(new_data)
+      @rule_memories = new_data
+    end
+
+  end
+
+end

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

@@ -0,0 +1,243 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Keeps track of the rules in a site.
+  #
+  # @api private
+  class RulesCollection
+
+    extend Nanoc::Memoization
+
+    # @return [Array<Nanoc::Rule>] The list of item compilation rules that
+    #   will be used to compile items.
+    attr_reader :item_compilation_rules
+
+    # @return [Array<Nanoc::Rule>] The list of routing rules that will be
+    #   used to give all items a path.
+    attr_reader :item_routing_rules
+
+    # The hash containing layout-to-filter mapping rules. This hash is
+    # ordered: iterating over the hash will happen in insertion order.
+    #
+    # @return [Hash] The layout-to-filter mapping rules
+    attr_reader :layout_filter_mapping
+
+    # @return [Proc] The code block that will be executed after all data is
+    #   loaded but before the site is compiled
+    attr_accessor :preprocessor
+
+    # @param [Nanoc::Compiler] compiler The site’s compiler
+    def initialize(compiler)
+      @compiler = compiler
+
+      @item_compilation_rules  = []
+      @item_routing_rules      = []
+      @layout_filter_mapping   = OrderedHash.new
+    end
+
+    # Add the given rule to the list of item compilation rules.
+    #
+    # @param [Nanoc::Rule] rule The item compilation rule to add
+    #
+    # @param [:before, :after] position The place where the rule should be
+    #   added (either at the beginning or the end of the list of rules)
+    #
+    # @return [void]
+    def add_item_compilation_rule(rule, position=:after)
+      case position
+      when :before
+        @item_compilation_rules.unshift(rule)
+      when :after
+        @item_compilation_rules << rule
+      else
+        raise "#add_item_routing_rule expected position to be :after or :before"
+      end
+    end
+
+    # Add the given rule to the list of item routing rules.
+    #
+    # @param [Nanoc::Rule] rule The item routing rule to add
+    #
+    # @param [:before, :after] position The place where the rule should be
+    #   added (either at the beginning or the end of the list of rules)
+    #
+    # @return [void]
+    def add_item_routing_rule(rule, position=:after)
+      case position
+      when :before
+        @item_routing_rules.unshift(rule)
+      when :after
+        @item_routing_rules << rule
+      else
+        raise "#add_item_routing_rule expected position to be :after or :before"
+      end
+    end
+
+    # @param [Nanoc::Item] item The item for which the compilation rules
+    #   should be retrieved
+    #
+    # @return [Array] The list of item compilation rules for the given item
+    def item_compilation_rules_for(item)
+      @item_compilation_rules.select { |r| r.applicable_to?(item) }
+    end
+
+    # Loads this site’s rules.
+    #
+    # @return [void]
+    def load
+      # Find rules file
+      rules_filenames = [ 'Rules', 'rules', 'Rules.rb', 'rules.rb' ]
+      rules_filename = rules_filenames.find { |f| File.file?(f) }
+      raise Nanoc::Errors::NoRulesFileFound.new if rules_filename.nil?
+
+      # Get rule data
+      @data = File.read(rules_filename)
+
+      # Load DSL
+      dsl.instance_eval(@data, "./#{rules_filename}")
+    end
+
+    # Unloads this site’s rules.
+    #
+    # @return [void]
+    def unload
+      @item_compilation_rules  = []
+      @item_routing_rules      = []
+      @layout_filter_mapping   = OrderedHash.new
+    end
+
+    # Finds the first matching compilation rule for the given item
+    # representation.
+    #
+    # @param [Nanoc::ItemRep] rep The item rep for which to fetch the rule
+    #
+    # @return [Nanoc::Rule, nil] The compilation rule for the given item rep,
+    #   or nil if no rules have been found
+    def compilation_rule_for(rep)
+      @item_compilation_rules.find do |rule|
+        rule.applicable_to?(rep.item) && rule.rep_name == rep.name
+      end
+    end
+
+    # Finds the first matching routing rule for the given item representation.
+    #
+    # @param [Nanoc::ItemRep] rep The item rep for which to fetch the rule
+    #
+    # @return [Nanoc::Rule, nil] The routing rule for the given item rep, or
+    #   nil if no rules have been found
+    def routing_rule_for(rep)
+      @item_routing_rules.find do |rule|
+        rule.applicable_to?(rep.item) && rule.rep_name == rep.name
+      end
+    end
+
+    # Returns the list of routing rules that can be applied to the given item
+    # representation. For each snapshot, the first matching rule will be
+    # returned. The result is a hash containing the corresponding rule for
+    # each snapshot.
+    #
+    # @param [Nanoc::ItemRep] rep The item rep for which to fetch the rules
+    #
+    # @return [Hash<Symbol, Nanoc::Rule>] The routing rules for the given rep
+    def routing_rules_for(rep)
+      rules = {}
+      @item_routing_rules.each do |rule|
+        next if !rule.applicable_to?(rep.item)
+        next if rule.rep_name != rep.name
+        next if rules.has_key?(rule.snapshot_name)
+
+        rules[rule.snapshot_name] = rule
+      end
+      rules
+    end
+
+    # Finds the filter name and arguments to use for the given layout.
+    #
+    # @param [Nanoc::Layout] layout The layout for which to fetch the filter.
+    #
+    # @return [Array, nil] A tuple containing the filter name and the filter 
+    #   arguments for the given layout.
+    def filter_for_layout(layout)
+      @layout_filter_mapping.each_pair do |layout_identifier, filter_name_and_args|
+        return filter_name_and_args if layout.identifier =~ layout_identifier
+      end
+      nil
+    end
+
+    # Returns the Nanoc::CompilerDSL that should be used for this site.
+    def dsl
+      Nanoc::CompilerDSL.new(self, @compiler.site.config)
+    end
+    memoize :dsl
+
+    # Returns an object that can be used for uniquely identifying objects.
+    #
+    # @return [Object] An unique reference to this object
+    def reference
+      :rules
+    end
+
+    # @return [String] The checksum for this object. If its contents change,
+    #   the checksum will change as well.
+    def checksum
+      @data.checksum
+    end
+
+    def inspect
+      "<#{self.class}>"
+    end
+
+    # @param [Nanoc::ItemRep] rep The item representation to get the rule
+    #   memory for
+    #
+    # @return [Array] The rule memory for the given item representation
+    def new_rule_memory_for_rep(rep)
+      recording_proxy = rep.to_recording_proxy
+      compilation_rule_for(rep).apply_to(recording_proxy, :compiler => @compiler)
+      recording_proxy.rule_memory
+    end
+    memoize :new_rule_memory_for_rep
+
+    # @param [Nanoc::Layout] layout The layout to get the rule memory for
+    #
+    # @return [Array] The rule memory for the given layout
+    def new_rule_memory_for_layout(layout)
+      filter_for_layout(layout)
+    end
+    memoize :new_rule_memory_for_layout
+
+    # @param [Nanoc::ItemRep] rep The item representation for which to fetch
+    #   the list of snapshots
+    #
+    # @return [Array] A list of snapshots, represented as arrays where the
+    #   first element is the snapshot name (a Symbol) and the last element is
+    #   a Boolean indicating whether the snapshot is final or not
+    def snapshots_for(rep)
+      new_rule_memory_for_rep(rep).select { |e| e[0] == :snapshot }.map do |e|
+        [ e[1], e[2].fetch(:final) { true } ]
+      end
+    end
+
+    # @param [Nanoc::Item] obj The object for which to check the rule memory
+    #
+    # @return [Boolean] true if the rule memory for the given object has
+    # changed since the last compilation, false otherwise
+    def rule_memory_differs_for(obj)
+      !rule_memory_store[obj].eql?(rule_memory_calculator[obj])
+    end
+    memoize :rule_memory_differs_for
+
+    # @return [Nanoc::RuleMemoryStore] The rule memory store
+    def rule_memory_store
+      @compiler.rule_memory_store
+    end
+
+    # @return [Nanoc::RuleMemoryCalculator] The rule memory calculator
+    def rule_memory_calculator
+      @compiler.rule_memory_calculator
+    end
+
+  end
+
+end