nanoc 3.2.4 → 3.3.0

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

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # Nanoc::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} 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/nanoc/base/source_data/configuration.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # 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/nanoc/base/source_data/data_source.rb

@@ -0,0 +1,234 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # 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 Nanoc::PluginRegistry::PluginMethods
+
+    # Creates a new data source for the given site.
+    #
+    # @param [Nanoc::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 {Nanoc::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<Nanoc::Item>] A list of items
+    def items
+      []
+    end
+
+    # Returns the list of layouts (represented by {Nanoc::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<Nanoc::Layout>] A list of layouts
+    def layouts
+      []
+    end
+
+    # Creates a new item with the given content, attributes and identifier. No
+    # instance of {Nanoc::Item} will be created; this method creates the item
+    # in the data source so that it can be loaded and turned into a
+    # {Nanoc::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 {Nanoc::Layout} will be created; this method creates the
+    # layout in the data source so that it can be loaded and turned into a
+    # {Nanoc::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/nanoc/base/source_data/item.rb

@@ -0,0 +1,301 @@
+# encoding: utf-8
+
+module Nanoc
+
+  # 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 Nanoc::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<Nanoc::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 [Nanoc::Item, nil] The parent item of this item. This can be
+    #   nil even for non-root items.
+    attr_accessor :parent
+
+    # @return [Array<Nanoc::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 [Nanoc::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 Nanoc::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 Nanoc::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)
+      Nanoc::NotificationCenter.post(:visit_started, self)
+      Nanoc::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
+        @@_Nanoc_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 @@_Nanoc_Helpers_Capturing_included
+          self.class.send(:include, ::Nanoc::Helpers::Capturing)
+          @@_Nanoc_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} 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