nanoc2 2.2.3

data/lib/nanoc2/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/nanoc2/base/data_source.rb

@@ -0,0 +1,286 @@
+module Nanoc2
+
+  # Nanoc2::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
+
+    # 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
+      @references += 1
+
+      yield
+    ensure
+      # Unload if necessary
+      @references -= 1
+      down if @references == 0
+    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 Nanoc2::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 Nanoc2::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
+
+    # Returns the page defaults (represented by Nanoc2::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
+
+    # 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
+
+    ########## Asset defaults
+
+    # Returns the asset defaults (represented by Nanoc2::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
+
+    # 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
+
+    ########## Layouts
+
+    # Returns the list of layouts (represented by Nanoc2::Layout) in this site.
+    # This is an abstract method implemented by the subclass.
+    #
+    # Subclasses must implement this method.
+    def layouts
+      not_implemented('layouts')
+    end
+
+    # 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 Nanoc2::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 Nanoc2::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
+end

data/lib/nanoc2/base/defaults.rb

@@ -0,0 +1,30 @@
+module Nanoc2
+
+  # Nanoc2::Defaults represent the default attributes for a given set of
+  # objects in the site. It is basically a hash with an optional modification
+  # time.
+  class Defaults
+
+    # Th site where this set of defaults belongs to.
+    attr_accessor :site
+
+    # A hash containing the default attributes.
+    attr_reader   :attributes
+
+    # The time when this set of defaults was last modified.
+    attr_reader   :mtime
+
+    # Creates a new set of defaults.
+    #
+    # +attributes+:: The hash containing the metadata that individual objects
+    #                will override.
+    #
+    # +mtime+:: The time when the defaults were last modified (optional).
+    def initialize(attributes, mtime=nil)
+      @attributes = attributes.clean
+      @mtime      = mtime
+    end
+
+  end
+
+end

data/lib/nanoc2/base/filter.rb

@@ -0,0 +1,93 @@
+module Nanoc2
+
+  # Nanoc2::Filter is responsible for filtering pages and textual assets
+  # (binary assets are filtered using Nanoc2::BinaryFilter). It is the
+  # (abstract) superclass for all textual filters. Subclasses should override
+  # the +run+ method.
+  class Filter < Plugin
+
+    # Deprecated
+    EXTENSIONS_MAP = {}
+
+    # Creates a new filter for the given object (page or asset) and site.
+    #
+    # +kind+:: The kind of object that is passed. Can be either +:page+ or
+    #          +:asset+.
+    #
+    # +obj_rep+:: A proxy for the page or asset representation (Nanoc2::PageRep
+    #             or Nanoc2::AssetRep) that should be compiled by this filter.
+    #
+    # +obj+:: A proxy for the page or asset's page (Nanoc2::Page or
+    #         Nanoc2::Asset).
+    #
+    # +site+:: The site (Nanoc2::Site) this filter belongs to.
+    #
+    # +other_assigns+:: A hash containing other variables that should be made
+    #                   available during filtering.
+    def initialize(obj_rep, other_assigns={})
+      # Determine kind
+      @kind = obj_rep.is_a?(Nanoc2::PageRep) ? :page : :asset
+
+      # Set object
+      @obj_rep = obj_rep
+      @obj     = (@kind == :page ? @obj_rep.page : @obj_rep.asset)
+
+      # Set page/asset and page/asset reps
+      if @kind == :page
+        @page       = @obj
+        @page_rep   = @obj_rep
+      else
+        @asset      = @obj
+        @asset_rep  = @obj_rep
+      end
+
+      # Set site
+      @site = @obj.site
+
+      # Set other assigns
+      @other_assigns  = other_assigns
+    end
+
+    # Runs the filter. This method returns the filtered content.
+    #
+    # +content+:: The unprocessed content that should be filtered.
+    #
+    # Subclasses must implement this method.
+    def run(content)
+      raise NotImplementedError.new("Nanoc2::Filter subclasses must implement #run")
+    end
+
+    # Returns a hash with data that should be available.
+    def assigns
+      @assigns ||= @other_assigns.merge({
+        :_obj_rep   => @obj_rep,
+        :_obj       => @obj,
+        :page_rep   => @kind == :page  ? @page_rep.to_proxy  : nil,
+        :page       => @kind == :page  ? @page.to_proxy      : nil,
+        :asset_rep  => @kind == :asset ? @asset_rep.to_proxy : nil,
+        :asset      => @kind == :asset ? @asset.to_proxy     : nil,
+        :pages      => @site.pages.map    { |obj| obj.to_proxy },
+        :assets     => @site.assets.map   { |obj| obj.to_proxy },
+        :layouts    => @site.layouts.map  { |obj| obj.to_proxy },
+        :config     => @site.config,
+        :site       => @site
+      })
+    end
+
+    # Returns the filename associated with the item that is being filtered.
+    # The returned filename is in the format "page <path> (rep <name>)".
+    def filename
+      if assigns[:layout]
+        "layout #{assigns[:layout].path}"
+      elsif assigns[:page]
+        "page #{assigns[:_obj].path} (rep #{assigns[:_obj_rep].name})"
+      elsif assigns[:asset]
+        "asset #{assigns[:_obj].path} (rep #{assigns[:_obj_rep].name})"
+      else
+        '?'
+      end
+    end
+
+  end
+
+end

data/lib/nanoc2/base/layout.rb

@@ -0,0 +1,91 @@
+module Nanoc2
+
+  # A Nanoc2::Layout represents a layout in a nanoc site. It has content,
+  # attributes (for determining which filter to use for laying out a page), a
+  # path (because layouts are organised hierarchically), and a modification
+  # time (to speed up compilation).
+  class Layout
+
+    # Default values for layouts.
+    DEFAULTS = {
+      :filter => 'erb'
+    }
+
+    # The Nanoc2::Site this layout belongs to.
+    attr_accessor :site
+
+    # The raw content of this layout.
+    attr_reader :content
+
+    # A hash containing this layout's attributes.
+    attr_reader :attributes
+
+    # This layout's path, starting and ending with a slash.
+    attr_reader :path
+
+    # The time when this layout was last modified.
+    attr_reader :mtime
+
+    # Creates a new layout.
+    #
+    # +content+:: The raw content of this layout.
+    #
+    # +attributes+:: A hash containing this layout's attributes.
+    #
+    # +path+:: This layout's path, starting and ending with a slash.
+    #
+    # +mtime+:: The time when this layout was last modified.
+    def initialize(content, attributes, path, mtime=nil)
+      @content    = content
+      @attributes = attributes.clean
+      @path       = path.cleaned_path
+      @mtime      = mtime
+    end
+
+    # Returns a proxy (Nanoc2::LayoutProxy) for this layout.
+    def to_proxy
+      @proxy ||= LayoutProxy.new(self)
+    end
+
+    # Returns the attribute with the given name.
+    def attribute_named(name)
+      return @attributes[name] if @attributes.has_key?(name)
+      return DEFAULTS[name]
+    end
+
+    # Returns the filter class needed for this layout.
+    def filter_class
+      Nanoc2::Filter.named(attribute_named(:filter))
+    end
+
+    # Saves the layout 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 layout.
+    def save
+      @site.data_source.loading do
+        @site.data_source.save_layout(self)
+      end
+    end
+
+    # Moves the layout to a new path. Tells the site's data source to move the
+    # layout.
+    def move_to(new_path)
+      @site.data_source.loading do
+        @site.data_source.move_layout(self, new_path)
+      end
+    end
+
+    # Deletes the layout. Tells the site's data source to delete the layout.
+    def delete
+      @site.data_source.loading do
+        @site.data_source.delete_layout(self)
+      end
+    end
+
+    def inspect
+      "<#{self.class} path=#{self.path}>"
+    end
+
+  end
+
+end