nanoc 3.2.4 → 3.3.0

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

@@ -0,0 +1,103 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Represents an item representation, but provides an interface that is
+  # easier to use when writing compilation and routing rules. It is also
+  # responsible for fetching the necessary information from the compiler, such
+  # as assigns.
+  #
+  # The API provided by item representation proxies allows layout identifiers
+  # to be given as literals instead of as references to {Nanoc::Layout}.
+  class ItemRepProxy
+
+    extend Forwardable
+
+    def_delegators :@item_rep, :item, :name, :binary, :binary?, :compiled_content, :has_snapshot?, :raw_path, :path
+    def_delegator  :@item_rep, :snapshot
+
+    # @param [Nanoc::ItemRep] item_rep The item representation that this
+    #   proxy should behave like
+    #
+    # @param [Nanoc::Compiler] compiler The compiler that will provide the
+    #   necessary compilation-related functionality.
+    def initialize(item_rep, compiler)
+      @item_rep = item_rep
+      @compiler = compiler
+    end
+
+    # Runs the item content through the given filter with the given arguments.
+    # This method will replace the content of the `:last` snapshot with the
+    # filtered content of the last snapshot.
+    #
+    # This method is supposed to be called only in a compilation rule block
+    # (see {Nanoc::CompilerDSL#compile}).
+    #
+    # @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(name, args={})
+      set_assigns
+      @item_rep.filter(name, args)
+    end
+
+    # Lays out the item using the given layout. This method will replace the
+    # content of the `:last` snapshot with the laid out content of the last
+    # snapshot.
+    #
+    # This method is supposed to be called only in a compilation rule block
+    # (see {Nanoc::CompilerDSL#compile}).
+    #
+    # @see Nanoc::ItemRep#layout
+    #
+    # @param [String] layout_identifier The identifier of the layout to use
+    #
+    # @return [void]
+    def layout(layout_identifier, extra_filter_args={})
+      set_assigns
+
+      layout = layout_with_identifier(layout_identifier)
+      filter_name, filter_args = @compiler.rules_collection.filter_for_layout(layout)
+      filter_args = filter_args.merge(extra_filter_args)
+
+      @item_rep.layout(layout, filter_name, filter_args)
+    end
+
+    # Returns true because this item is already a proxy, and therefore doesn’t
+    # need to be wrapped anymore.
+    #
+    # @api private
+    #
+    # @return [true]
+    #
+    # @see Nanoc::ItemRep#is_proxy?
+    # @see Nanoc::ItemRepRecorderProxy#is_proxy?
+    def is_proxy?
+      true
+    end
+
+  private
+
+    def set_assigns
+      @item_rep.assigns = @compiler.assigns_for(@item_rep)
+    end
+
+    def layouts
+      @compiler.site.layouts
+    end
+
+    def layout_with_identifier(layout_identifier)
+      layout ||= layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
+      raise Nanoc::Errors::UnknownLayout.new(layout_identifier) if layout.nil?
+      layout
+    end
+
+  end
+
+end

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

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Represents a fake iem representation that does not actually perform any
+  # actual filtering, layouting or snapshotting, but instead keeps track of
+  # what would happen if a real item representation would have been used
+  # instead. It therefore “records” the actions that happens upon it.
+  #
+  # The list of recorded actions is used during compilation to determine
+  # whether an item representation needs to be recompiled: if the list of
+  # actions is different from the list of actions from the previous
+  # compilation run, the item needs to be recompiled; if it is the same, it
+  # may not need to be recompiled.
+  #
+  # @api private
+  class ItemRepRecorderProxy
+
+    extend Forwardable
+
+    def_delegators :@item_rep, :item, :name, :binary, :binary?, :compiled_content, :has_snapshot?, :raw_path, :path, :assigns, :assigns=
+
+    # @example The compilation rule and the corresponding rule memory
+    #
+    #     # rule
+    #     compile '/foo/' do
+    #       filter :erb
+    #       filter :myfilter, :arg1 => 'stuff'
+    #       layout 'meh'
+    #     end
+    #
+    #     # memory
+    #     [
+    #       [ :filter, :erb, {} ],
+    #       [ :filter, :myfilter, { :arg1 => 'stuff' } ],
+    #       [ :layout, 'meh' ]
+    #     ]
+    #
+    # @return [Array] The list of recorded actions (“rule memory”)
+    attr_reader :rule_memory
+
+    # @param [Nanoc::ItemRep] item_rep The item representation that this
+    #   proxy should behave like
+    def initialize(item_rep)
+      @item_rep = item_rep
+      @rule_memory = []
+    end
+
+    # @return [void]
+    #
+    # @see Nanoc::ItemRepProxy#filter, Nanoc::ItemRep#filter
+    def filter(name, args={})
+      @rule_memory << [ :filter, name, args ]
+    end
+
+    # @return [void]
+    #
+    # @see Nanoc::ItemRepProxy#layout, Nanoc::ItemRep#layout
+    def layout(layout_identifier, extra_filter_args=nil)
+      if extra_filter_args
+        @rule_memory << [ :layout, layout_identifier, extra_filter_args ]
+      else
+        @rule_memory << [ :layout, layout_identifier ]
+      end
+    end
+
+    # @return [void]
+    #
+    # @see Nanoc::ItemRep#snapshot
+    def snapshot(snapshot_name, params={})
+      @rule_memory << [ :snapshot, snapshot_name, params ]
+
+      # Count
+      existing = Set.new
+      names = @rule_memory.select { |r| r[0] == :snapshot }.map { |r| r[2] }
+      names.each do |n|
+        if existing.include?(n)
+          raise Nanoc::Errors::CannotCreateMultipleSnapshotsWithSameName.new(@item_rep, snapshot_name)
+        end
+        existing << n
+      end
+    end
+
+    # @return [{}]
+    def content
+      {}
+    end
+
+    # Returns true because this item is already a proxy, and therefore doesn’t
+    # need to be wrapped anymore.
+    #
+    # @return [true]
+    #
+    # @see Nanoc::ItemRep#is_proxy?
+    # @see Nanoc::ItemRepProxy#is_proxy?
+    def is_proxy?
+      true
+    end
+
+  end
+
+end

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

@@ -0,0 +1,223 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Responsible for determining whether an item or a layout is outdated.
+  #
+  # @api private
+  class OutdatednessChecker
+
+    extend Nanoc::Memoization
+
+    # @option params [Nanoc::Site] :site (nil) The site this outdatedness
+    #   checker belongs to.
+    #
+    # @option params [Nanoc::ChecksumStore] :checksum_store (nil) The
+    #   checksum store where checksums of items, layouts, … are stored.
+    #
+    # @option params [Nanoc::DependencyTracker] :dependency_tracker (nil) The
+    #   dependency tracker for the given site.
+    def initialize(params={})
+      @site = params[:site] or raise ArgumentError,
+        'Nanoc::OutdatednessChecker#initialize needs a :site parameter'
+      @checksum_store = params[:checksum_store] or raise ArgumentError,
+        'Nanoc::OutdatednessChecker#initialize needs a :checksum_store parameter'
+      @dependency_tracker = params[:dependency_tracker] or raise ArgumentError,
+        'Nanoc::OutdatednessChecker#initialize needs a :dependency_tracker parameter'
+
+      @basic_outdatedness_reasons = {}
+      @outdatedness_reasons = {}
+      @objects_outdated_due_to_dependencies = {}
+    end
+
+    # Checks whether the given object is outdated and therefore needs to be
+    # recompiled.
+    #
+    # @param [Nanoc::Item, Nanoc::ItemRep, Nanoc::Layout] obj The object
+    #   whose outdatedness should be checked.
+    #
+    # @return [Boolean] true if the object is outdated, false otherwise
+    def outdated?(obj)
+      !outdatedness_reason_for(obj).nil?
+    end
+
+    # Calculates the reason why the given object is outdated.
+    #
+    # @param [Nanoc::Item, Nanoc::ItemRep, Nanoc::Layout] obj The object
+    #   whose outdatedness reason should be calculated.
+    #
+    # @return [Nanoc::OutdatednessReasons::Generic, nil] The reason why the
+    #   given object is outdated, or nil if the object is not outdated.
+    def outdatedness_reason_for(obj)
+      reason = basic_outdatedness_reason_for(obj)
+      if reason.nil? && outdated_due_to_dependencies?(obj)
+        reason = Nanoc::OutdatednessReasons::DependenciesOutdated
+      end
+      reason
+    end
+    memoize :outdatedness_reason_for
+
+  private
+
+    # Checks whether the given object is outdated and therefore needs to be
+    # recompiled. This method does not take dependencies into account; use
+    # {#outdated?} if you want to include dependencies in the outdatedness
+    # check.
+    #
+    # @param [Nanoc::Item, Nanoc::ItemRep, Nanoc::Layout] obj The object
+    #   whose outdatedness should be checked.
+    #
+    # @return [Boolean] true if the object is outdated, false otherwise
+    def basic_outdated?(obj)
+      !basic_outdatedness_reason_for(obj).nil?
+    end
+
+    # Calculates the reason why the given object is outdated. This method does
+    # not take dependencies into account; use {#outdatedness_reason_for?} if
+    # you want to include dependencies in the outdatedness check.
+    #
+    # @param [Nanoc::Item, Nanoc::ItemRep, Nanoc::Layout] obj The object
+    #   whose outdatedness reason should be calculated.
+    #
+    # @return [Nanoc::OutdatednessReasons::Generic, nil] The reason why the
+    #   given object is outdated, or nil if the object is not outdated.
+    def basic_outdatedness_reason_for(obj)
+      case obj.type
+        when :item_rep
+          # Outdated if rules outdated
+          return Nanoc::OutdatednessReasons::RulesModified if
+            rule_memory_differs_for(obj)
+
+          # Outdated if checksums are missing or different
+          return Nanoc::OutdatednessReasons::NotEnoughData if !checksums_available?(obj.item)
+          return Nanoc::OutdatednessReasons::SourceModified if !checksums_identical?(obj.item)
+
+          # Outdated if compiled file doesn't exist (yet)
+          return Nanoc::OutdatednessReasons::NotWritten if obj.raw_path && !File.file?(obj.raw_path)
+
+          # Outdated if code snippets outdated
+          return Nanoc::OutdatednessReasons::CodeSnippetsModified if site.code_snippets.any? do |cs|
+            object_modified?(cs)
+          end
+
+          # Outdated if configuration outdated
+          return Nanoc::OutdatednessReasons::ConfigurationModified if object_modified?(site.config)
+
+          # Not outdated
+          return nil
+        when :item
+          obj.reps.find { |rep| basic_outdatedness_reason_for(rep) }
+        when :layout
+          # Outdated if rules outdated
+          return Nanoc::OutdatednessReasons::RulesModified if
+            rule_memory_differs_for(obj)
+
+          # Outdated if checksums are missing or different
+          return Nanoc::OutdatednessReasons::NotEnoughData if !checksums_available?(obj)
+          return Nanoc::OutdatednessReasons::SourceModified if !checksums_identical?(obj)
+
+          # Not outdated
+          return nil
+        else
+          raise RuntimeError, "do not know how to check outdatedness of #{obj.inspect}"
+      end
+    end
+    memoize :basic_outdatedness_reason_for
+
+    # Checks whether the given object is outdated due to dependencies.
+    #
+    # @param [Nanoc::Item, Nanoc::ItemRep, Nanoc::Layout] obj The object
+    #   whose outdatedness should be checked.
+    #
+    # @param [Set] processed The collection of items that has been visited
+    #   during this outdatedness check. This is used to prevent checks for
+    #   items that (indirectly) depend on their own from looping
+    #   indefinitely. It should not be necessary to pass this a custom value.
+    #
+    # @return [Boolean] true if the object is outdated, false otherwise
+    def outdated_due_to_dependencies?(obj, processed=Set.new)
+      # Convert from rep to item if necessary
+      obj = obj.item if obj.type == :item_rep
+
+      # Get from cache
+      if @objects_outdated_due_to_dependencies.has_key?(obj)
+        return @objects_outdated_due_to_dependencies[obj]
+      end
+
+      # Check processed
+      # Don’t return true; the false will be or’ed into a true if there
+      # really is a dependency that is causing outdatedness.
+      return false if processed.include?(obj)
+
+      # Calculate
+      is_outdated = dependency_tracker.objects_causing_outdatedness_of(obj).any? do |other|
+        other.nil? || basic_outdated?(other) || outdated_due_to_dependencies?(other, processed.merge([obj]))
+      end
+
+      # Cache
+      @objects_outdated_due_to_dependencies[obj] = is_outdated
+
+      # Done
+      is_outdated
+    end
+
+    # @param [Nanoc::ItemRep, Nanoc::Layout] obj The layout or item
+    #   representation to check the rule memory for
+    #
+    # @return [Boolean] true if the rule memory for the given item
+    #   represenation has changed, false otherwise
+    def rule_memory_differs_for(obj)
+      rules_collection.rule_memory_differs_for(obj)
+    end
+    memoize :rule_memory_differs_for
+
+    # @param obj
+    #
+    # @return [Boolean] false if either the new or the old checksum for the
+    #   given object is not available, true if both checksums are available
+    def checksums_available?(obj)
+      !!checksum_store[obj] && obj.checksum
+    end
+    memoize :checksums_available?
+
+    # @param obj
+    #
+    # @return [Boolean] false if the old and new checksums for the given
+    #   object differ, true if they are identical
+    def checksums_identical?(obj)
+      checksum_store[obj] == obj.checksum
+    end
+    memoize :checksums_identical?
+
+    # @param obj
+    #
+    # @return [Boolean] true if the old and new checksums for the given object
+    #   are available and identical, false otherwise
+    def object_modified?(obj)
+      !checksums_available?(obj) || !checksums_identical?(obj)
+    end
+    memoize :object_modified?
+
+    # @return [Nanoc::ChecksumStore] The checksum store
+    def checksum_store
+      @checksum_store
+    end
+
+    # @return [Nanoc::RulesCollection] The rules collection
+    def rules_collection
+      site.compiler.rules_collection
+    end
+
+    # @return [Nanoc::DependencyTracker] The dependency tracker
+    def dependency_tracker
+      @dependency_tracker
+    end
+
+    # @return [Nanoc::Site] The site
+    def site
+      @site
+    end
+
+  end
+
+end

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

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Module that contains all outdatedness reasons.
+  module OutdatednessReasons
+
+    # A generic outdatedness reason. An outdatedness reason is basically a
+    # descriptive message that explains why a given object is outdated.
+    class Generic
+
+      # @return [String] A descriptive message for this outdatedness reason
+      attr_reader :message
+
+      # @param [String] message The descriptive message for this outdatedness
+      #   reason
+      def initialize(message)
+        @message = message
+      end
+
+    end
+
+    CodeSnippetsModified = Generic.new(
+      'The code snippets have been modified since the last time the site was compiled.')
+
+    ConfigurationModified = Generic.new(
+      'The site configuration has been modified since the last time the site was compiled.')
+
+    DependenciesOutdated = Generic.new(
+      'This item uses content or attributes that have changed since the last time the site was compiled.')
+
+    NotEnoughData = Generic.new(
+      'Not enough data is present to correctly determine whether the item is outdated.')
+
+    NotWritten = Generic.new(
+      'This item representation has not yet been written to the output directory (but it does have a path).')
+
+    RulesModified = Generic.new(
+      'The rules file has been modified since the last time the site was compiled.')
+
+    SourceModified = Generic.new(
+      'The source file of this item has been modified since the last time the site was compiled.')
+
+  end
+
+end