nanoc3 3.1.0a2 → 3.1.0a3

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2009 Denis Defreyne and contributors
+Copyright (c) 2007-2010 Denis Defreyne and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/NEWS.md

@@ -2,8 +2,6 @@
 
 ## 3.1
 
-New:
-
 * An `Item#rep(name)` function for quickly getting a certain rep
 * An `Item#compiled_content` function for quickly getting compiled content
 * An `Item#path` function for quickly getting the path of an item rep
@@ -42,6 +40,18 @@ Deprecated:
 * The `last_fm`, `delicious` and `twitter` data sources; fetch online content
   into a cache by a rake task and load data from this cache instead
 
+## 3.0.9
+
+* Fixed 1.8.x parsing bug due to lack of parens which could cause “undefined
+  method `to_iso8601_time` for #<String:0x…>” errors
+
+## 3.0.8
+
+* `#atom_tag_for` now works with base_urls that contain a path [Eric Sunshine]
+* Generated root URLs in `#atom_feed` now end with a slash [Eric Sunshine]
+* Autocompiler now recognises requests to index files
+* `Blogging` helper now allows created_at to be a Time instance
+
 ## 3.0.7
 
 * Fixed a bug which could cause layout rules not be matched in order

data/README.md

@@ -5,6 +5,8 @@ It operates on local files, and therefore does not run on the server. nanoc
 “compiles” the local source files into HTML (usually), by evaluating eRuby,
 Markdown, etc.
 
+Note: This documentation looks best with Yardoc, not RDoc.
+
 ## Resources
 
 The [nanoc web site](http://nanoc.stoneship.org) contains a few useful

data/lib/nanoc3/base/code_snippet.rb

@@ -29,9 +29,13 @@ module Nanoc3
 
     # Creates a new code snippet.
     #
-    # @param [String] data     The raw source code which will be executed before compilation
+    # @param [String] data The raw source code which will be executed before
+    # compilation
+    #
     # @param [String] filename The filename corresponding to this code snippet
-    # @param [Time]   mtime    The time when the code was last modified (can be nil)
+    #
+    # @param [Time] mtime The time when the code was last modified (can be
+    # nil)
     def initialize(data, filename, mtime=nil)
       @data     = data
       @filename = filename

data/lib/nanoc3/base/compiler.rb

@@ -47,10 +47,10 @@ module Nanoc3
     # representations.
     #
     # @param [Nanoc3::Item] item The item that should be compiled, along with
-    #   its dependencies. Pass `nil` if the entire site should be compiled.
+    # its dependencies. Pass `nil` if the entire site should be compiled.
     #
     # @option params [Boolean] :force (false) true if the rep should be
-    #   compiled even if it is not outdated, false if not
+    # compiled even if it is not outdated, false if not
     #
     # @return [void]
     def run(item=nil, params={})
@@ -83,6 +83,9 @@ module Nanoc3
       compile_reps(reps)
       dependency_tracker.stop
 
+      # Cleanup
+      FileUtils.rm_rf(Nanoc3::Filter::TMP_BINARY_ITEMS_DIR)
+
       # Store dependencies
       dependency_tracker.store_graph
     end
@@ -93,7 +96,7 @@ module Nanoc3
     # @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
+    # 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
@@ -105,7 +108,7 @@ module Nanoc3
     # @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
+    # 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
@@ -117,7 +120,7 @@ module Nanoc3
     # @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.
+    # 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
@@ -228,7 +231,7 @@ module Nanoc3
     # 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
+    # the dependencies
     #
     # @return [void]
     def forget_dependencies_if_outdated(items)

data/lib/nanoc3/base/compiler_dsl.rb

@@ -33,22 +33,24 @@ module Nanoc3
     # rep as a block argument.
     #
     # @param [String] identifier A pattern matching identifiers of items that
-    #   should be compiled using this rule
+    # should be compiled using this rule
     #
     # @option params [Symbol] :rep (:default) The name of the representation
-    #   that should be compiled using this rule
+    # 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
+    # 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
@@ -75,22 +77,24 @@ module Nanoc3
     # and passing the rep as a block argument.
     #
     # @param [String] identifier A pattern matching identifiers of items that
-    #   should be routed using this rule
+    # should be routed using this rule
     #
     # @option params [Symbol] :rep (:default) The name of the representation
-    #   that should be routed using this rule
+    # 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
+    # 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
@@ -113,20 +117,22 @@ module Nanoc3
     # 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
+    # that should be filtered using this rule
     #
     # @param [Symbol] filter_name The name of the filter that should be run
-    #   when processing the layout
+    # 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})
+    # filter when processing the layout (see {Nanoc3::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={})
       @site.compiler.layout_filter_mapping[identifier_to_regex(identifier)] = [ filter_name, params ]

data/lib/nanoc3/base/data_source.rb

@@ -27,15 +27,15 @@ module Nanoc3
   class DataSource
 
     # @return [String] The root path where items returned by this data source
-    #   should be mounted.
+    # should be mounted.
     attr_reader :items_root
 
     # @return [String] The root path where layouts returned by this data
-    #   source should be mounted.
+    # source should be mounted.
     attr_reader :layouts_root
 
     # @return [Hash] The configuration for this data source. For example,
-    #   online data sources could contain authentication details.
+    # online data sources could contain authentication details.
     attr_reader :config
 
     extend Nanoc3::PluginRegistry::PluginMethods
@@ -45,12 +45,12 @@ module Nanoc3
     # @param [Nanoc3::Site] site The site this data source belongs to.
     #
     # @param [String] items_root The prefix that should be given to all items
-    #   returned by the #items method (comparable to mount points for
-    #   filesystems in Unix-ish OSes).
+    # returned by the #items method (comparable to mount points for
+    # filesystems in Unix-ish OSes).
     #
     # @param [String] layouts_root The prefix that should be given to all
-    #   layouts returned by the #layouts method (comparable to mount points
-    #   for filesystems in Unix-ish OSes).
+    # layouts returned by the #layouts method (comparable to mount points
+    # for filesystems in Unix-ish OSes).
     #
     # @param [Hash] config The configuration for this data source.
     def initialize(site, items_root, layouts_root, config)
@@ -93,7 +93,7 @@ module Nanoc3
     #
     # Calling this method decreases the internal reference count. When the
     # reference count reaches zero, i.e. when the data source is not used any
-    # more, the data soruce will be unloaded ({#down} will be called).
+    # more, the data source will be unloaded ({#down} will be called).
     #
     # @return [void]
     def unuse
@@ -189,9 +189,9 @@ module Nanoc3
     # @param [String] identifier
     #
     # @param [Hash] params Extra parameters to give to the data source. This
-    #   can be used to influence the way items are stored. For example,
-    #   filesystem data sources could use this to pass the extension of the
-    #   files that should be generated.
+    # can be used to influence the way items are stored. For example,
+    # filesystem data sources could use this to pass the extension of the
+    # files that should be generated.
     #
     # @return [void]
     def create_item(content, attributes, identifier, params={})
@@ -212,9 +212,9 @@ module Nanoc3
     # @param [String] identifier
     #
     # @param [Hash] params Extra parameters to give to the data source. This
-    #   can be used to influence the way items are stored. For example,
-    #   filesystem data sources could use this to pass the extension of the
-    #   files that should be generated.
+    # can be used to influence the way items are stored. For example,
+    # filesystem data sources could use this to pass the extension of the
+    # files that should be generated.
     #
     # @return [void]
     def create_layout(content, attributes, identifier, params={})

data/lib/nanoc3/base/dependency_tracker.rb

@@ -24,7 +24,7 @@ module Nanoc3
   class DependencyTracker
 
     # @return [String] The name of the file in which dependency information is
-    #   stored
+    # stored
     attr_accessor :filename
 
     # The version of the file format used to store dependencies.
@@ -33,7 +33,7 @@ module Nanoc3
     # Creates a new dependency tracker for the given items.
     #
     # @param [Array<Nanoc3::Item>] item The list of items whose dependencies
-    #   should be managed
+    # should be managed
     def initialize(items)
       @items          = items
       @filename       = 'tmp/dependencies'
@@ -89,7 +89,7 @@ module Nanoc3
     # direct dependencies of A do not include C).
     #
     # @param [Nanoc3::Item] item The item for which to fetch the direct
-    #   predecessors
+    # predecessors
     #
     # @return [Array<Nanoc3::Item>] The direct predecessors of the given item
     def direct_predecessors_of(item)
@@ -102,7 +102,7 @@ module Nanoc3
     # cause `item` to be marked as outdated.
     #
     # @param [Nanoc3::Item] item The item for which to fetch all direct and
-    #   indirect predecessors
+    # indirect predecessors
     #
     # @return [Array<Nanoc3::Item>] The predecessors of the given item
     def predecessors_of(item)
@@ -117,7 +117,7 @@ module Nanoc3
     # direct inverse dependencies of C do not include A).
     #
     # @param [Nanoc3::Item] item The item for which to fetch the direct
-    #   successors
+    # successors
     #
     # @return [Array<Nanoc3::Item>] The direct successors of the given item
     def direct_successors_of(item)
@@ -130,7 +130,7 @@ module Nanoc3
     # as outdated when `item` is outdated.
     #
     # @param [Nanoc3::Item] item The item for which to fetch all direct and
-    #   indirect successors
+    # indirect successors
     #
     # @return [Array<Nanoc3::Item>] The successors of the given item
     def successors_of(item)
@@ -141,11 +141,11 @@ module Nanoc3
     # `dst` is oudated, `src` will also become outdated.
     #
     # @param [Nanoc3::Item] src The source of the dependency, i.e. the item
-    #   that will become outdated if dst is outdated
+    # that will become outdated if dst is outdated
     #
     # @param [Nanoc3::Item] dst The destination of the dependency, i.e. the
-    #   item that will cause the source to become outdated if the destination
-    #    is outdated
+    # item that will cause the source to become outdated if the destination
+    # is outdated
     #
     # @return [void]
     def record_dependency(src, dst)

data/lib/nanoc3/base/directed_graph.rb

@@ -2,10 +2,10 @@
 
 module Nanoc3
 
-  # Nanoc3::DirectedGraph represents a directed graph. It is used by the
-  # dependency tracker for storing and querying dependencies between items.
-  # Internally, the graph will be stored as an adjacency matrix. For this,
-  # the {Nanoc3::DirectedGraph::SquareBooleanMatrix} class is used.
+  # Represents a directed graph. It is used by the dependency tracker for
+  # storing and querying dependencies between items. Internally, the graph
+  # will be stored as an adjacency matrix. For this, the
+  # {Nanoc3::DirectedGraph::SquareBooleanMatrix} class is used.
   #
   # @example Creating and using a directed graph
   #
@@ -33,15 +33,14 @@ module Nanoc3
   #     # => %w( b c )
   class DirectedGraph
 
-    # Nanoc3::DirectedGraph::SquareBooleanMatrix is, as the name says, a
-    # square matrix that contains boolean values. It is used as an adjacency
+    # A square matrix that contains boolean values. It is used as an adjacency
     # matrix by the {Nanoc3::DirectedGraph} class.
     class SquareBooleanMatrix
 
       # Creates a new matrix with the given number of rows/columns.
       #
       # @param [Number] size The number of elements along both sides of the
-      #   matrix (in other words, the square root of the number of elements)
+      # matrix (in other words, the square root of the number of elements)
       def initialize(size)
         @size = size
       end

data/lib/nanoc3/base/errors.rb

@@ -14,7 +14,7 @@ module Nanoc3
     class UnknownDataSource < Generic
 
       # @param [String] data_source_name The data source name for which no
-      #   data source could be found
+      # data source could be found
       def initialize(data_source_name)
         super("The data source specified in the site's configuration file, #{data_source_name}, does not exist.")
       end
@@ -26,7 +26,7 @@ module Nanoc3
     class UnknownLayout < Generic
 
       # @param [String] layout_identifier The layout identifier for which no
-      #   layout could be found
+      # layout could be found
       def initialize(layout_identifier)
         super("The site does not have a layout with identifier '#{layout_identifier}'.")
       end
@@ -38,7 +38,7 @@ module Nanoc3
     class UnknownFilter < Generic
 
       # @param [Symbol] filter_name The filter name for which no filter could
-      #   be found
+      # be found
       def initialize(filter_name)
         super("The requested filter, #{filter_name}, does not exist.")
       end
@@ -51,7 +51,7 @@ module Nanoc3
     class CannotDetermineFilter < Generic
 
       # @param [String] layout_identifier The identifier of the layout for
-      #   which the filter could not be determined
+      # which the filter could not be determined
       def initialize(layout_identifier)
         super("The filter to be used for the '#{layout_identifier}' could not be determined. Make sure the layout does have a filter.")
       end
@@ -63,12 +63,12 @@ module Nanoc3
     class DataNotYetAvailable < Generic
 
       # @param [String] type The name of the data type that is not yet
-      #   available. For example: `"site"`, `"items"`.
+      # available. For example: `"site"`, `"items"`.
       #
       # @param [Boolean] plural True if the given type is plural, false
-      #   otherwise. This only has an effect on the exception message. For
-      #   example, if the given type is `"site"`, plural would be `false`; if
-      #   the given type is `"items"`, plural would be `true`.
+      # otherwise. This only has an effect on the exception message. For
+      # example, if the given type is `"site"`, plural would be `false`; if
+      # the given type is `"items"`, plural would be `true`.
       def initialize(type, plural)
         super("#{type} #{plural ? 'are' : 'is'} not available yet. You may be missing a Nanoc3::Site#load_data call.")
       end
@@ -80,7 +80,7 @@ module Nanoc3
     class RecursiveCompilation < Generic
 
       # @param [Array<Nanoc3::ItemRep>] reps A list of item representations
-      #   that mutually depend on each other
+      # that mutually depend on each other
       def initialize(reps)
         super("The site cannot be compiled because the following items mutually depend on each other: #{reps.inspect}.")
       end
@@ -102,7 +102,7 @@ module Nanoc3
     class NoMatchingCompilationRuleFound < Generic
 
       # @param [Nanoc3::Item] item The item for which no compilation rule
-      #   could be found
+      # could be found
       def initialize(item)
         super("No compilation rules were found for the '#{item.identifier}' item.")
       end
@@ -114,7 +114,7 @@ module Nanoc3
     class NoMatchingRoutingRuleFound < Generic
 
       # @param [Nanoc3::Item] item The item for which no routing rule could be
-      #   found
+      # found
       def initialize(rep)
         super("No routing rules were found for the '#{rep.item.identifier}' item (rep '#{rep.name}').")
       end
@@ -126,11 +126,11 @@ module Nanoc3
     class UnmetDependency < Generic
 
       # @return [Nanoc3::ItemRep] The item representation that cannot yet be
-      #   compiled
+      # compiled
       attr_reader :rep
 
       # @param [Nanoc3::ItemRep] The item representation that cannot yet be
-      #   compiled
+      # compiled
       def initialize(rep)
         @rep = rep
         super("The '#{rep.item.identifier}' item (rep '#{rep.name}') cannot currently be compiled yet due to an unmet dependency.")
@@ -138,6 +138,41 @@ module Nanoc3
 
     end
 
+    # Error that is raised when a binary item is attempted to be laid out.
+    class CannotLayoutBinaryItem < Generic
+
+      # @param [Nanoc3::ItemRep] The item representation that was attempted to
+      # be laid out
+      def initialize(rep)
+        super("The '#{rep.item.identifier}' item (rep '#{rep.name}') cannot be laid out because it is a binary item.")
+      end
+
+    end
+
+    class CannotUseTextualFilter < Generic
+
+      # @param [Nanoc3::ItemRep] rep The item representation that was
+      # attempted to be filtered
+      #
+      # @param [Class] filter_class The filter class that was used
+      def initialize(rep, filter_class)
+        super("The “#{filter_class.inspect}” filter cannot be used to filter the “#{rep.item.identifier}” item (rep “#{rep.name}”), because textual filters cannot be used on binary items.")
+      end
+
+    end
+
+    class CannotUseBinaryFilter < Generic
+
+      # @param [Nanoc3::ItemRep] rep The item representation that was
+      # attempted to be filtered
+      #
+      # @param [Class] filter_class The filter class that was used
+      def initialize(rep, filter_class)
+        super("The “#{filter_class.inspect}” filter cannot be used to filter the “#{rep.item.identifier}” item (rep “#{rep.name}”), because binary filters cannot be used on textual items.")
+      end
+
+    end
+
   end
 
 end

data/lib/nanoc3/base/filter.rb

@@ -5,6 +5,9 @@ module Nanoc3
   # Nanoc3::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
@@ -12,19 +15,22 @@ module Nanoc3
   #
   # @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'
+  #   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.
     #
@@ -33,29 +39,69 @@ module Nanoc3
 
     extend Nanoc3::PluginRegistry::PluginMethods
 
+    class << self
+
+      # Sets the new type for the filter (`:binary` or `:text`).
+      #
+      # @param [Symbol] arg The new type of this filter
+      #
+      # @return [void]
+      def type(arg)
+        @type = arg
+      end
+
+      # @return [Boolean] True if this is a binary filter, false otherwise
+      def binary?
+        (@type || :text) == :binary
+      end
+
+    end
+
     # Creates a new filter that has access to the given assigns.
     #
-    # @param [Hash] a_assigns A hash containing variables that should be made
-    #   available during filtering.
+    # @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.
+    # Runs the filter on the given content or filename.
     #
     # @abstract
     #
-    # @param [String] content The unprocessed content that should be filtered.
+    # @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 fitlered (if the item is a binar item)
     #
     # @param [Hash] params A hash containing parameters. Filter subclasses can
-    #   use these parameters to allow modifying the filter's behaviour.
+    # use these parameters to allow modifying the filter's behaviour.
     #
-    # @return [String] The filtered content
-    def run(content, params={})
+    # @return [String] The filtered content (if the item is a textual item) or
+    # a path to a newly generated file containing the filtered content (if the
+    # item is a binary item)
+    def run(content_or_filename, params={})
       raise NotImplementedError.new("Nanoc3::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.
+    #
+    # @return [String] The output filename
+    def output_filename
+      @output_filename ||= begin
+        require 'tempfile'
+
+        FileUtils.mkdir_p(TMP_BINARY_ITEMS_DIR)
+        tempfile = Tempfile.new(filename.gsub(/[^a-z]/, '-'), TMP_BINARY_ITEMS_DIR)
+        new_filename = tempfile.path
+        tempfile.close!
+
+        new_filename
+      end
+    end
+
     # Returns the filename associated with the item that is being filtered.
     # It is in the format `item <identifier> (rep <name>)`.
     #