nanoc3 3.2.0a2 → 3.2.0a3

data/NEWS.md

@@ -5,6 +5,30 @@
 * Sped up nanoc quite a bit
 * Added AsciiDoc filter
 * Added progress indicator for long-running filters
+* Made all source data, such as item attributes, frozen during compilation
+* Exposed RedCloth parameters in the filter [Vincent Driessen]
+* Added --color option to force color on
+* Cleaned up internals, deprecating several parts and/or marking them as
+  private in the progress
+
+## 3.1.5 (???)
+
+* Improved `#render` documentation
+* Improved metadata section check so that e.g. raw diffs are handled properly
+* Deprecated using `Nanoc3::Site#initialize` with a non-`"."` argument
+* Added Ruby engine to version string
+* Allowed the `created_at` and `updated_at` attributes used in  the`Blogging`
+  helper to be `Date` instances
+
+## 3.1.4 (2010-07-25)
+
+* Made INT and TERM signals always quit the CLI
+* Allowed relative imports in LESS
+* Made sure modification times are unchanged for identical recompiled items
+* Improved link validator error handling
+* Made pygmentize not output extra divs and pres
+* Allowed colorizers to be specified using symbols instead of strings
+* Added scss to the default list of text extensions
 
 ## 3.1.3 (2010-04-25)
 

data/README.md

@@ -74,9 +74,11 @@ may be interested in the development dependencies:
 * Dmitry Bilunov
 * Devon Luke Buchanan
 * Brian Candler
+* Vincent Driessen
 * Chris Eppstein
 * Felix Hanley
 * Starr Horne
+* Tuomas Kareinen
 * Ale Muñoz
 * Nicky Peeters
 * Christian Plessl

data/lib/nanoc3.rb

@@ -3,7 +3,7 @@
 module Nanoc3
 
   # The current nanoc version.
-  VERSION = '3.2.0a2'
+  VERSION = '3.2.0a3'
 
 end
 

data/lib/nanoc3/base/compilation/checksum_store.rb

@@ -82,7 +82,7 @@ module Nanoc3
     #
     # @return [void]
     def calculate_all_checksums
-      @site.objects.each { |obj| new_checksum_for(obj) }
+      @site.compiler.objects.each { |obj| new_checksum_for(obj) }
     end
 
     # @param [#reference] obj

data/lib/nanoc3/base/compilation/compiler.rb

@@ -40,6 +40,8 @@ module Nanoc3
   #   the specified object.
   class Compiler
 
+    # @group Accessors
+
     # @return [Nanoc3::Site] The site this compiler belongs to
     attr_reader :site
 
@@ -68,6 +70,8 @@ module Nanoc3
     #   loaded but before the site is compiled
     attr_accessor :preprocessor
 
+    # @group Public instance methods
+
     # Creates a new compiler fo the given site
     #
     # @param [Nanoc3::Site] site The site this compiler belongs to
@@ -96,6 +100,7 @@ module Nanoc3
 
       # Compile reps
       load
+      @site.freeze
       dependency_tracker.start
       compile_reps(reps)
       dependency_tracker.stop
@@ -105,6 +110,8 @@ module Nanoc3
       FileUtils.rm_rf(Nanoc3::Filter::TMP_BINARY_ITEMS_DIR)
     end
 
+    # @group Private instance methods
+
     # Load the helper data that is used for compiling the site.
     #
     # @api private
@@ -114,7 +121,8 @@ module Nanoc3
       return if @loaded
       @loaded = true
 
-      stores.each { |s| s.load }
+      # Load site if necessary
+      @site.load
 
       # Preprocess
       load_rules
@@ -123,6 +131,9 @@ module Nanoc3
       build_reps
       route_reps
 
+      # Load auxiliary stores
+      stores.each { |s| s.load }
+
       # Determine which reps need to be recompiled
       dependency_tracker.propagate_outdatedness
       forget_dependencies_if_outdated(items)
@@ -260,7 +271,17 @@ module Nanoc3
       preprocessor_context.instance_eval(&preprocessor) if preprocessor
     end
 
-    # FIXME get rid of this
+    # Returns all objects managed by the site (items, layouts, code snippets,
+    # site configuration and the rules).
+    #
+    # @api private
+    def objects
+      # FIXME remove reference to rules
+      site.items + site.layouts + site.code_snippets + [ site.config, self.rules_with_reference ]
+    end
+
+    # Returns the rules along with an unique reference (`:rules`) so that the
+    # outdatedness checker can use them.
     #
     # @api private
     def rules_with_reference
@@ -306,6 +327,9 @@ module Nanoc3
           # Get basic path by applying matching rule
           basic_path = rule.apply_to(rep, :compiler => self)
           next if basic_path.nil?
+          if basic_path !~ %r{^/}
+            raise RuntimeError, "The path returned for the #{rep.inspect} item representation, “#{basic_path}”, does not start with a slash. Please ensure that all routing rules return a path that starts with a slash.".make_compatible_with_env
+          end
 
           # Get raw path by prepending output directory
           rep.raw_paths[snapshot] = @site.config[:output_dir] + basic_path
@@ -328,9 +352,11 @@ module Nanoc3
     #
     # @return [Hash] The assigns that should be used in the next filter/layout
     #   operation
+    #
+    # @api private
     def assigns_for(rep)
       if rep.binary?
-        content_or_filename_assigns = { :filename => rep.filenames[:last] }
+        content_or_filename_assigns = { :filename => rep.temporary_filenames[:last] }
       else
         content_or_filename_assigns = { :content => rep.content[:last] }
       end

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

@@ -218,7 +218,8 @@ module Nanoc3
       # Load edges
       new_data[:edges].each do |edge|
         from_index, to_index = *edge
-        from, to = @previous_objects[from_index], @previous_objects[to_index]
+        from = from_index && @previous_objects[from_index]
+        to   = to_index   && @previous_objects[to_index]
         @graph.add_edge(from, to)
       end
     end

data/lib/nanoc3/base/directed_graph.rb

@@ -67,6 +67,9 @@ module Nanoc3
     #
     # @return [void]
     def add_edge(from, to)
+      add_vertex(from)
+      add_vertex(to)
+
       @from_graph[from] ||= Set.new
       @from_graph[from] << to
 
@@ -107,6 +110,8 @@ module Nanoc3
       return if @vertices.include?(v)
 
       @vertices << v
+      @vertice_indexes[v] = @vertices.size-1
+
       @roots    << v
     end
 

data/lib/nanoc3/base/source_data/code_snippet.rb

@@ -22,20 +22,11 @@ module Nanoc3
     #
     # @param [String] filename The filename corresponding to this code snippet
     #
-    # @param [Time, Hash] params Extra parameters. For backwards
-    #   compatibility, this can be a Time instance indicating the time when
-    #   this code snippet was last modified (mtime).
-    #
-    # @option params [Time, nil] :mtime (nil) The time when this code snippet
-    #   was last modified
+    # @param [Time, Hash] params Extra parameters. Ignored by nanoc; it is
+    #   only included for backwards compatibility.
     def initialize(data, filename, params=nil)
-      # Parse params
-      params ||= {}
-      params = { :mtime => params } if params.is_a?(Time)
-
       @data     = data
       @filename = filename
-      @mtime    = params[:mtime]
     end
 
     # Loads the code by executing it.

data/lib/nanoc3/base/source_data/item.rb

@@ -23,9 +23,6 @@ module Nanoc3
     # @return [String] This item's identifier
     attr_accessor :identifier
 
-    # @return [Time] The time where this item was last modified
-    attr_reader   :mtime
-
     # @return [Array<Nanoc3::ItemRep>] This item’s list of item reps
     attr_reader   :reps
 
@@ -60,7 +57,8 @@ module Nanoc3
     #   this item was last modified (mtime).
     #
     # @option params [Time, nil] :mtime (nil) The time when this item was last
-    #   modified
+    #   modified. Deprecated; pass the modification time as the `:mtime`
+    #   attribute instead.
     #
     # @option params [Symbol, nil] :binary (true) Whether or not this item is
     #   binary
@@ -70,9 +68,6 @@ module Nanoc3
       params = { :mtime => params } if params.is_a?(Time)
       params[:binary] = false unless params.has_key?(:binary)
 
-      # Get mtime
-      @mtime = params[:mtime]
-
       # Get type and raw content or raw filename
       @is_binary = params[:binary]
       if @is_binary
@@ -85,6 +80,9 @@ module Nanoc3
       @attributes   = attributes.symbolize_keys
       @identifier   = identifier.cleaned_identifier
 
+      # Set mtime
+      @attributes.merge(:mtime => params[:mtime]) if params[:mtime]
+
       @parent       = nil
       @children     = []
 
@@ -163,6 +161,19 @@ module Nanoc3
       Nanoc3::NotificationCenter.post(:visit_started, self)
       Nanoc3::NotificationCenter.post(:visit_ended,   self)
 
+      # Get captured content (hax)
+      # TODO [in nanoc 4.0] remove me
+      if key.to_s =~ /^content_for_(.*)$/
+        # Include capturing helper if necessary
+        unless @_Nanoc3_Helpers_Capturing_included
+          self.class.send(:include, ::Nanoc3::Helpers::Capturing)
+          @_Nanoc3_Helpers_Capturing_included = true
+        end
+
+        # Get content
+        return content_for(self, $1.to_sym)
+      end
+
       @attributes[key]
     end
 
@@ -199,10 +210,21 @@ module Nanoc3
       [ type, self.identifier ]
     end
 
+    # Prevents all further modifications to itself, its items, its layouts etc.
+    #
+    # @return [void]
+    def freeze
+      attributes.freeze
+    end
     def inspect
       "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier} binary?=#{self.binary?}>"
     end
 
+    # @deprecated Access the modification time using `item[:mtime]` instead.
+    def mtime
+      self[:mtime]
+    end
+
   end
 
 end

data/lib/nanoc3/base/source_data/layout.rb

@@ -16,9 +16,6 @@ module Nanoc3
     #   slash
     attr_accessor :identifier
 
-    # @return [Time] The time where this layout was last modified
-    attr_reader   :mtime
-
     # Creates a new layout.
     #
     # @param [String] raw_content The raw content of this layout.
@@ -32,18 +29,17 @@ module Nanoc3
     #   this layout was last modified (mtime).
     #
     # @option params [Time, nil] :mtime (nil) The time when this layout was
-    #   last modified
+    #   last modified. Deprecated; pass the modification time as the `:mtime`
+    #   attribute instead.
     def initialize(raw_content, attributes, identifier, params=nil)
-      # Parse params
-      params ||= {}
-      params = { :mtime => params } if params.is_a?(Time)
-
-      # Get mtime
-      @mtime        = params[:mtime]
-
       @raw_content  = raw_content
       @attributes   = attributes.symbolize_keys
       @identifier   = identifier.cleaned_identifier
+
+      # Set mtime
+      params ||= {}
+      params = { :mtime => params } if params.is_a?(Time)
+      @attributes.merge(:mtime => params[:mtime]) if params[:mtime]
     end
 
     # Requests the attribute with the given key.
@@ -78,6 +74,11 @@ module Nanoc3
       "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier}>"
     end
 
+    # @deprecated Access the modification time using `layout[:mtime]` instead.
+    def mtime
+      self[:mtime]
+    end
+
   end
 
 end

data/lib/nanoc3/base/source_data/site.rb

@@ -208,12 +208,16 @@ module Nanoc3
       end
     end
 
-    # TODO document
+    # Prevents all further modifications to itself, its items, its layouts etc.
     #
-    # @api private
-    def objects
-      # FIXME remove reference to rules
-      items + layouts + code_snippets + [ config, compiler.rules_with_reference ]
+    # @return [void]
+    def freeze
+      super
+
+      config.freeze
+      items.each         { |i|  i.freeze  }
+      layouts.each       { |l|  l.freeze  }
+      code_snippets.each { |cs| cs.freeze }
     end
 
     # @deprecated It is no longer necessary to explicitly load site data. It
@@ -222,10 +226,12 @@ module Nanoc3
       warn 'It is no longer necessary to call Nanoc3::Site#load_data. This method no longer has any effect. All calls to this method can be safely removed.'
     end
 
-  private
-
     # Loads the site data. It is not necessary to call this method explicitly;
     # it will be called when it is necessary.
+    #
+    # @api private
+    #
+    # @return [void]
     def load
       return if @data_loaded
       @data_loaded = true
@@ -243,6 +249,8 @@ module Nanoc3
       compiler.load
     end
 
+  private
+
     # Loads this site’s code and executes it.
     def load_code_snippets
       @code_snippets_loaded ||= false
@@ -296,6 +304,11 @@ module Nanoc3
     # {#initialize} for details.
     def build_config(dir_or_config_hash)
       if dir_or_config_hash.is_a? String
+        # Check whether it is supported
+        if dir_or_config_hash != '.'
+          warn 'WARNING: Calling Nanoc3::Site.new with a directory that is not the current working directory is not supported. It is recommended to change the directory before calling Nanoc3::Site.new. For example, instead of Nanoc3::Site.new(\'abc\'), use Dir.chdir(\'abc\') { Nanoc3::Site.new(\'.\') }.'
+        end
+
         # Read config from config.yaml in given dir
         config_path = File.join(dir_or_config_hash, 'config.yaml')
         @config = DEFAULT_CONFIG.merge(YAML.load_file(config_path).symbolize_keys)

data/lib/nanoc3/cli/base.rb

@@ -55,6 +55,11 @@ module Nanoc3::CLI
       add_command(Nanoc3::CLI::Commands::Watch.new)
     end
 
+    # Returns a fully initialised base instance. It is recommended to use this
+    # shared instance than to create new ones, as this will be the instance
+    # that will be used when reading all code from the `lib/` directory.
+    #
+    # @return [Nanoc3::CLI::Base]
     def self.shared_base
       @shared_base ||= Nanoc3::CLI::Base.new
     end
@@ -64,8 +69,11 @@ module Nanoc3::CLI
       @debug
     end
 
-    # Helper function which can be called when a command is executed that
-    # requires a site, such as the compile command.
+    # Asserts that the current working directory contains a site
+    # ({Nanoc3::Site} instance). If no site is present, prints an error
+    # message and exits.
+    #
+    # @return [void]
     def require_site
       if site.nil?
         $stderr.puts 'The current working directory does not seem to be a ' +
@@ -74,7 +82,10 @@ module Nanoc3::CLI
       end
     end
 
-    # Gets the site (Nanoc3::Site) in the current directory and loads its data.
+    # Gets the site ({Nanoc3::Site} instance) in the current directory and
+    # loads its data.
+    #
+    # @return [Nanoc3::Site] The site in the current working directory
     def site
       # Load site if possible
       if File.file?('config.yaml') && (!self.instance_variable_defined?(:@site) || @site.nil?)
@@ -89,8 +100,16 @@ module Nanoc3::CLI
       @site
     end
 
-    # Inherited from ::Cri::Base
+    # @see ::Cri::Base#run
     def run(args)
+      # Set exit handler
+      [ 'INT', 'TERM' ].each do |signal|
+        Signal.trap(signal) do
+          puts
+          exit!(0)
+        end
+      end
+
       super(args)
     rescue Interrupt => e
       exit(1)
@@ -99,8 +118,12 @@ module Nanoc3::CLI
       exit(1)
     end
 
-    # Prints the given error to stderr. Includes message, possible resolution,
-    # compilation stack, backtrace, etc.
+    # Prints the given error to stderr. Includes message, possible resolution
+    # (see {#resolution_for}), compilation stack, backtrace, etc.
+    #
+    # @param [Error] error The error that should be described
+    #
+    # @return [void]
     def print_error(error)
       $stderr.puts
 
@@ -144,8 +167,12 @@ module Nanoc3::CLI
       $stderr.puts error.backtrace.to_enum(:each_with_index).map { |item, index| "  #{index}. #{item}" }.join("\n")
     end
 
-    # Returns a string containing hints for resolving the given error, or nil
-    # if no resolution can be automatically obtained.
+    # Attempts to find a resolution for the given error, or nil if no
+    # resolution can be automatically obtained.
+    #
+    # @param [Error] error The error to find a resolution for
+    #
+    # @return [String] The resolution for the given error
     def resolution_for(error)
       case error
       when LoadError
@@ -157,12 +184,22 @@ module Nanoc3::CLI
         if gem_name
           "Try installing the '#{gem_name}' gem (`gem install #{gem_name}`) and then re-running the command."
         end
+      when RuntimeError
+        if error.message =~ /^can't modify frozen/
+          "You attempted to modify immutable data. Some data, such as " \
+          "item/layout attributes and raw item/layout content, can no " \
+          "longer be modified once compilation has started."
+        end
       end
     end
 
     # Sets the data source's VCS to the VCS with the given name. Does nothing
     # when the site's data source does not support VCSes (i.e. does not
     # implement #vcs=).
+    #
+    # @param [String] vcs_name The name of the VCS that should be used
+    #
+    # @return [void]
     def set_vcs(vcs_name)
       # Skip if not possible
       return if vcs_name.nil? || site.nil?
@@ -183,13 +220,17 @@ module Nanoc3::CLI
       end
     end
 
-    # Returns the list of global option definitionss.
+    # @return [Array] The list of global option definitions
     def global_option_definitions
       [
         {
           :long => 'help', :short => 'h', :argument => :forbidden,
           :desc => 'show this help message and quit'
         },
+        {
+          :long => 'color', :short => 'l', :argument => :forbidden,
+          :desc => 'enable color'
+        },
         {
           :long => 'no-color', :short => 'C', :argument => :forbidden,
           :desc => 'disable color'
@@ -213,13 +254,15 @@ module Nanoc3::CLI
       ]
     end
 
+    # @see Cri::Base#handle_option
     def handle_option(option)
       case option
       when :version
         gem_info = defined?(Gem) ? "with RubyGems #{Gem::VERSION}" : "without RubyGems"
+        engine   = defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
 
         puts "nanoc #{Nanoc3::VERSION} (c) 2007-2010 Denis Defreyne."
-        puts "Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) running on #{RUBY_PLATFORM} #{gem_info}"
+        puts "Running #{engine} #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) on #{RUBY_PLATFORM} #{gem_info}"
         exit 0
       when :verbose
         Nanoc3::CLI::Logger.instance.level = :low
@@ -227,6 +270,8 @@ module Nanoc3::CLI
         @debug = true
       when :warn
         $-w = true
+      when :color
+        Nanoc3::CLI::Logger.instance.color = true
       when :'no-color'
         Nanoc3::CLI::Logger.instance.color = false
       when :help

data/lib/nanoc3/cli/commands/debug.rb

@@ -53,7 +53,7 @@ module Nanoc3::CLI::Commands
         puts "item #{item.identifier} depends on:"
         predecessors = dependency_tracker.direct_predecessors_of(item).sort_by { |i| i.identifier }
         predecessors.each do |pred|
-          puts "  #{pred.identifier}"
+          puts "  [ #{format '%6s', pred.type} ] #{pred.identifier}"
         end
         puts "  (nothing)" if predecessors.empty?
         puts

data/lib/nanoc3/cli/commands/watch.rb

@@ -31,11 +31,7 @@ module Nanoc3::CLI::Commands
 
     def run(options, arguments)
       require 'fssm'
-
-      Signal.trap("INT") do
-        puts
-        exit
-      end
+      require 'pathname'
 
       @notifier = Notifier.new
 
@@ -119,7 +115,7 @@ module Nanoc3::CLI::Commands
       # @param [String] message The message to include in the notification
       def notify(message)
         return if tool.nil?
-        send(tool.tr('-', '_'), message, params)
+        send(tool.tr('-', '_'), message)
       end
 
     private
@@ -128,11 +124,11 @@ module Nanoc3::CLI::Commands
         @tool ||= TOOLS.find { |t| !`which #{t}`.empty? }
       end
 
-      def growlnotify(message, params={})
+      def growlnotify(message)
         system('growlnotify', '-m', message)
       end
 
-      def notify_send(message, params={})
+      def notify_send(message)
         system('notify-send', message)
       end
 

data/lib/nanoc3/cli/logger.rb

@@ -8,6 +8,8 @@ module Nanoc3::CLI
   # feedback in the terminal.
   class Logger
 
+    # Maps actions (`:create`, `:update`, `:identical` and `:skip`) onto their
+    # ANSI color codes.
     ACTION_COLORS = {
       :create         => "\e[1m" + "\e[32m", # bold + green
       :update         => "\e[1m" + "\e[33m", # bold + yellow
@@ -17,35 +19,43 @@ module Nanoc3::CLI
 
     include Singleton
 
-    # The log level, which can be :high, :low or :off (which will log all
-    # messages, only high-priority messages, or no messages at all,
+    # Returns the log level, which can be :high, :low or :off (which will log
+    # all messages, only high-priority messages, or no messages at all,
     # respectively).
+    #
+    # @return [Symbol] The log level
     attr_accessor :level
 
-    # Whether to use color in log messages or not
-    attr_accessor :color
-    alias_method :color?, :color
+    # @return [Boolean] True if color should be used, false otherwise
+    attr_writer :color
 
     def initialize
       @level = :high
-      @color = $stdout.tty?
+    end
 
-      # Try enabling color support on Windows
-      begin
-        require 'Win32/Console/ANSI' if RUBY_PLATFORM =~/mswin|mingw/
-      rescue LoadError
-        @color = false
+    # @return [Boolean] true if colors are enabled, false otherwise
+    def color?
+      if @color.nil?
+        @color = true
+        begin
+          require 'Win32/Console/ANSI' if RUBY_PLATFORM =~ /mswin|mingw/
+        rescue LoadError
+          @color = false
+        end
       end
+
+      @color
     end
 
     # Logs a file-related action.
     #
-    # +level+:: The importance of this action. Can be :high or :low.
+    # @param [:high, :low] level The importance of this action
     #
-    # +action+:: The kind of file action. Can be :create, :update or
-    #            :identical.
+    # @param [:create, :update, :identical] action The kind of file action
     #
-    # +identifier+:: The identifier of the item the action was performed on.
+    # @param [String] name The name of the file the action was performed on
+    #
+    # @return [void]
     def file(level, action, identifier, duration=nil)
       log(
         level,
@@ -61,18 +71,19 @@ module Nanoc3::CLI
 
     # Logs a message.
     #
-    # +level+:: The importance of this message. Can be :high or :low.
+    # @param [:high, :low] level The importance of this message
+    #
+    # @param [String] message The message to be logged
     #
-    # +s+:: The message to be logged.
+    # @param [#puts] io The stream to which the message should be written
     #
-    # +io+:: The IO instance to which the message will be written. Defaults to
-    #        standard output.
-    def log(level, s, io=$stdout)
+    # @return [void]
+    def log(level, message, io=$stdout)
       # Don't log when logging is disabled
       return if @level == :off
 
       # Log when level permits it
-      io.puts(s) if (@level == :low or @level == level)
+      io.puts(message) if (@level == :low or @level == level)
     end
 
   end

data/lib/nanoc3/data_sources/filesystem.rb

@@ -238,7 +238,7 @@ module Nanoc3::DataSources
       data = File.read(content_filename)
 
       # Check presence of metadata section
-      if data[0, 3] != '-'*3 && data[0, 5] != '-'*5
+      if data !~ /\A-{3,5}\s*$/
         return [ {}, data ]
       end
 

data/lib/nanoc3/filters/colorize_syntax.rb

@@ -107,8 +107,23 @@ module Nanoc3::Filters
       code
     end
 
+    # Runs the content through [pygmentize](http://pygments.org/docs/cmdline/),
+    # the commandline frontend for [Pygments](http://pygments.org/).
+    #
+    # @api private
+    #
+    # @param [String] code The code to colorize
+    #
+    # @param [String] language The language the code is written in
+    #
+    # @option params [String, Symbol] :encoding The encoding of the code block
+    #
+    # @return [String] The colorized output
     def pygmentize(code, language, params={})
-      IO.popen("pygmentize -l #{language} -f html", "r+") do |io|
+      enc = ""
+      enc = "-O encoding=" + params[:encoding] if params[:encoding]
+
+      IO.popen("pygmentize -l #{language} -f html #{enc}", "r+") do |io|
         io.write(code)
         io.close_write
         highlighted_code = io.read

data/lib/nanoc3/filters/redcloth.rb

@@ -3,8 +3,22 @@
 module Nanoc3::Filters
   class RedCloth < Nanoc3::Filter
 
-    # Runs the content through [RedCloth](http://redcloth.org/).
-    # This method takes no options.
+    # Runs the content through [RedCloth](http://redcloth.org/). This method
+    # takes the following options:
+    #
+    # * `:filter_class`
+    # * `:filter_html`
+    # * `:filter_ids`
+    # * `:filter_style`
+    # * `:hard_breaks`
+    # * `:lite_mode`
+    # * `:no_span_caps`
+    # * `:sanitize_htm`
+    #
+    # Each of these options sets the corresponding attribute on the `RedCloth`
+    # instance. For example, when the `:hard_breaks => false` option is passed
+    # to this filter, the filter will call `r.hard_breaks = false` (with `r`
+    # being the `RedCloth` instance).
     #
     # @param [String] content The content to filter
     #
@@ -12,8 +26,21 @@ module Nanoc3::Filters
     def run(content, params={})
       require 'redcloth'
 
+      # Create formatter
+      r = ::RedCloth.new(content)
+
+      # Set options
+      r.filter_classes = params[:filter_classes] if params.has_key?(:filter_classes)
+      r.filter_html    = params[:filter_html]    if params.has_key?(:filter_html)
+      r.filter_ids     = params[:filter_ids]     if params.has_key?(:filter_ids)
+      r.filter_styles  = params[:filter_styles]  if params.has_key?(:filter_styles)
+      r.hard_breaks    = params[:hard_breaks]    if params.has_key?(:hard_breaks)
+      r.lite_mode      = params[:lite_mode]      if params.has_key?(:lite_mode)
+      r.no_span_caps   = params[:no_span_caps]   if params.has_key?(:no_span_caps)
+      r.sanitize_html  = params[:sanitize_html]  if params.has_key?(:sanitize_html)
+
       # Get result
-      ::RedCloth.new(content).to_html
+      r.to_html
     end
 
   end

data/lib/nanoc3/helpers/blogging.rb

@@ -39,8 +39,7 @@ module Nanoc3::Helpers
     def sorted_articles
       require 'time'
       articles.sort_by do |a|
-        time = a[:created_at]
-        time.is_a?(String) ? Time.parse(time) : time
+        attribute_to_time(a[:created_at])
       end.reverse
     end
 
@@ -183,8 +182,7 @@ module Nanoc3::Helpers
 
       # Get sorted relevant articles
       sorted_relevant_articles = relevant_articles.sort_by do |a|
-        time = a[:created_at]
-        time.is_a?(String) ? Time.parse(time) : time
+        attribute_to_time(a[:created_at])
       end.reverse.first(limit)
 
       # Get most recent article
@@ -204,8 +202,7 @@ module Nanoc3::Helpers
         xml.title   title
 
         # Add date
-        time = last_article[:created_at]
-        xml.updated((time.is_a?(String) ? Time.parse(time) : time).to_iso8601_time)
+        xml.updated(attribute_to_time(last_article[:created_at]).to_iso8601_time)
 
         # Add links
         xml.link(:rel => 'alternate', :href => root_url)
@@ -229,10 +226,8 @@ module Nanoc3::Helpers
             xml.title     a[:title], :type => 'html'
 
             # Add dates
-            create_time = a[:created_at]
-            update_time = a[:updated_at] || a[:created_at]
-            xml.published((create_time.is_a?(String) ? Time.parse(create_time) : create_time).to_iso8601_time)
-            xml.updated(  (update_time.is_a?(String) ? Time.parse(update_time) : update_time).to_iso8601_time)
+            xml.published attribute_to_time(a[:created_at]).to_iso8601_time
+            xml.updated   attribute_to_time(a[:updated_at] || a[:created_at]).to_iso8601_time
         
             # Add specific author information
             if a[:author_name] || a[:author_uri]
@@ -305,12 +300,24 @@ module Nanoc3::Helpers
 
       hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@site.config[:base_url])[1..2]
 
-      time = item[:created_at]
-      formatted_date = (time.is_a?(String) ? Time.parse(time) : time).to_iso8601_date
+      formatted_date = attribute_to_time(item[:created_at]).to_iso8601_date
 
       'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier)
     end
 
+    # Converts the given attribute (which can be a string, a Time or a Date)
+    # into a Time.
+    #
+    # @param [String, Time, Date] time Something that contains time
+    #   information but is not necessarily a Time instance yet
+    #
+    # @return [Time] The Time instance corresponding to the given input
+    def attribute_to_time(time)
+      time = Time.local(time.year, time.month, time.day) if time.is_a?(Date)
+      time = Time.parse(time) if time.is_a?(String)
+      time
+    end
+
   end
 
 end

data/lib/nanoc3/helpers/capturing.rb

@@ -12,7 +12,10 @@ module Nanoc3::Helpers
   # you write the summary on the item itself, but capture it, and print it in
   # the sidebar layout.
   #
-  # @example Capturing content into a `content_for_summary` attribute
+  # This helper has been tested with ERB and Haml. Other filters may not work
+  # correctly.
+  #
+  # @example Capturing content for a summary
   #
   #   <% content_for :summary do %>
   #     <p>On this item, nanoc is introduced, blah blah.</p>
@@ -22,28 +25,95 @@ module Nanoc3::Helpers
   #
   #   <div id="sidebar">
   #     <h3>Summary</h3>
+  #     <%= content_for(@item, :summary) || '(no summary)' %>
+  #   </div>
+  #
+  # @example Showing captured content in a sidebar the old, deprecated way (do not use or I will become very angry)
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
   #     <%= @item[:content_for_summary] || '(no summary)' %>
   #   </div>
   module Capturing
 
-    # Captures the content inside the block and stores it in an item
-    # attribute named `content_for_` followed by the given name. The
-    # content of the block itself will not be outputted.
+    # @api private
+    class CapturesStore
+
+      require 'singleton'
+      include Singleton
+
+      def initialize
+        @store = {}
+      end
+
+      def []=(item, name, content)
+        @store[item.identifier] ||= {}
+        @store[item.identifier][name] = content
+      end
+
+      def [](item, name)
+        @store[item.identifier] ||= {}
+        @store[item.identifier][name]
+      end
+
+    end
+
+    # @overload content_for(name, &block)
+    #
+    #   Captures the content inside the block and stores it so that it can be
+    #   referenced later on. The same method, {#content_for}, is used for
+    #   getting the captured content as well as setting it. When capturing,
+    #   the content of the block itself will not be outputted.
+    #
+    #   For backwards compatibility, it is also possible to fetch the captured
+    #   content by getting the contents of the attribute named `content_for_`
+    #   followed by the given name. This way of accessing captures is
+    #   deprecated.
+    #
+    #   @param [Symbol, String] name The base name of the attribute into which
+    #     the content should be stored
+    #
+    #   @return [void]
+    #
+    # @overload content_for(item, name)
     #
-    # @param [Symbol, String] The base name of the attribute into which the
-    #   content should be stored
+    #   Fetches the capture with the given name from the given item and
+    #   returns it.
     #
-    # @return [void]
-    def content_for(name, &block)
-      eval("@item[:content_for_#{name.to_s}] = capture(&block)")
+    #   @param [Nanoc3::Item] item The item for which to get the capture
+    #
+    #   @param [Symbol, String] name The name of the capture to fetch
+    #
+    #   @return [String] The stored captured content
+    def content_for(*args, &block)
+      if block_given? # Set content
+        # Get args
+        if args.size != 1
+          raise ArgumentError, "expected 1 argument (the name " + 
+            "of the capture) but got #{args.size} instead"
+        end
+        name = args[0]
+
+        # Capture and store
+        content = capture(&block)
+        CapturesStore.instance[@item, name.to_sym] = content
+      else # Get content
+        # Get args
+        if args.size != 2
+          raise ArgumentError, "expected 2 arguments (the item " +
+            "and the name of the capture) but got #{args.size} instead"
+        end
+        item = args[0]
+        name = args[1]
+
+        # Get content
+        CapturesStore.instance[item, name.to_sym]
+      end
     end
 
-    # Evaluates the given block and returns the result. The contents of the
+    # Evaluates the given block and returns its contents. The contents of the
     # block is not outputted.
     #
-    # This function has been tested with ERB and Haml. Other filters may not
-    # work correctly.
-    #
     # @return [String] The captured result
     def capture(&block)
       # Get erbout so far

data/lib/nanoc3/helpers/rendering.rb

@@ -7,7 +7,18 @@ module Nanoc3::Helpers
 
     include Nanoc3::Helpers::Capturing
 
-    # Returns a string containing the rendered given layout.
+    # Returns a string containing the rendered given layout. The given layout
+    # will first be run through the matching layout rule.
+    #
+    # The assigns (`@item`, `@config`, …) will not be available in the
+    # partial, but it is possible to pass custom assigns to the method. These
+    # assigns will be made available as instance variables inside the partial.
+    #
+    # The method can also take a block. In this case, the content of the block
+    # will be captured (using the {Nanoc3::Helpers::Capturing} helper) and
+    # this content will be made available with `yield`. In other words, a
+    # `yield` inside the partial will output the content of the block passed
+    # to the method.
     #
     # @param [String] identifier The identifier of the layout that should be
     #   rendered
@@ -29,6 +40,18 @@ module Nanoc3::Helpers
     #   <%= render 'head', :title => 'Foo' %>
     #   # => "<h1>Foo</h1>"
     #
+    # @example Yielding inside a partial
+    #
+    #   # The 'box' partial
+    #   <div class="box">
+    #     <%= yield %>
+    #   </div>
+    #
+    #   # The item/layout where the partial is rendered
+    #   <% render 'box' do %>
+    #     I'm boxy! Luvz!
+    #   <% end %>
+    #
     # @raise [Nanoc3::Errors::UnknownLayout] if the given layout does not
     #   exist
     #

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: nanoc3
 version: !ruby/object:Gem::Version 
-  hash: -142061300
+  hash: -794993270
   prerelease: true
   segments: 
   - 3
   - 2
-  - 0a2
-  version: 3.2.0a2
+  - 0a3
+  version: 3.2.0a3
 platform: ruby
 authors: 
 - Denis Defreyne
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-09 00:00:00 +02:00
+date: 2010-08-24 00:00:00 +02:00
 default_executable: nanoc3
 dependencies: 
 - !ruby/object:Gem::Dependency