nanoc3 3.0.9 → 3.1.0a1

data/lib/nanoc3/base/compiler.rb

@@ -2,27 +2,37 @@
 
 module Nanoc3
 
-  # Nanoc3::Compiler is responsible for compiling a site's item
-  # representations.
+  # Responsible for compiling a site’s item representations.
   class Compiler
 
     # The compilation stack. When the compiler begins compiling a rep or a
     # layout, it will be placed on the stack; when it is done compiling the
     # rep or layout, it will be removed from the stack.
+    #
+    # @return [Array] The compilation stack
     attr_reader :stack
 
     # The list of compilation rules that will be used to compile items. This
-    # array will be filled by Nanoc3::Site#load_data.
+    # array will be filled by {Nanoc3::Site#load_data}.
+    #
+    # @return [Array<Nanoc3::Rule>] The list of item compilation rules
     attr_reader :item_compilation_rules
 
     # The list of routing rules that will be used to give all items a path.
-    # This array will be filled by Nanoc3::Site#load_data.
+    # This array will be filled by {Nanoc3::Site#load_data}.
+    #
+    # @return [Array<Nanoc3::Rule>] The list of item routing rules
     attr_reader :item_routing_rules
 
-    # The hash containing layout-to-filter mapping 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
 
-    # Creates a new compiler for the given site.
+    # Creates a new compiler fo the given site
+    #
+    # @param [Nanoc3::Site] site The site this compiler belongs to
     def initialize(site)
       @site = site
 
@@ -36,25 +46,24 @@ module Nanoc3
     # Compiles (part of) the site and writes out the compiled item
     # representations.
     #
-    # +items+:: The items that should be compiled, along with their
-    #           dependencies. Pass +nil+ if the entire site should be
-    #           compiled.
+    # @param [Nanoc3::Item] item The item that should be compiled, along with
+    #   its dependencies. Pass `nil` if the entire site should be compiled.
     #
-    # This method also accepts a few optional parameters:
+    # @option params [Boolean] :force (false) true if the rep should be
+    #   compiled even if it is not outdated, false if not
     #
-    # +:force+:: true if the rep should be compiled even if it is not
-    #            outdated, false if not. Defaults to false.
+    # @return [void]
     def run(item=nil, params={})
       # Create output directory if necessary
       FileUtils.mkdir_p(@site.config[:output_dir])
 
       # Load dependencies
       dependency_tracker.load_graph
-      print_dependency_graph if $DEBUG
+      dependency_tracker.print_graph if $DEBUG
 
       # Get items and reps to compile
       if item
-        items = [ item ] + dependency_tracker.all_inverse_dependencies_for(item)
+        items = [ item ] + dependency_tracker.successors_of(item)
         items.uniq!
       else
         items = @site.items
@@ -62,7 +71,11 @@ module Nanoc3
       reps = items.map { |i| i.reps }.flatten
 
       # Prepare dependencies
-      mark_outdated_items(reps, params.has_key?(:force) && params[:force])
+      if params.has_key?(:force) && params[:force]
+        reps.each { |r| r.force_outdated = true }
+      else
+        dependency_tracker.mark_outdated_items
+      end
       forget_dependencies_if_outdated(items)
 
       # Compile reps
@@ -74,22 +87,37 @@ module Nanoc3
       dependency_tracker.store_graph
     end
 
-    # Returns the first matching compilation rule for the given rep.
+    # Finds the first matching compilation rule for the given item
+    # representation.
+    #
+    # @param [Nanoc3::ItemRep] rep The item rep for which to fetch the rule
+    #
+    # @return [Nanoc3::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
 
-    # Returns the first matching routing rule for the given rep.
+    # Finds the first matching routing rule for the given item representation.
+    #
+    # @param [Nanoc3::ItemRep] rep The item rep for which to fetch the rule
+    #
+    # @return [Nanoc3::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 a tuple containing the filter name and the filter arguments for
-    # the given layout.
+    # Finds the filter name and arguments to use for the given layout.
+    #
+    # @param [Nanoc3::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
@@ -99,9 +127,13 @@ module Nanoc3
 
   private
 
-    # Compiles all item representations in the site.
+    # Compiles the given representations.
+    #
+    # @param [Array] reps The item representations to compile.
+    #
+    # @return [void]
     def compile_reps(reps)
-      active_reps, skipped_reps = reps.partition { |rep| rep.outdated? || rep.item.dependencies_outdated? }
+      active_reps, skipped_reps = reps.partition { |rep| rep.outdated? || rep.item.outdated_due_to_dependencies? }
       inactive_reps = []
       compiled_reps = []
 
@@ -162,10 +194,12 @@ module Nanoc3
     # Compiles the given item representation.
     #
     # This method should not be called directly; please use
-    # Nanoc3::Compiler#run instead, and pass this item representation's item as
-    # its first argument.
+    # {Nanoc3::Compiler#run} instead, and pass this item representation's item
+    # as its first argument.
     #
-    # +rep+:: The rep that is to be compiled.
+    # @param [Nanoc3::ItemRep] rep The rep that is to be compiled
+    #
+    # @return [void]
     def compile_rep(rep)
       # Start
       Nanoc3::NotificationCenter.post(:compilation_started, rep)
@@ -183,43 +217,28 @@ module Nanoc3
       Nanoc3::NotificationCenter.post(:compilation_ended, rep)
     end
 
-    # Returns the dependency tracker for this site.
+    # Returns the dependency tracker for this site, creating it first if it
+    # does not yet exist.
+    # 
+    # @return [Nanoc3::DependencyTracker] The dependency tracker for this site
     def dependency_tracker
       @dependency_tracker ||= Nanoc3::DependencyTracker.new(@site.items)
     end
 
-    # Marks the necessary items as outdated.
-    def mark_outdated_items(reps, force)
-      if force
-        reps.each { |r| r.force_outdated = true }
-      else
-        dependency_tracker.mark_outdated_items
-      end
-    end
-
     # Clears the list of dependencies for items that will be recompiled.
+    #
+    # @param [Array<Nanoc3::Item>] items The list of items for which to forget
+    #   the dependencies
+    #
+    # @return [void]
     def forget_dependencies_if_outdated(items)
       items.each do |i|
-        if i.outdated? || i.dependencies_outdated?
+        if i.outdated? || i.outdated_due_to_dependencies?
           dependency_tracker.forget_dependencies_for(i)
         end
       end
     end
 
-    # Prints the dependency graph.
-    def print_dependency_graph
-      graph = dependency_tracker.instance_eval { @graph }
-      puts "DEPENDENCY GRAPH:"
-      graph.each_pair do |key, values|
-        puts "#{key.inspect} depends on:"
-        values.each do |value|
-          puts "    #{value.inspect}"
-        end
-        puts "    (nothing!)" if values.empty?
-        puts
-      end
-    end
-
   end
 
 end

data/lib/nanoc3/base/compiler_dsl.rb

@@ -2,17 +2,22 @@
 
 module Nanoc3
 
-  # Nanoc3::CompilerDSL contains methods that will be executed by the site's
-  # rules file.
+  # Contains methods that will be executed by the site’s `Rules` file.
   class CompilerDSL
 
     # Creates a new compiler DSL for the given compiler.
+    #
+    # @param [Nanoc3::Site] site The site this DSL belongs to
     def initialize(site)
       @site = site
     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)
       @site.preprocessor = block
     end
@@ -21,21 +26,32 @@ module Nanoc3
     # 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"
-    # unless an explicit :rep parameter is given.
+    # 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.
     #
-    # Example:
+    # @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
     #
-    #   compile '/foo/*' do
-    #     rep.filter :erb
-    #   end
-    #   
-    #   compile '/bar/*', :rep => 'raw' do
-    #     # do nothing
-    #   end
+    # @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?
@@ -49,24 +65,35 @@ module Nanoc3
     end
 
     # Creates a routing rule for all items whose identifier match the
-    # given identifier, which may either be a string containing 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 givign an explicit :rep parameter.
+    # 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.
     #
-    # Example:
+    # @param [String] identifier A pattern matching identifiers of items that
+    #   should be routed using this rule
     #
-    #   route '/foo/*' do
-    #     '/blahblah' + rep.item.identifier + 'index.html'
-    #   end
-    #   
-    #   route '/bar/*', :rep => 'raw' do
-    #     '/blahblah' + rep.item.identifier + 'index.txt'
-    #   end
+    # @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?
@@ -85,18 +112,32 @@ module Nanoc3
     # using the filter specified in the second argument. The params hash
     # contains filter arguments that will be passed to the filter.
     #
-    # Example:
+    # @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 {Nanoc3::Filter#run})
+    #
+    # @return [void]
+    #
+    # @example Specifying the filter to use for a layout
+    #     layout '/default/', :erb
     #
-    #   layout '/default/', :erb
-    #   layout '/custom/',  :haml, :format => :html5
+    # @example Using custom filter arguments for a layout
+    #     layout '/custom/',  :haml, :format => :html5
     def layout(identifier, filter_name, params={})
       @site.compiler.layout_filter_mapping[identifier_to_regex(identifier)] = [ filter_name, params ]
     end
 
   private
 
-    # Converts the given identifier, which can contain the '*' wildcard, to a regex.
-    # For example, 'foo/*/bar' is transformed into /^foo\/(.*?)\/bar$/.
+    # 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
@@ -104,7 +145,7 @@ module Nanoc3
         new_identifier[/^/] = '/' if identifier[0,1] != '/'
         new_identifier[/$/] = '/' unless [ '*', '/' ].include?(identifier[-1,1])
 
-        /^#{new_identifier.gsub('*', '(.*?)')}$/
+        /^#{new_identifier.gsub('*', '(.*?)').gsub('+', '(.+?)')}$/
       else
         identifier
       end

data/lib/nanoc3/base/context.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # 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 = Nanoc3::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/nanoc3/base/core_ext/array.rb

@@ -3,6 +3,8 @@
 module Nanoc3::ArrayExtensions
 
   # Returns a new array where all items' keys are recursively converted to symbols by calling #symbolize_keys.
+  #
+  # @return [Array] The converted array
   def symbolize_keys
     inject([]) do |array, element|
       array + [ element.respond_to?(:symbolize_keys) ? element.symbolize_keys : element ]
@@ -10,6 +12,8 @@ module Nanoc3::ArrayExtensions
   end
 
   # Returns a new array where all items' keys are recursively converted to strings by calling #stringify_keys.
+  #
+  # @return [Array] The converted array
   def stringify_keys
     inject([]) do |array, element|
       array + [ element.respond_to?(:stringify_keys) ? element.stringify_keys : element ]

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

@@ -2,7 +2,9 @@
 
 module Nanoc3::HashExtensions
 
-  # Returns a new hash where all keys are recursively converted into symbols.
+  # Returns a new hash where all keys are recursively converted to symbols.
+  #
+  # @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)
@@ -10,6 +12,8 @@ module Nanoc3::HashExtensions
   end
 
   # Returns a new hash where all keys are recursively converted to strings.
+  #
+  # @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)

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

@@ -3,6 +3,8 @@
 module Nanoc3::StringExtensions
 
   # Transforms string into an actual identifier
+  #
+  # @return [String] The identifier generated from the receiver
   def cleaned_identifier
     "/#{self}/".gsub(/^\/+|\/+$/, '/')
   end