nanoc 2.0.4 → 2.1

data/lib/nanoc/base/binary_filter.rb

@@ -0,0 +1,44 @@
+module Nanoc
+
+  # Nanoc::BinaryFilter is responsible for filtering binary assets. It is the
+  # (abstract) superclass for all binary filters. Subclasses should override
+  # the +run+ method.
+  class BinaryFilter < Plugin
+
+    # Creates a new binary filter for the given asset and site.
+    #
+    # +asset_rep+:: A proxy for the asset representation (Nanoc::AssetRep)
+    #               that should be compiled by this filter.
+    #
+    # +asset+:: A proxy for the asset (Nanoc::Asset) for which +asset_rep+ is
+    #           the representation.
+    #
+    # +site+:: The site (Nanoc::Site) this filter belongs to.
+    #
+    # +other_assigns+:: A hash containing other variables that should be made
+    #                   available during filtering.
+    def initialize(asset_rep, asset, site, other_assigns={})
+      @asset_rep      = asset_rep
+      @asset          = asset
+      @pages          = site.pages.map   { |p| p.to_proxy }
+      @assets         = site.assets.map  { |a| a.to_proxy }
+      @layouts        = site.layouts.map { |l| l.to_proxy }
+      @config         = site.config
+      @site           = site
+      @other_assigns  = other_assigns
+    end
+
+    # Runs the filter. This method returns a File instance pointing to a new
+    # file, containing the filtered content.
+    #
+    # +file+:: A File instance representing the incoming file that should be
+    #          filtered. This file should _not_ be modified.
+    #
+    # Subclasses must implement this method.
+    def run(file)
+      raise NotImplementedError.new("Nanoc::BinaryFilter subclasses must implement #run")
+    end
+
+  end
+
+end

data/lib/nanoc/base/code.rb

@@ -0,0 +1,41 @@
+module Nanoc
+
+  # Nanoc::Code represent the custom code of a nanoc site. It contains the
+  # textual source code as well as a mtime, which is used to speed up site
+  # compilation.
+  class Code
+
+    # The Nanoc::Site this code belongs to.
+    attr_accessor :site
+
+    # The textual source code representation.
+    attr_reader :data
+
+    # The time where the code was last modified.
+    attr_reader :mtime
+
+    # Creates a new code object. +data+ is the raw source code, which will be
+    # executed before compilation. +mtime+ is the time when the code was last
+    # modified (optional).
+    def initialize(data, mtime=nil)
+      @data  = data
+      @mtime = mtime
+    end
+
+    # Loads the code by executing it.
+    def load
+      eval(@data, TOPLEVEL_BINDING)
+    end
+
+    # Saves the code in the database, creating it if it doesn't exist yet or
+    # updating it if it already exists. Tells the site's data source to save
+    # the code.
+    def save
+      @site.data_source.loading do
+        @site.data_source.save_code(self)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/compiler.rb

@@ -1,54 +1,66 @@
 module Nanoc
+
+  # Nanoc::Compiler is responsible for compiling a site's page and asset
+  # representations.
   class Compiler
 
     attr_reader :stack
 
+    # Creates a new compiler for the given site.
     def initialize(site)
-      @site = site
+      @site  = site
+      @stack = []
     end
 
-    def run(page=nil)
-      # Give feedback
-      log(:high, "Compiling #{page.nil? ? 'site' : 'page'}...")
-      time_before = Time.now
+    # Compiles (part of) the site and writes out the compiled page and asset
+    # representations.
+    #
+    # +obj+:: The page or asset that should be compiled, along with their
+    #         dependencies, or +nil+ if the entire site should be compiled.
+    #
+    # This method also accepts a few parameters:
+    #
+    # +:also_layout+:: true if the page rep should also be laid out and
+    #                  post-filtered, false if the page rep should only be
+    #                  pre-filtered. Only applicable to page reps, and not to
+    #                  asset reps. Defaults to true.
+    #
+    # +:even_when_not_outdated+:: true if the rep should be compiled even if
+    #                             it is not outdated, false if not. Defaults
+    #                             to false.
+    #
+    # +:from_scratch+:: true if all compilation stages (for page reps:
+    #                   pre-filter, layout, post-filter; for asset reps:
+    #                   filter) should be performed again even if they have
+    #                   already been performed, false otherwise. Defaults to
+    #                   false.
+    def run(objects=nil, params={})
+      # Parse params
+      also_layout             = params[:also_layout]            || true
+      even_when_not_outdated  = params[:even_when_not_outdated] || false
+      from_scratch            = params[:from_scratch]           || false
 
-      # Get the data we need
+      # Load data
       @site.load_data
-      eval(@site.code, $nanoc_binding)
 
       # Create output directory if necessary
       FileUtils.mkdir_p(@site.config[:output_dir])
 
-      # Compile
+      # Initialize
       @stack = []
-      pages = (page.nil? ? @site.pages : [ page ])
-      pages.each do |current_page|
-        begin
-          current_page.compile
-        rescue => exception
-          handle_exception(exception, current_page, !page.nil?)
-        end
-      end
 
-      # Give feedback
-      log(:high, "No pages were modified.") unless pages.any? { |page| page.modified? }
-      log(:high, "#{page.nil? ? 'Site' : 'Pages'} compiled in #{format('%.2f', Time.now - time_before)}s.")
-    end
+      # Get pages and asset reps
+      objects = @site.pages + @site.assets if objects.nil?
+      reps = objects.map { |o| o.reps }.flatten
 
-    def handle_exception(exception, page, single_page)
-      raise exception if single_page
-
-      log(:high, "ERROR: An exception occured while compiling page #{page.path}.", $stderr)
-      log(:high, "", $stderr)
-      log(:high, "If you think this is a bug in nanoc, please do report it at", $stderr)
-      log(:high, "<http://nanoc.stoneship.org/trac/newticket> -- thanks!", $stderr)
-      log(:high, "", $stderr)
-      log(:high, 'Message:', $stderr)
-      log(:high, '  ' + exception.message, $stderr)
-      log(:high, 'Backtrace:', $stderr)
-      log(:high, exception.backtrace.map { |t| '  - ' + t }.join("\n"), $stderr)
-
-      exit(1)
+      # Compile everything
+      reps.each do |rep|
+        if rep.is_a?(Nanoc::PageRep)
+          rep.compile(also_layout, even_when_not_outdated, from_scratch)
+        else
+          rep.compile(even_when_not_outdated, from_scratch)
+        end
+      end
     end
 
   end

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

@@ -5,18 +5,38 @@ class Hash
   # Cleans up the hash and returns the result. It performs the following
   # operations:
   #
-  # * Values with keys ending in _at and _on are converted into Times and
-  #   Dates, respectively
+  # * Values with keys ending in +_at+ and +_on+ are converted into +Time+ and
+  #   and +Date+ objects, respectively
   # * All keys are converted to symbols
-  # * Value strings 'true', 'false', and 'none' are converted into
-  #   true, false, and nil, respectively
+  # * Value strings 'true', 'false' and 'none' are converted into +true+,
+  #   +false+ and +nil+, respectively
+  #
+  # Hashes are cleaned recursively, so the value of a hash pair will also be
+  # cleaned if the value is a hash.
+  #
+  # For example, the following hash:
+  #
+  #   {
+  #     'foo'       => 'bar',
+  #     :created_on => '2008-05-19',
+  #     :layout     => 'none'
+  #   }
+  #
+  # will be converted into:
+  #
+  #   {
+  #     :foo        => 'bar',
+  #     :created_on => Date.parse('2008-05-19'),
+  #     :layout     => nil
+  #   }
   def clean
     inject({}) do |hash, (key, value)|
       real_key = key.to_s
-      if real_key =~ /_on$/
+
+      if real_key =~ /_on$/ and value.is_a?(String)
         hash.merge(key.to_sym => Date.parse(value))
-      elsif real_key =~ /_at$/
-        hash.merge(key.to_sym => Time.parse(value))
+      elsif real_key =~ /_at$/ and value.is_a?(String)
+        hash.merge(key.to_sym => Time.parse(value.to_s))
       elsif value == 'true'
         hash.merge(key.to_sym => true)
       elsif value == 'false'
@@ -31,4 +51,28 @@ class Hash
     end
   end
 
+  # Returns the hash where all keys are converted to strings. Hash keys are
+  # converted to strings recursively, so the keys of a value of a hash pair
+  # will also be converted to strings if the value is a hash.
+  #
+  # For example, the following hash:
+  #
+  #   {
+  #     'foo' => 'bar',
+  #     :baz  => 'quux'
+  #   }
+  #
+  # will be converted into:
+  #
+  #   {
+  #     :foo  => 'bar',
+  #     :baz  => 'quux'
+  #   }
+  #
+  def stringify_keys
+    inject({}) do |hash, (key, value)|
+      hash.merge(key.to_s => value.is_a?(Hash) ? value.stringify_keys : value)
+    end
+  end
+
 end

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

@@ -0,0 +1,8 @@
+class String
+
+  # Transforms string into an actual path
+  def cleaned_path
+    "/#{self}/".gsub(/^\/+|\/+$/, '/')
+  end
+
+end

data/lib/nanoc/base/data_source.rb

@@ -1,15 +1,31 @@
 module Nanoc
-  class DataSource < Plugin
 
-    attr_reader :config
+  # Nanoc::DataSource is responsible for loading data. It is the (abstract)
+  # superclass for all data sources. Subclasses must at least implement the
+  # data reading methods (+pages+, +page_defaults+, +layouts+, +templates+,
+  # and +code+); all other methods involving data manipulation are optional.
+  #
+  # Apart from the methods for loading and storing data, there are the +up+
+  # and +down+ methods for bringing up and tearing down the connection to the
+  # data source. These should be overridden in subclasses. The +loading+
+  # method wraps +up+ and +down+.
+  #
+  # The +setup+ method is used for setting up a site's data source for the
+  # first time. This method should be overridden in subclasses.
+  class DataSource < Plugin
 
+    # Creates a new data source for the given site.
     def initialize(site)
       @site       = site
       @references = 0
     end
 
-    # Preparation
-
+    # Loads the data source when necessary (calling +up+), yields, and unloads
+    # the data source when it is not being used elsewhere. All data source
+    # queries and data manipulations should be wrapped in a +loading+ block;
+    # it ensures that the data source is loaded when necessary and makes sure
+    # the data source does not get unloaded while it is still being used
+    # elsewhere.
     def loading
       # Load if necessary
       up if @references == 0
@@ -22,31 +38,248 @@ module Nanoc
       down if @references == 0
     end
 
-    def up    ; end
-    def down  ; end
+    ########## Loading and unloading
+
+    # Brings up the connection to the data. This is an abstract method
+    # implemented by the subclass. Depending on the way data is stored, this
+    # may not be necessary. This is the ideal place to connect to the
+    # database, for example.
+    #
+    # Subclasses may implement this method.
+    def up
+    end
+
+    # Brings down the connection to the data. This is an abstract method
+    # implemented by the subclass. This method should undo the effects of
+    # +up+.
+    #
+    # Subclasses may implement this method.
+    def down
+    end
+
+    ########## Creating/updating
+
+    # Creates the bare minimum essentials for this data source to work. This
+    # action will likely be destructive. This method should not create sample
+    # data such as a default home page, a default layout, etc. For example, if
+    # you're using a database, this is where you should create the necessary
+    # tables for the data source to function properly.
+    #
+    # Subclasses must implement this method.
+    def setup
+      not_implemented('setup')
+    end
+
+    # Removes all data stored by this data source. This method undoes the
+    # effects of the +setup+ method.
+    #
+    # Subclasses must implement this method.
+    def destroy
+      not_implemented('destroy')
+    end
+
+    # Updated the content stored in this site to a newer version. A newer
+    # version of a data source may store content in a different format, and
+    # this method will update the stored content to this newer format.
+    #
+    # Subclasses may implement this method.
+    def update
+    end
+
+    ########## Pages
+
+    # Returns the list of pages (represented by Nanoc::Page) in this site.
+    # This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def pages
+      not_implemented('pages')
+    end
+
+    # Saves the given page in the data source, creating it if it doesn't exist
+    # yet and updating the existing copy otherwise.
+    #
+    # Subclasses must implement this method.
+    def save_page(page)
+      not_implemented('save_page')
+    end
+
+    # Changes the path of the given page to the given new path. When changing
+    # a page's path, this method must be used (save_page will not work).
+    #
+    # Subclasses must implement this method.
+    def move_page(page, new_path)
+      not_implemented('move_page')
+    end
+
+    # Removes the given page from the data source.
+    #
+    # Subclasses must implement this method.
+    def delete_page(page)
+      not_implemented('delete_page')
+    end
+
+    ########## Assets
+
+    # Returns the list of assets (represented by Nanoc::Asset) in this site.
+    # This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def assets
+      not_implemented('assets')
+    end
+
+    # Saves the given asset in the data source, creating it if it doesn't
+    # exist yet and updating the existing copy otherwise.
+    #
+    # Subclasses must implement this method.
+    def save_asset(asset)
+      not_implemented('save_asset')
+    end
+
+    # Changes the path of the given asset to the given new path. When changing
+    # a asset's path, this method must be used (save_asset will not work).
+    #
+    # Subclasses must implement this method.
+    def move_asset(asset, new_path)
+      not_implemented('move_asset')
+    end
+
+    # Removes the given asset from the data source.
+    #
+    # Subclasses must implement this method.
+    def delete_asset(asset)
+      not_implemented('delete_asset')
+    end
+
+    ########## Page defaults
 
-    def setup ; end
+    # Returns the page defaults (represented by Nanoc::PageDefaults) of this
+    # site. This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def page_defaults
+      not_implemented('page_defaults')
+    end
 
-    # Loading data
+    # Saves the given page defaults in the data source.
+    #
+    # Subclasses must implement this method.
+    def save_page_defaults(page_defaults)
+      not_implemented('save_page_defaults')
+    end
 
-    def pages         ; error 'DataSource#pages must be overridden'         ; end
-    def page_defaults ; error 'DataSource#page_defaults must be overridden' ; end
-    def layouts       ; error 'DataSource#layouts must be overridden'       ; end
-    def templates     ; error 'DataSource#templates must be overridden'     ; end
-    def code          ; error 'DataSource#code must be overridden'          ; end
+    ########## Asset defaults
 
-    # Creating data
+    # Returns the asset defaults (represented by Nanoc::AssetDefaults) of this
+    # site. This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def asset_defaults
+      not_implemented('asset_defaults')
+    end
 
-    def create_page(name, template)
-      error 'DataSource#create_page must be overridden'
+    # Saves the given asset defaults in the data source.
+    #
+    # Subclasses must implement this method.
+    def save_asset_defaults(asset_defaults)
+      not_implemented('save_asset_defaults')
     end
 
-    def create_layout(name)
-      error 'DataSource#create_layout must be overridden'
+    ########## Layouts
+
+    # Returns the list of layouts (represented by Nanoc::Layout) in this site.
+    # This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def layouts
+      not_implemented('layouts')
     end
 
-    def create_template(name)
-      error 'DataSource#create_template must be overridden'
+    # Saves the given layout in the data source, creating it if it doesn't
+    # exist yet and updating the existing copy otherwise.
+    #
+    # Subclasses must implement this method.
+    def save_layout(layout)
+      not_implemented('save_layout')
+    end
+
+    # Changes the path of the given layout to the given new path. When
+    # changing a layout's path, this method must be used (save_layout will not
+    # work).
+    #
+    # Subclasses must implement this method.
+    def move_layout(layout, new_path)
+      not_implemented('move_layout')
+    end
+
+    # Removes the given layout from the data source.
+    #
+    # Subclasses must implement this method.
+    def delete_layout(layout)
+      not_implemented('delete_layout')
+    end
+
+    ########## Templates
+
+    # Returns the list of templates (represented by Nanoc::Template) in this
+    # site. This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def templates
+      not_implemented('templates')
+    end
+
+    # Saves the given template in the data source, creating it if it doesn't
+    # exist yet and updating the existing copy otherwise.
+    #
+    # Subclasses must implement this method.
+    def save_template(template)
+      not_implemented('save_template')
+    end
+
+    # Changes the name of the given template to the given new name. When
+    # changing a template's name, this method must be used (save_template will
+    # not work).
+    #
+    # Subclasses must implement this method.
+    def move_template(template, new_name)
+      not_implemented('move_template')
+    end
+
+    # Removes the given template from the data source.
+    #
+    # Subclasses must implement this method.
+    def delete_template(template)
+      not_implemented('delete_template')
+    end
+
+    ########## Code
+
+    # Returns the custom code (represented by Nanoc::Code) for this site.
+    # This is an abstract method implemented by the subclass. This can be code
+    # for custom filters, routers, and more, but pretty much any code can
+    # be put in there (global helper functions are very useful).
+    #
+    # Subclasses must implement this method.
+    def code
+      not_implemented('code')
+    end
+
+    # Saves the given code in the data source.
+    #
+    # Subclasses must implement this method.
+    def save_code(code)
+      not_implemented('save_code')
+    end
+
+  private
+
+    def not_implemented(name)
+      raise NotImplementedError.new(
+        "#{self.class} does not override ##{name}, which is required for " +
+        "this data source to be used."
+      )
     end
 
   end