nanoc 2.0 → 2.1

data/lib/nanoc/base/asset_rep.rb

@@ -0,0 +1,277 @@
+module Nanoc
+
+  # A Nanoc::AssetRep is a single representation (rep) of an asset
+  # (Nanoc::Asset). An asset can have multiple representations. A
+  # representation has its own attributes and its own output file. A single
+  # asset can therefore have multiple output files, each run through a
+  # different set of filters with a different layout.
+  #
+  # An asset representation is observable. The following events will be
+  # notified:
+  #
+  # * :compilation_started
+  # * :compilation_ended
+  # * :filtering_started
+  # * :filtering_ended
+  #
+  # The compilation-related events have one parameters (the page
+  # representation); the filtering-related events have two (the page
+  # representation, and a symbol containing the filter class name).
+  class AssetRep
+
+    # The asset (Nanoc::Asset) to which this representation belongs.
+    attr_reader   :asset
+
+    # A hash containing this asset representation's attributes.
+    attr_accessor :attributes
+
+    # This asset representation's unique name.
+    attr_reader   :name
+
+    # Creates a new asset representation for the given asset and with the
+    # given attributes.
+    #
+    # +asset+:: The asset (Nanoc::Asset) to which the new representation will
+    #           belong.
+    #
+    # +attributes+:: A hash containing the new asset representation's
+    #                attributes. This hash must have been run through
+    #                Hash#clean before using it here.
+    #
+    # +name+:: The unique name for the new asset representation.
+    def initialize(asset, attributes, name)
+      # Set primary attributes
+      @asset      = asset
+      @attributes = attributes
+      @name       = name
+
+      # Reset flags
+      @compiled   = false
+      @modified   = false
+      @created    = false
+
+      # Reset stages
+      @filtered   = false
+    end
+
+    # Returns a proxy (Nanoc::AssetRepProxy) for this asset representation.
+    def to_proxy
+      @proxy ||= AssetRepProxy.new(self)
+    end
+
+    # Returns true if this asset rep's output file was created during the last
+    # compilation session, or false if the output file did already exist.
+    def created?
+      @created
+    end
+
+    # Returns true if this asset rep's output file was modified during the
+    # last compilation session, or false if the output file wasn't changed.
+    def modified?
+      @modified
+    end
+
+    # Returns true if this page rep has been compiled, false otherwise.
+    def compiled?
+      @compiled
+    end
+
+    # Returns the path to the output file, including the path to the output
+    # directory specified in the site configuration, and including the
+    # filename and extension.
+    def disk_path
+      @disk_path ||= @asset.site.router.disk_path_for(self)
+    end
+
+    # Returns the path to the output file as it would be used in a web
+    # browser: starting with a slash (representing the web root), and only
+    # including the filename and extension if they cannot be ignored (i.e.
+    # they are not in the site configuration's list of index files).
+    def web_path
+      compile(false, false)
+
+      @web_path ||= @asset.site.router.web_path_for(self)
+    end
+
+    # Returns true if this asset rep's output file is outdated and must be
+    # regenerated, false otherwise.
+    def outdated?
+      # Outdated if we don't know
+      return true if @asset.mtime.nil?
+
+      # Outdated if compiled file doesn't exist
+      return true if !File.file?(disk_path)
+
+      # Get compiled mtime
+      compiled_mtime = File.stat(disk_path).mtime
+
+      # Outdated if file too old
+      return true if @asset.mtime > compiled_mtime
+
+      # Outdated if asset defaults outdated
+      return true if @asset.site.asset_defaults.mtime.nil?
+      return true if @asset.site.asset_defaults.mtime > compiled_mtime
+
+      # Outdated if code outdated
+      return true if @asset.site.code.mtime.nil?
+      return true if @asset.site.code.mtime > compiled_mtime
+
+      return false
+    end
+
+    # Returns the attribute with the given name. This method will look in
+    # several places for the requested attribute:
+    #
+    # 1. This asset representation's attributes;
+    # 2. The attributes of this asset representation's asset;
+    # 3. The asset defaults' representation corresponding to this asset
+    #    representation;
+    # 4. The asset defaults in general;
+    # 5. The hardcoded asset defaults, if everything else fails.
+    def attribute_named(name)
+      # Check in here
+      return @attributes[name] if @attributes.has_key?(name)
+
+      # Check in asset
+      return @asset.attributes[name] if @asset.attributes.has_key?(name)
+
+      # Check in asset defaults' asset rep
+      asset_default_reps = @asset.site.asset_defaults.attributes[:reps] || {}
+      asset_default_rep  = asset_default_reps[@name] || {}
+      return asset_default_rep[name] if asset_default_rep.has_key?(name)
+
+      # Check in site defaults (global)
+      asset_defaults_attrs = @asset.site.asset_defaults.attributes
+      return asset_defaults_attrs[name] if asset_defaults_attrs.has_key?(name)
+
+      # Check in hardcoded defaults
+      return Nanoc::Asset::DEFAULTS[name]
+    end
+
+    # Compiles the asset representation and writes the result to the disk.
+    # This method should not be called directly; please use
+    # Nanoc::Compiler#run instead, and pass this asset representation's asset
+    # as its first argument.
+    #
+    # The asset representation will only be compiled if it wasn't compiled
+    # before yet. To force recompilation of the asset rep, forgetting any
+    # progress, set +from_scratch+ to true.
+    #
+    # +even_when_not_outdated+:: true if the asset rep should be compiled even
+    #                            if it is not outdated, false if not.
+    #
+    # +from_scratch+:: true if the asset rep should be filtered again even if
+    #                  it has already been filtered, false otherwise.
+    def compile(even_when_not_outdated, from_scratch)
+      # Don't compile if already compiled
+      return if @compiled and !from_scratch
+
+      # Skip unless outdated
+      unless outdated? or even_when_not_outdated
+        Nanoc::NotificationCenter.post(:compilation_started, self)
+        Nanoc::NotificationCenter.post(:compilation_ended,   self)
+        return
+      end
+
+      # Reset flags
+      @compiled = false
+      @modified = false
+      @created  = !File.file?(self.disk_path)
+
+      # Forget progress if requested
+      @filtered = false if from_scratch
+
+      # Start
+      @asset.site.compiler.stack.push(self)
+      Nanoc::NotificationCenter.post(:compilation_started, self)
+
+      # Compile
+      unless @filtered
+        if attribute_named(:binary) == true
+          compile_binary
+        else
+          compile_textual
+        end
+      end
+      @compiled = true
+
+      # Stop
+      @asset.site.compiler.stack.pop
+      Nanoc::NotificationCenter.post(:compilation_ended, self)
+    end
+
+  private
+
+    # Computes and returns the MD5 digest for the given file.
+    def digest(file)
+      # Create hash
+      incr_digest = Digest::MD5.new()
+
+      # Collect data
+      file.rewind
+      incr_digest << file.read(1000) until file.eof?
+
+      # Calculate hex hash
+      incr_digest.hexdigest
+    end
+
+    # Compiles the asset rep, treating its contents as binary data.
+    def compile_binary
+      # Calculate digest before
+      digest_before = File.file?(disk_path) ? digest(File.open(disk_path, 'r')) : nil
+
+      # Run filters
+      current_file = @asset.file
+      attribute_named(:filters).each do |filter_name|
+        # Free resources so that this filter won't fail
+        GC.start
+
+        # Create filter
+        klass = Nanoc::BinaryFilter.named(filter_name)
+        raise Nanoc::Errors::UnknownFilterError.new(filter_name) if klass.nil?
+        filter = klass.new(self.to_proxy, @asset.to_proxy, @asset.site)
+
+        # Run filter
+        Nanoc::NotificationCenter.post(:filtering_started, self, klass.identifier)
+        current_file = filter.run(current_file)
+        Nanoc::NotificationCenter.post(:filtering_ended,   self, klass.identifier)
+      end
+
+      # Write asset
+      FileUtils.mkdir_p(File.dirname(self.disk_path))
+      FileUtils.cp(current_file.path, disk_path)
+
+      # Calculate digest after
+      digest_after = digest(current_file)
+      @modified = (digest_after != digest_before)
+    end
+
+    # Compiles the asset rep, treating its contents as textual data.
+    def compile_textual
+      # Get content
+      current_content = @asset.file.read
+
+      # Check modified
+      @modified = @created ? true : File.read(self.disk_path) != current_content
+
+      # Run filters
+      attribute_named(:filters).each do |filter_name|
+        # Create filter
+        klass = Nanoc::Filter.named(filter_name)
+        raise Nanoc::Errors::UnknownFilterError.new(filter_name) if klass.nil?
+        filter = klass.new(self)
+
+        # Run filter
+        Nanoc::NotificationCenter.post(:filtering_started, self, klass.identifier)
+        current_content = filter.run(current_content)
+        Nanoc::NotificationCenter.post(:filtering_ended,   self, klass.identifier)
+      end
+
+      # Write asset
+      FileUtils.mkdir_p(File.dirname(self.disk_path))
+      File.open(self.disk_path, 'w') { |io| io.write(current_content) }
+    end
+
+  end
+
+end

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