nanoc 2.0.4 → 2.1

data/lib/nanoc.rb

@@ -1,24 +1,95 @@
 module Nanoc
 
-  VERSION = '2.0.4'
+  # The current nanoc version.
+  VERSION = '2.1'
 
-  def self.load_file(*path)
+  # Generic error. Superclass for all nanoc-specific errors.
+  class Error < RuntimeError ; end
+
+  module Errors # :nodoc:
+
+    # Error that is raised when a site is loaded that uses a data source with
+    # an unknown identifier.
+    class UnknownDataSourceError < Error ; end
+
+    # Error that is raised when a site is loaded that uses a data source with
+    # an unknown identifier.
+    class UnknownRouterError < Error ; end
+
+    # Error that is raised during site compilation when a page uses a layout
+    # that is not present in the site.
+    class UnknownLayoutError < Error ; end
+
+    # Error that is raised during site compilation when a page uses a filter
+    # that is not known.
+    class UnknownFilterError < Error ; end
+
+    # Error that is raised during site compilation when a layout is compiled
+    # for which the filter cannot be determined. This is similar to the
+    # UnknownFilterError, but specific for filters for layouts.
+    class CannotDetermineFilterError < Error ; end
+
+    # Error that is raised during site compilation when a page (directly or
+    # indirectly) includes its own page content, leading to endless recursion.
+    class RecursiveCompilationError < Error ; end
+
+    # Error that is raised when a certain function or feature is used that is
+    # no longer supported by nanoc.
+    class NoLongerSupportedError < Error ; end
+
+  end
+
+  module BinaryFilters # :nodoc:
+  end
+
+  module DataSources # :nodoc:
+  end
+
+  module Helpers # :nodoc:
+  end
+
+  module Extra # :nodoc:
+  end
+
+  module Filters # :nodoc:
+  end
+
+  module Routers # :nodoc:
+  end
+
+  # Requires the given Ruby files at the specified path.
+  #
+  # +path+:: An array containing path segments. This path is relative to the
+  #          directory this file (nanoc.rb) is in. Can contain wildcards.
+  def self.load(*path)
     full_path = [ File.dirname(__FILE__), 'nanoc' ] + path
     Dir[File.join(full_path)].each { |f| require f }
   end
 
 end
 
+# Load requirements
+begin ; require 'rubygems' ; rescue LoadError ; end
+require 'yaml'
+require 'fileutils'
+
 # Load base
-Nanoc.load_file('base', 'enhancements.rb')
-Nanoc.load_file('base', 'core_ext', '*.rb')
-Nanoc.load_file('base', 'plugin.rb')
-Nanoc.load_file('base', '*.rb')
+Nanoc.load('base', 'enhancements.rb')
+Nanoc.load('base', 'defaults.rb')
+Nanoc.load('base', 'proxy.rb')
+Nanoc.load('base', 'proxies', '*.rb')
+Nanoc.load('base', 'core_ext', '*.rb')
+Nanoc.load('base', 'plugin.rb')
+Nanoc.load('base', '*.rb')
 
-# Load plugins
-Nanoc.load_file('data_sources', '*.rb')
-Nanoc.load_file('filters', '*.rb')
-Nanoc.load_file('layout_processors', '*.rb')
+# Load extra's
+Nanoc.load('extra', 'core_ext', '*.rb')
+Nanoc.load('extra', '*.rb')
+Nanoc.load('extra', 'vcses', '*.rb')
 
-# Get global binding
-$nanoc_binding = binding
+# Load plugins
+Nanoc.load('data_sources', '*.rb')
+Nanoc.load('filters', '*.rb')
+Nanoc.load('binary_filters', '*.rb')
+Nanoc.load('routers', '*.rb')
+Nanoc.load('helpers', '*.rb')

data/lib/nanoc/base/asset.rb

@@ -0,0 +1,113 @@
+module Nanoc
+
+  # A Nanoc::Asset represents an asset in a nanoc site. It has a file object
+  # (File instance) and attributes, as well as a path. It can also store the
+  # modification time to speed up compilation.
+  #
+  # Each asset has a list of asset representations or reps (Nanoc::AssetRep);
+  # compiling an asset actually compiles all of its assets.
+  class Asset
+
+    # Defaults values for assets.
+    DEFAULTS = {
+      :extension  => 'dat',
+      :binary     => true,
+      :filters    => []
+    }
+
+    # The Nanoc::Site this asset belongs to.
+    attr_accessor :site
+
+    # This assets's file.
+    attr_reader   :file
+
+    # A hash containing this asset's attributes.
+    attr_accessor :attributes
+
+    # This asset's path.
+    attr_reader   :path
+
+    # The time when this asset was last modified.
+    attr_reader   :mtime
+
+    # This asset's list of asset representations.
+    attr_reader   :reps
+
+    # Creates a new asset.
+    #
+    # +file+:: An instance of File representing the uncompiled asset.
+    #
+    # +attributes+:: A hash containing this asset's attributes.
+    #
+    # +path+:: This asset's path.
+    #
+    # +mtime+:: The time when this asset was last modified.
+    def initialize(file, attributes, path, mtime=nil)
+      # Set primary attributes
+      @file           = file
+      @attributes     = attributes.clean
+      @path           = path.cleaned_path
+      @mtime          = mtime
+    end
+
+    # Builds the individual asset representations (Nanoc::AssetRep) for this
+    # asset.
+    def build_reps
+      # Get list of rep names
+      rep_names_default = (@site.asset_defaults.attributes[:reps] || {}).keys
+      rep_names_this    = (@attributes[:reps] || {}).keys + [ :default ]
+      rep_names         = rep_names_default | rep_names_this
+
+      # Get list of reps
+      reps = rep_names.inject({}) do |memo, rep_name|
+        rep = (@attributes[:reps] || {})[rep_name]
+        is_bad = (@attributes[:reps] || {}).has_key?(rep_name) && rep.nil?
+        is_bad ? memo : memo.merge(rep_name => rep || {})
+      end
+
+      # Build reps
+      @reps = []
+      reps.each_pair do |name, attrs|
+        @reps << AssetRep.new(self, attrs, name)
+      end
+    end
+
+    # Returns a proxy (Nanoc::AssetProxy) for this asset.
+    def to_proxy
+      @proxy ||= AssetProxy.new(self)
+    end
+
+    # Returns the attribute with the given name.
+    def attribute_named(name)
+      return @attributes[name] if @attributes.has_key?(name)
+      return @site.asset_defaults.attributes[name] if @site.asset_defaults.attributes.has_key?(name)
+      return DEFAULTS[name]
+    end
+
+    # Saves the asset 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 asset.
+    def save
+      @site.data_source.loading do
+        @site.data_source.save_asset(self)
+      end
+    end
+
+    # Moves the asset to a new path. Tells the site's data source to move the
+    # asset.
+    def move_to(new_path)
+      @site.data_source.loading do
+        @site.data_source.move_asset(self, new_path)
+      end
+    end
+
+    # Deletes the asset. Tells the site's data source to delete the asset.
+    def delete
+      @site.data_source.loading do
+        @site.data_source.delete_asset(self)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/asset_defaults.rb

@@ -0,0 +1,21 @@
+module Nanoc
+
+  # Nanoc::AssetDefaults represent the default attributes for all assets in
+  # the site. If a specific asset attribute is requested, but not found, then
+  # the asset defaults will be queried for this attribute. (If the attribute
+  # doesn't even exist in the asset defaults, hardcoded defaults will be
+  # used.)
+  class AssetDefaults < Defaults
+
+    # Saves the asset defaults 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 asset defaults.
+    def save
+      @site.data_source.loading do
+        @site.data_source.save_asset_defaults(self)
+      end
+    end
+
+  end
+
+end

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