nanoc3 3.2.4 → 3.3.0

data/lib/nanoc3/base/source_data/code_snippet.rb

@@ -1,58 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3
-
-  # Nanoc3::CodeSnippet represent a piece of custom code of a nanoc site.
-  class CodeSnippet
-
-    # A string containing the actual code in this code snippet.
-    #
-    # @return [String]
-    attr_reader :data
-
-    # The filename corresponding to this code snippet.
-    #
-    # @return [String]
-    attr_reader :filename
-
-    # Creates a new code snippet.
-    #
-    # @param [String] data The raw source code which will be executed before
-    #   compilation
-    #
-    # @param [String] filename The filename corresponding to this code snippet
-    #
-    # @param [Time, Hash] params Extra parameters. Ignored by nanoc; it is
-    #   only included for backwards compatibility.
-    def initialize(data, filename, params=nil)
-      @data     = data
-      @filename = filename
-    end
-
-    # Loads the code by executing it.
-    #
-    # @return [void]
-    def load
-      eval(@data, TOPLEVEL_BINDING, @filename)
-    end
-
-    # Returns an object that can be used for uniquely identifying objects.
-    #
-    # @return [Object] An unique reference to this object
-    def reference
-      [ :code_snippet, filename ]
-    end
-
-    def inspect
-      "<#{self.class}:0x#{self.object_id.to_s(16)} filename=#{self.filename}>"
-    end
-
-    # @return [String] The checksum for this object. If its contents change,
-    #   the checksum will change as well.
-    def checksum
-      @data.checksum
-    end
-
-  end
-
-end

data/lib/nanoc3/base/source_data/configuration.rb

@@ -1,24 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3
-
-  # Represents the site configuration.
-  class Configuration < ::Hash
-
-    # Creates a new configuration with the given hash.
-    #
-    # @param [Hash] hash The actual configuration hash
-    def initialize(hash)
-      self.replace(hash)
-    end
-
-    # Returns an object that can be used for uniquely identifying objects.
-    #
-    # @return [Object] An unique reference to this object
-    def reference
-      :config
-    end
-
-  end
-
-end

data/lib/nanoc3/base/source_data/data_source.rb

@@ -1,234 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3
-
-  # Responsible for loading site data. It is the (abstract) superclass for all
-  # data sources. Subclasses must at least implement the data reading methods
-  # ({#items} and {#layouts}); 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}. {#loading} is a convenience method for the
-  # more low-level methods {#use} and {#unuse}, which respectively increment
-  # and decrement the reference count; when the reference count goes from 0 to
-  # 1, the data source will be loaded ({#up} will be called) and when the
-  # reference count goes from 1 to 0, the data source will be unloaded
-  # ({#down} will be called).
-  #
-  # The {#setup} method is used for setting up a site's data source for the
-  # first time.
-  #
-  # @abstract Subclasses should at least implement {#items} and {#layouts}. If
-  #   the data source should support creating items and layouts using the
-  #   `create_item` and `create_layout` CLI commands, the {#setup},
-  #   {#create_item} and {#create_layout} methods should be implemented as
-  #   well.
-  class DataSource
-
-    # @return [String] The root path where items returned by this data source
-    #   should be mounted.
-    attr_reader :items_root
-
-    # @return [String] The root path where layouts returned by this data
-    #   source should be mounted.
-    attr_reader :layouts_root
-
-    # @return [Hash] The configuration for this data source. For example,
-    #   online data sources could contain authentication details.
-    attr_reader :config
-
-    extend Nanoc3::PluginRegistry::PluginMethods
-
-    # Creates a new data source for the given site.
-    #
-    # @param [Nanoc3::Site] site The site this data source belongs to.
-    #
-    # @param [String] items_root The prefix that should be given to all items
-    #   returned by the #items method (comparable to mount points for
-    #   filesystems in Unix-ish OSes).
-    #
-    # @param [String] layouts_root The prefix that should be given to all
-    #   layouts returned by the #layouts method (comparable to mount points
-    #   for filesystems in Unix-ish OSes).
-    #
-    # @param [Hash] config The configuration for this data source.
-    def initialize(site, items_root, layouts_root, config)
-      @site         = site
-      @items_root   = items_root
-      @layouts_root = layouts_root
-      @config       = config
-
-      @references = 0
-    end
-
-    # Loads the data source when necessary (calling {#up}), yields, and
-    # unloads (using {#down}) 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.
-    #
-    # @return [void]
-    def loading
-      use
-      yield
-    ensure
-      unuse
-    end
-
-    # Marks the data source as used by the caller.
-    #
-    # Calling this method increases the internal reference count. When the
-    # data source is used for the first time (first {#use} call), the data
-    # source will be loaded ({#up} will be called).
-    #
-    # @return [void]
-    def use
-      up if @references == 0
-      @references += 1
-    end
-
-    # Marks the data source as unused by the caller.
-    #
-    # Calling this method decreases the internal reference count. When the
-    # reference count reaches zero, i.e. when the data source is not used any
-    # more, the data source will be unloaded ({#down} will be called).
-    #
-    # @return [void]
-    def unuse
-      @references -= 1
-      down if @references == 0
-    end
-
-    # Brings up the connection to the data. 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 override this method, but are not required to do so; the
-    # default implementation simply does nothing.
-    #
-    # @return [void]
-    def up
-    end
-
-    # Brings down the connection to the data. This method should undo the
-    # effects of the {#up} method. For example, a database connection
-    # established in {#up} should be closed in this method.
-    #
-    # Subclasses may override this method, but are not required to do so; the
-    # default implementation simply does nothing.
-    #
-    # @return [void]
-    def down
-    end
-
-    # 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,
-    # when using a database, this is where you should create the necessary
-    # tables for the data source to function properly.
-    #
-    # @abstract
-    #
-    # @return [void]
-    def setup
-      not_implemented('setup')
-    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 override this method, but are not required to do so; the
-    # default implementation simply does nothing.
-    #
-    # @return [void]
-    def update
-    end
-
-    # Returns the list of items (represented by {Nanoc3::Item}) in this site.
-    # The default implementation simply returns an empty array.
-    #
-    # Subclasses should not prepend `items_root` to the item's identifiers, as
-    # this will be done automatically.
-    #
-    # Subclasses may override this method, but are not required to do so; the
-    # default implementation simply does nothing.
-    #
-    # @return [Array<Nanoc3::Item>] A list of items
-    def items
-      []
-    end
-
-    # Returns the list of layouts (represented by {Nanoc3::Layout}) in this
-    # site. The default implementation simply returns an empty array.
-    #
-    # Subclasses should prepend `layout_root` to the layout's identifiers,
-    # since this is not done automatically.
-    #
-    # Subclasses may override this method, but are not required to do so; the
-    # default implementation simply does nothing.
-    #
-    # @return [Array<Nanoc3::Layout>] A list of layouts
-    def layouts
-      []
-    end
-
-    # Creates a new item with the given content, attributes and identifier. No
-    # instance of {Nanoc3::Item} will be created; this method creates the item
-    # in the data source so that it can be loaded and turned into a
-    # {Nanoc3::Item} instance by the {#items} method.
-    #
-    # @abstract
-    #
-    # @param [String] content
-    #
-    # @param [Hash] attributes
-    #
-    # @param [String] identifier
-    #
-    # @param [Hash] params Extra parameters to give to the data source. This
-    #   can be used to influence the way items are stored. For example,
-    #   filesystem data sources could use this to pass the extension of the
-    #   files that should be generated.
-    #
-    # @return [void]
-    def create_item(content, attributes, identifier, params={})
-      not_implemented('create_item')
-    end
-
-    # Creates a new layout with the given content, attributes and identifier.
-    # No instance of {Nanoc3::Layout} will be created; this method creates the
-    # layout in the data source so that it can be loaded and turned into a
-    # {Nanoc3::Layout} instance by the {#layouts} method.
-    #
-    # @abstract
-    #
-    # @param [String] content
-    #
-    # @param [Hash] attributes
-    #
-    # @param [String] identifier
-    #
-    # @param [Hash] params Extra parameters to give to the data source. This
-    #   can be used to influence the way items are stored. For example,
-    #   filesystem data sources could use this to pass the extension of the
-    #   files that should be generated.
-    #
-    # @return [void]
-    def create_layout(content, attributes, identifier, params={})
-      not_implemented('create_layout')
-    end
-
-  private
-
-    def not_implemented(name)
-      raise NotImplementedError.new(
-        "#{self.class} does not implement ##{name}"
-      )
-    end
-
-  end
-end

data/lib/nanoc3/base/source_data/item.rb

@@ -1,301 +0,0 @@
-# encoding: utf-8
-
-module Nanoc3
-
-  # Represents a compileable item in a site. It has content and attributes, as
-  # well as an identifier (which starts and ends with a slash). It can also
-  # store the modification time to speed up compilation.
-  class Item
-
-    extend Nanoc3::Memoization
-
-    # @return [Hash] This item's attributes
-    attr_accessor :attributes
-
-    # A string that uniquely identifies an item in a site.
-    #
-    # Identifiers start and end with a slash. They are comparable to paths on
-    # the filesystem, with the difference that file system paths usually do
-    # not have a trailing slash. The item hierarchy (parent and children of
-    # items) is determined by the item identifier.
-    #
-    # The root page (the home page) has the identifier “/”, which means
-    # that it is the ancestor of all other items.
-    #
-    # @return [String] This item's identifier
-    attr_accessor :identifier
-
-    # @return [Array<Nanoc3::ItemRep>] This item’s list of item reps
-    attr_reader   :reps
-
-    # @return [String] This item's raw, uncompiled content of this item (only
-    #   available for textual items)
-    attr_reader   :raw_content
-
-    # @return [String] The filename pointing to the file containing this
-    #   item’s content (only available for binary items)
-    attr_reader   :raw_filename
-
-    # @return [Nanoc3::Item, nil] The parent item of this item. This can be
-    #   nil even for non-root items.
-    attr_accessor :parent
-
-    # @return [Array<Nanoc3::Item>] The child items of this item
-    attr_accessor :children
-
-    # Creates a new item with the given content or filename, attributes and
-    # identifier.
-    #
-    # @param [String] raw_content_or_raw_filename The uncompiled item content
-    #   (if it is a textual item) or the path to the filename containing the
-    #   content (if it is a binary item).
-    #
-    # @param [Hash] attributes A hash containing this item's attributes.
-    #
-    # @param [String] identifier This item's identifier.
-    #
-    # @param [Time, Hash] params Extra parameters. For backwards
-    #   compatibility, this can be a Time instance indicating the time when
-    #   this item was last modified (mtime).
-    #
-    # @option params [Time, nil] :mtime (nil) The time when this item was last
-    #   modified. Deprecated; pass the modification time as the `:mtime`
-    #   attribute instead.
-    #
-    # @option params [Symbol, nil] :binary (true) Whether or not this item is
-    #   binary
-    def initialize(raw_content_or_raw_filename, attributes, identifier, params=nil)
-      # Parse params
-      params ||= {}
-      params = { :mtime => params } if params.is_a?(Time)
-      params[:binary] = false unless params.has_key?(:binary)
-
-      if raw_content_or_raw_filename.nil?
-        raise "attempted to create an item with no content/filename (identifier #{identifier})"
-      end
-
-      # Get type and raw content or raw filename
-      @is_binary = params[:binary]
-      if @is_binary
-        @raw_filename = raw_content_or_raw_filename
-      else
-        @raw_content  = raw_content_or_raw_filename
-      end
-
-      # Get rest of params
-      @attributes   = attributes.symbolize_keys
-      @identifier   = identifier.cleaned_identifier.freeze
-
-      # Set mtime
-      @attributes.merge!(:mtime => params[:mtime]) if params[:mtime]
-
-      @parent       = nil
-      @children     = []
-
-      @reps         = []
-    end
-
-    # Returns the rep with the given name.
-    #
-    # @param [Symbol] rep_name The name of the representation to return
-    #
-    # @return [Nanoc3::ItemRep] The representation with the given name
-    def rep_named(rep_name)
-      @reps.find { |r| r.name == rep_name }
-    end
-
-    # Returns the compiled content from a given representation and a given
-    # snapshot. This is a convenience method that makes fetching compiled
-    # content easier.
-    #
-    # @option params [String] :rep (:default) The name of the representation
-    #   from which the compiled content should be fetched. By default, the
-    #   compiled content will be fetched from the default representation.
-    #
-    # @option params [String] :snapshot The name of the snapshot from which to
-    #   fetch the compiled content. By default, the returned compiled content
-    #   will be the content compiled right before the first layout call (if
-    #   any).
-    #
-    # @return [String] The compiled content of the given rep (or the default
-    #   rep if no rep is specified) at the given snapshot (or the default
-    #   snapshot if no snapshot is specified)
-    #
-    # @see ItemRep#compiled_content
-    def compiled_content(params={})
-      # Get rep
-      rep_name = params[:rep] || :default
-      rep = reps.find { |r| r.name == rep_name }
-      if rep.nil?
-        raise Nanoc3::Errors::Generic,
-          "No rep named #{rep_name.inspect} was found."
-      end
-
-      # Get rep's content
-      rep.compiled_content(params)
-    end
-
-    # Returns the path from a given representation. This is a convenience
-    # method that makes fetching the path of a rep easier.
-    #
-    # @option params [String] :rep (:default) The name of the representation
-    #   from which the path should be fetched. By default, the path will be
-    #   fetched from the default representation.
-    #
-    # @return [String] The path of the given rep ( or the default rep if no
-    #   rep is specified)
-    def path(params={})
-      rep_name = params[:rep] || :default
-
-      # Get rep
-      rep = reps.find { |r| r.name == rep_name }
-      if rep.nil?
-        raise Nanoc3::Errors::Generic,
-          "No rep named #{rep_name.inspect} was found."
-      end
-
-      # Get rep's path
-      rep.path
-    end
-
-    # Requests the attribute with the given key.
-    #
-    # @param [Symbol] key The name of the attribute to fetch
-    #
-    # @return [Object] The value of the requested attribute
-    def [](key)
-      Nanoc3::NotificationCenter.post(:visit_started, self)
-      Nanoc3::NotificationCenter.post(:visit_ended,   self)
-
-      # Get captured content (hax)
-      # TODO [in nanoc 4.0] remove me
-      if key.to_s =~ /^content_for_(.*)$/
-        @@_content_for_warning_issued ||= false
-        @@_Nanoc3_Helpers_Capturing_included ||= false
-
-        # Warn
-        unless @@_content_for_warning_issued
-          warn 'WARNING: Accessing captured content should happen using the #content_for method defined in the Capturing helper instead of using item[:content_for_something]. The latter way of accessing captured content will be removed in nanoc 4.0.'
-          @@_content_for_warning_issued = true
-        end
-
-        # Include capturing helper if necessary
-        unless @@_Nanoc3_Helpers_Capturing_included
-          self.class.send(:include, ::Nanoc3::Helpers::Capturing)
-          @@_Nanoc3_Helpers_Capturing_included = true
-        end
-
-        # Get content
-        return content_for(self, $1.to_sym)
-      end
-
-      @attributes[key]
-    end
-
-    # Sets the attribute with the given key to the given value.
-    #
-    # @param [Symbol] key The name of the attribute to set
-    #
-    # @param [Object] value The value of the attribute to set
-    def []=(key, value)
-      @attributes[key] = value
-    end
-
-    # @return [Boolean] True if the item is binary; false if it is not
-    def binary?
-      !!@is_binary
-    end
-
-    # Returns the type of this object. Will always return `:item`, because
-    # this is an item. For layouts, this method returns `:layout`.
-    #
-    # @api private
-    #
-    # @return [Symbol] :item
-    def type
-      :item
-    end
-
-    # Returns an object that can be used for uniquely identifying objects.
-    #
-    # @api private
-    #
-    # @return [Object] An unique reference to this object
-    def reference
-      [ type, self.identifier ]
-    end
-
-    # Prevents all further modifications to its attributes.
-    #
-    # @return [void]
-    def freeze
-      attributes.freeze_recursively
-      children.freeze
-      identifier.freeze
-      raw_filename.freeze if raw_filename
-      raw_content.freeze  if raw_content
-    end
-
-    def inspect
-      "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier} binary?=#{self.binary?}>"
-    end
-
-    # @return [String] The checksum for this object. If its contents change,
-    #   the checksum will change as well.
-    def checksum
-      content_checksum = if binary?
-        if File.exist?(raw_filename)
-          Pathname.new(raw_filename).checksum
-        else
-          ''.checksum
-        end
-      else
-        @raw_content.checksum
-      end
-
-      attributes = @attributes.dup
-      attributes.delete(:file)
-      attributes_checksum = attributes.checksum
-
-      content_checksum + ',' + attributes_checksum
-    end
-    memoize :checksum
-
-    def hash
-      self.class.hash ^ self.identifier.hash
-    end
-
-    def eql?(other)
-      self.class == other.class && self.identifier == other.identifier
-    end
-
-    def ==(other)
-      self.eql?(other)
-    end
-
-    def marshal_dump
-      [
-        @is_binary,
-        @raw_filename,
-        @raw_content,
-        @attributes,
-        @identifier
-      ]
-    end
-
-    def marshal_load(source)
-      @is_binary,
-      @raw_filename,
-      @raw_content,
-      @attributes,
-      @identifier = *source
-    end
-
-    # @deprecated Access the modification time using `item[:mtime]` instead.
-    def mtime
-      self[:mtime]
-    end
-
-  end
-
-end