nanoc 2.0 → 2.1

data/lib/nanoc/base/plugin.rb

@@ -1,19 +1,67 @@
 module Nanoc
+
+  # Nanoc::Plugin is the superclass for all plugins, such as filters
+  # (Nanoc::Filter), binary filters (Nanoc::BinaryFilter), routers
+  # (Nanoc::Router), data sources (Nanoc::DataSource) and VCSes
+  # (Nanoc::Extra::VCS). Each plugin has one or more unique identifiers, and
+  # several methods in this class provides functionality for finding plugins
+  # with given identifiers.
   class Plugin
 
+    MAP = {}
+
     class << self
-      attr_accessor :_identifiers
-    end
 
-    def self.identifiers(*identifiers)
-      self._identifiers = [] unless instance_variable_defined?(:@_identifiers)
-      identifiers.empty? ? self._identifiers || [] : self._identifiers = (self._identifiers || []) + identifiers
-    end
+      # Sets or returns the identifiers for this plugin.
+      #
+      # When given a list of identifier symbols, sets the identifiers for
+      # this plugin. When given nothing, returns an array of identifier
+      # symbols for this plugin.
+      def identifiers(*identifiers)
+        # Initialize
+        @identifiers = [] unless instance_variables.include?('@identifiers')
+
+        if identifiers.empty?
+          @identifiers
+        else
+          @identifiers = identifiers
+          @identifiers.each { |i| register(i, self) }
+        end
+      end
+
+      # Sets or returns the identifier for this plugin.
+      #
+      # When given an identifier symbols, sets the identifier for this plugin.
+      # When given nothing, returns the identifier for this plugin.
+      def identifier(identifier=nil)
+        # Initialize
+        @identifiers = [] unless instance_variables.include?('@identifiers')
+
+        if identifier.nil?
+          @identifiers.first
+        else
+          @identifiers = [ identifier ]
+          register(identifier, self)
+        end
+      end
+
+      # Registers the given class +klass+ with the given name. This will allow
+      # the named method to find the class.
+      def register(name, klass)
+        MAP[klass.superclass] ||= {}
+        MAP[klass.superclass][name.to_sym] = klass
+      end
+
+      # Returns the the plugin with the given name. Only subclasses of this
+      # class will be searched. For example, calling this method on
+      # Nanoc::Filter will cause only Nanoc::Filter subclasses to be searched.
+      def named(name)
+        MAP[self] ||= {}
+        MAP[self][name.to_sym]
+      end
 
-    def self.identifier(identifier=nil)
-      self._identifiers = [] unless instance_variable_defined?(:@_identifiers)
-      identifier.nil? ? self.identifiers.first : self.identifiers(identifier)
     end
 
   end
+
 end

data/lib/nanoc/base/proxies/asset_proxy.rb

@@ -0,0 +1,29 @@
+module Nanoc
+
+  # Nanoc::AssetProxy is a proxy object for an asset (Nanoc::Asset).
+  class AssetProxy < Proxy
+
+    # Requests the asset attribute with the given name. +key+ can be a string
+    # or a symbol, and it can contain a trailing question mark (which will be
+    # stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      if real_key == :mtime
+        @obj.mtime
+      elsif real_key == :path # backward compatibility
+        @obj.reps.find { |r| r.name == :default }.web_path
+      else
+        super(key)
+      end
+    end
+
+    # Returns the asset representation with the given name.
+    def reps(name)
+      rep = @obj.reps.find { |r| r.name == name }
+      rep.nil? ? nil : rep.to_proxy
+    end
+
+  end
+
+end

data/lib/nanoc/base/proxies/asset_rep_proxy.rb

@@ -0,0 +1,26 @@
+module Nanoc
+
+  # Nanoc::AssetRepProxy is a proxy object for an asset representation
+  # (Nanoc::AssetRep).
+  class AssetRepProxy < Proxy
+
+    # Requests the asset representation attribute with the given name. +key+
+    # can be a string or a symbol, and it can contain a trailing question mark
+    # (which will be stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      if real_key == :name
+        @obj.name
+      elsif real_key == :path
+        @obj.web_path
+      elsif real_key == :asset
+        @obj.asset.to_proxy
+      else
+        super(key)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/proxies/layout_proxy.rb

@@ -0,0 +1,25 @@
+module Nanoc
+
+  # Nanoc::LayoutProxy is a proxy object for a layout (Nanoc::Layout).
+  class LayoutProxy < Proxy
+
+    # Requests the layout attribute with the given name. +key+ can be a string
+    # or a symbol, and it can contain a trailing question mark (which will be
+    # stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      if real_key == :content
+        @obj.content
+      elsif real_key == :path
+        @obj.path
+      elsif real_key == :mtime
+        @obj.mtime
+      else
+        super(key)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/proxies/page_proxy.rb

@@ -0,0 +1,35 @@
+module Nanoc
+
+  # Nanoc::PageProxy is a proxy object for a page (Nanoc::Page).
+  class PageProxy < Proxy
+
+    # Requests the page attribute with the given name. +key+ can be a string
+    # or a symbol, and it can contain a trailing question mark (which will be
+    # stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      if real_key == :mtime
+        @obj.mtime
+      elsif real_key == :parent
+        @obj.parent.nil? ? nil : @obj.parent.to_proxy
+      elsif real_key == :children
+        @obj.children.map { |page| page.to_proxy }
+      elsif real_key == :content # backward compatibility
+        @obj.reps.find { |r| r.name == :default }.content
+      elsif real_key == :path # backward compatibility
+        @obj.reps.find { |r| r.name == :default }.web_path
+      else
+        super(key)
+      end
+    end
+
+    # Returns the page representation with the given name.
+    def reps(name)
+      rep = @obj.reps.find { |r| r.name == name }
+      rep.nil? ? nil : rep.to_proxy
+    end
+
+  end
+
+end

data/lib/nanoc/base/proxies/page_rep_proxy.rb

@@ -0,0 +1,28 @@
+module Nanoc
+
+  # Nanoc::PageRepProxy is a proxy object for a page representation
+  # (Nanoc::PageRep).
+  class PageRepProxy < Proxy
+
+    # Requests the page representation attribute with the given name. +key+
+    # can be a string or a symbol, and it can contain a trailing question mark
+    # (which will be stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      if real_key == :name
+        @obj.name
+      elsif real_key == :content
+        @obj.content
+      elsif real_key == :path
+        @obj.web_path
+      elsif real_key == :page
+        @obj.page.to_proxy
+      else
+        super(key)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/base/proxy.rb

@@ -0,0 +1,37 @@
+module Nanoc
+
+  # Nanoc::Proxy is used when making data available to pages and layouts.
+  # It provides an easy way to access data without the risk of accidentally
+  # calling destructive methods.
+  class Proxy
+
+    instance_methods.each { |m| undef_method m unless m =~ /^__/ }
+
+    # Creates a proxy for the given object.
+    def initialize(obj)
+      @obj = obj
+    end
+
+    # Requests the attribute with the given name. +key+ can be a string or a
+    # symbol, and it can contain a trailing question mark (which will be
+    # stripped).
+    def [](key)
+      real_key = key.to_s.sub(/\?$/, '').to_sym
+
+      @obj.attribute_named(real_key)
+    end
+
+    # Sets a given attribute. The use of setting an object's attributes is not
+    # recommended but may be necessary in some cases.
+    def []=(key, value)
+      @obj.attributes[key.to_sym] = value
+    end
+
+    # Used for requesting attributes without accessing the proxy like a hash.
+    def method_missing(method, *args)
+      self[method]
+    end
+
+  end
+
+end

data/lib/nanoc/base/router.rb

@@ -0,0 +1,72 @@
+module Nanoc
+
+  # A Nanoc::Router is an abstract superclass that determines the paths of
+  # page and asset representations, both the path on the disk (relative to the
+  # site's output directory) and the path as it appears on the web site.
+  class Router < Plugin
+
+    # Creates a new router for the given site.
+    def initialize(site)
+      @site = site
+    end
+
+    # Returns the routed path for the given page representation, including the
+    # filename and the extension. It should start with a slash, and should be
+    # relative to the web root (i.e. should not include any references to the
+    # output directory). There is no need to let this method handle custom
+    # paths.
+    #
+    # Subclasses must implement this method.
+    def path_for_page_rep(page_rep)
+      raise NotImplementedError.new("Nanoc::Router subclasses must implement #path_for_page_rep.")
+    end
+
+    # Returns the routed path for the given asset representation, including
+    # the filename and the extension. It should start with a slash, and should
+    # be relative to the web root (i.e. should not include any references to
+    # the output directory). There is no need to let this method handle custom
+    # paths.
+    #
+    # Subclasses must implement this method.
+    def path_for_asset_rep(asset_rep)
+      raise NotImplementedError.new("Nanoc::Router subclasses must implement #path_for_asset_rep.")
+    end
+
+    # Returns the web path for the given page or asset representation, i.e.
+    # the page or asset rep's custom path or routed path with index filenames
+    # stripped.
+    def web_path_for(obj)
+      # Get actual path
+      path ||= obj.attribute_named(:custom_path)
+      if obj.is_a?(Nanoc::PageRep) # Page rep
+        path ||= path_for_page_rep(obj)
+      else # Asset rep
+        path ||= path_for_asset_rep(obj)
+      end
+
+      # Try stripping each index filename
+      @site.config[:index_filenames].each do |index_filename|
+        if path[-index_filename.length..-1] == index_filename
+          # Strip and stop
+          path = path[0..-index_filename.length-1]
+          break
+        end
+      end
+
+      # Return possibly stripped path
+      path
+    end
+
+    # Returns the disk path for the given page or asset representation, i.e.
+    # the page or asset's custom path or routed path relative to the output
+    # directory.
+    def disk_path_for(obj)
+      @site.config[:output_dir] + (
+        obj.attribute_named(:custom_path) ||
+        (obj.is_a?(Nanoc::PageRep) ? path_for_page_rep(obj) : path_for_asset_rep(obj))
+      )
+    end
+
+  end
+
+end