nanoc3 3.0.0

data/lib/nanoc3/base/errors.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  module Errors
+
+    # Generic error. Superclass for all nanoc-specific errors.
+    class Generic < ::StandardError
+    end
+
+    # Error that is raised when a site is loaded that uses a data source with
+    # an unknown identifier.
+    class UnknownDataSource < Generic
+      def initialize(data_source_name)
+        super("The data source specified in the site's configuration file, #{data_source_name}, does not exist.")
+      end
+    end
+
+    # Error that is raised during site compilation when an item uses a layout
+    # that is not present in the site.
+    class UnknownLayout < Generic
+      def initialize(layout_identifier)
+        super("The site does not have a layout with identifier '#{layout_identifier}'.")
+      end
+    end
+
+    # Error that is raised during site compilation when an item uses a filter
+    # that is not known.
+    class UnknownFilter < Generic
+      def initialize(filter_name)
+        super("The requested filter, #{filter_name}, does not exist.")
+      end
+    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 CannotDetermineFilter < Generic
+      def initialize(layout_identifier)
+        super("The filter to be used for the '#{layout_identifier}' could not be determined. Make sure the layout does have a filter.")
+      end
+    end
+
+    # Error that is raised when data is requested when the data is not yet
+    # available (possibly due to a missing Nanoc::Site#load_data).
+    class DataNotYetAvailable < Generic
+      def initialize(type, plural)
+        super("#{type} #{plural ? 'are' : 'is'} not available yet. You may be missing a Nanoc::Site#load_data call.")
+      end
+    end
+
+    # Error that is raised during site compilation when an item (directly or
+    # indirectly) includes its own item content, leading to endless recursion.
+    class RecursiveCompilation < Generic
+      def initialize(reps)
+        super("The site cannot be compiled because the following items mutually depend on each other: #{reps.inspect}.")
+      end
+    end
+
+    # Error that is raised when no rules file can be found in the current
+    # working directory.
+    class NoRulesFileFound < Generic
+      def initialize
+        super("This site does not have a rules file, which is required for nanoc sites.")
+      end
+    end
+
+    # Error that is raised when no compilation rule that can be applied to the
+    # current item can be found.
+    class NoMatchingCompilationRuleFound < Generic
+      def initialize(rep)
+        super("No compilation rules were found for the '#{rep.item.identifier}' item (rep '#{rep.name}').")
+      end
+    end
+
+    # Error that is raised when no routing rule that can be applied to the
+    # current item can be found.
+    class NoMatchingRoutingRuleFound < Generic
+      def initialize(rep)
+        super("No routing rules were found for the '#{rep.item.identifier}' item (rep '#{rep.name}').")
+      end
+    end
+
+    # Error that is raised when an rep cannot be compiled because it depends on other representations.
+    class UnmetDependency < Generic
+      attr_reader :rep
+      def initialize(rep)
+        @rep = rep
+        super("The '#{rep.item.identifier}' item (rep '#{rep.name}') cannot currently be compiled yet due to an unmet dependency.")
+      end
+    end
+
+  end
+
+end

data/lib/nanoc3/base/filter.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Nanoc3::Filter is responsible for filtering items. It is
+  # the (abstract) superclass for all textual filters. Subclasses should
+  # override the +run+ method.
+  class Filter < Plugin
+
+    # A hash containing variables that will be made available during
+    # filtering.
+    attr_reader :assigns
+
+    # Creates a new filter with the given assigns.
+    #
+    # +a_assigns+:: A hash containing variables that should be made available
+    #               during filtering.
+    def initialize(a_assigns={})
+      @assigns = a_assigns
+    end
+
+    # Sets the identifiers for this filter.
+    def self.identifiers(*identifiers)
+      Nanoc3::Filter.register(self, *identifiers)
+    end
+
+    # Sets the identifier for this filter.
+    def self.identifier(identifier)
+      Nanoc3::Filter.register(self, identifier)
+    end
+
+    # Registers the given class as a filter with the given identifier.
+    def self.register(class_or_name, *identifiers)
+      Nanoc3::Plugin.register(Nanoc3::Filter, class_or_name, *identifiers)
+    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, params={})
+      raise NotImplementedError.new("Nanoc3::Filter subclasses must implement #run")
+    end
+
+    # Returns the filename associated with the item that is being filtered.
+    # The returned filename is in the format "item <identifier> (rep <name>)".
+    def filename
+      if assigns[:layout]
+        "layout #{assigns[:layout].identifier}"
+      elsif assigns[:item]
+        "item #{assigns[:item].identifier} (rep #{assigns[:item_rep].name})"
+      else
+        '?'
+      end
+    end
+
+  end
+
+end

data/lib/nanoc3/base/item.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Nanoc3::Item is represents all compileable items in a site. It has content
+  # and attributes, as well as an identifier. It can also store the
+  # modification time to speed up compilation.
+  class Item
+
+    # The Nanoc3::Site this item belongs to.
+    attr_accessor :site
+
+    # A hash containing this item's attributes.
+    attr_accessor :attributes
+
+    # This item's identifier.
+    attr_accessor :identifier
+
+    # The time when this item was last modified.
+    attr_reader   :mtime
+
+    # This item's list of item representations.
+    attr_reader   :reps
+
+    # This item's raw, uncompiled content.
+    attr_reader   :raw_content
+
+    # The parent item of this item. This can be nil even for non-root items.
+    attr_accessor :parent
+
+    # The child items of this item.
+    attr_accessor :children
+
+    # A boolean indicating whether or not this item is outdated because of its dependencies are outdated.
+    attr_accessor :dependencies_outdated
+
+    # Creates a new item.
+    #
+    # +raw_content+:: The uncompiled item content.
+    #
+    # +attributes+:: A hash containing this item's attributes.
+    #
+    # +identifier+:: This item's identifier.
+    #
+    # +mtime+:: The time when this item was last modified.
+    def initialize(raw_content, attributes, identifier, mtime=nil)
+      @raw_content  = raw_content
+      @attributes   = attributes.symbolize_keys
+      @identifier   = identifier.cleaned_identifier
+      @mtime        = mtime
+
+      @parent       = nil
+      @children     = []
+
+      @reps         = []
+    end
+
+    # Requests the attribute with the given key.
+    def [](key)
+      Nanoc3::NotificationCenter.post(:visit_started, self)
+      Nanoc3::NotificationCenter.post(:visit_ended,   self)
+
+      @attributes[key]
+    end
+
+    # Sets the attribute with the given key to the given value.
+    def []=(key, value)
+      @attributes[key] = value
+    end
+
+    # True if any reps are outdated; false otherwise.
+    def outdated?
+      @reps.any? { |r| r.outdated? }
+    end
+
+    # Alias for #dependencies_outdated.
+    def dependencies_outdated?
+      self.dependencies_outdated
+    end
+
+    def inspect
+      "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier}>"
+    end
+
+  end
+
+end

data/lib/nanoc3/base/item_rep.rb

@@ -0,0 +1,236 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # A Nanoc3::ItemRep is a single representation (rep) of an item
+  # (Nanoc3::Item). An item can have multiple representations. A representation
+  # has its own output file. A single item can therefore have multiple output
+  # files, each run through a different set of filters with a different
+  # layout.
+  #
+  # An item 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 item
+  # representation); the filtering-related events have two (the item
+  # representation, and a symbol containing the filter class name).
+  class ItemRep
+
+    # The item (Nanoc3::Item) to which this representation belongs.
+    attr_reader   :item
+
+    # This item representation's unique name.
+    attr_reader   :name
+
+    # Indicates whether this rep is forced to be dirty by the user.
+    attr_accessor :force_outdated
+
+    # Indicates whether this rep's output file has changed the last time it
+    # was compiled.
+    attr_accessor :modified
+    alias_method :modified?, :modified
+
+    # Indicates whether this rep's output file was created the last time it
+    # was compiled.
+    attr_accessor :created
+    alias_method :created?, :created
+
+    # Indicates whether this rep has already been compiled.
+    attr_accessor :compiled
+    alias_method :compiled?, :compiled
+
+    # Indicates whether this rep's compiled content has been written during
+    # the current or last compilation session.
+    attr_reader :written
+    alias_method :written?, :written
+
+    # The item rep's path, as used when being linked to. It starts with a
+    # slash and it is relative to the output directory. It does not include
+    # the path to the output directory. It will not include the filename if
+    # the filename is an index filename.
+    attr_accessor :path
+
+    # The item rep's raw path. It is relative to the current working directory
+    # and includes the path to the output directory. It also includes the
+    # filename, even if it is an index filename.
+    attr_accessor :raw_path
+
+    # Creates a new item representation for the given item.
+    #
+    # +item+:: The item (Nanoc3::Item) to which the new representation will
+    #          belong.
+    #
+    # +name+:: The unique name for the new item representation.
+    def initialize(item, name)
+      # Set primary attributes
+      @item = item
+      @name = name
+
+      # Initialize content
+      @content = {
+        :raw  => @item.raw_content,
+        :last => @item.raw_content,
+        :pre  => @item.raw_content
+      }
+
+      # Reset flags
+      @compiled       = false
+      @modified       = false
+      @created        = false
+      @written        = false
+      @force_outdated = false
+    end
+
+    # Returns true if this item rep's output file is outdated and must be
+    # regenerated, false otherwise.
+    def outdated?
+      # Outdated if we don't know
+      return true if @item.mtime.nil?
+
+      # Outdated if the dependency tracker says so
+      return true if @force_outdated
+
+      # Outdated if compiled file doesn't exist
+      return true if self.raw_path.nil?
+      return true if !File.file?(self.raw_path)
+
+      # Get compiled mtime
+      compiled_mtime = File.stat(self.raw_path).mtime
+
+      # Outdated if file too old
+      return true if @item.mtime > compiled_mtime
+
+      # Outdated if layouts outdated
+      return true if @item.site.layouts.any? do |l|
+        l.mtime.nil? || l.mtime > compiled_mtime
+      end
+
+      # Outdated if code outdated
+      return true if @item.site.code_snippets.any? do |cs|
+        cs.mtime.nil? || cs.mtime > compiled_mtime
+      end
+
+      # Outdated if config outdated
+      return true if @item.site.config_mtime.nil?
+      return true if @item.site.config_mtime > compiled_mtime
+
+      # Outdated if rules outdated
+      return true if @item.site.rules_mtime.nil?
+      return true if @item.site.rules_mtime > compiled_mtime
+
+      return false
+    end
+
+    # Returns the assignments that should be available when compiling the content.
+    def assigns
+      {
+        :content    => @content[:last],
+        :item       => self.item,
+        :item_rep   => self,
+        :items      => self.item.site.items,
+        :layouts    => self.item.site.layouts,
+        :config     => self.item.site.config,
+        :site       => self.item.site
+      }
+    end
+
+    # Returns the item representation content at the given snapshot.
+    #
+    # +snapshot+:: The snapshot from which the content should be fetched. To
+    #              get the raw, uncompiled content, use +:raw+.
+    def content_at_snapshot(snapshot=:pre)
+      Nanoc3::NotificationCenter.post(:visit_started, self.item)
+      Nanoc3::NotificationCenter.post(:visit_ended,   self.item)
+
+      puts "*** Attempting to fetch content for #{self.inspect}" if $DEBUG
+
+      raise Nanoc3::Errors::UnmetDependency.new(self) unless compiled?
+
+      @content[snapshot]
+    end
+
+    # Runs the item content through the given filter with the given arguments.
+    def filter(filter_name, filter_args={})
+      # Create filter
+      klass = Nanoc3::Filter.named(filter_name)
+      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
+      filter = klass.new(assigns)
+
+      # Run filter
+      Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name)
+      @content[:last] = filter.run(@content[:last], filter_args)
+      Nanoc3::NotificationCenter.post(:filtering_ended, self, filter_name)
+
+      # Create snapshot
+      snapshot(@content[:post] ? :post : :pre)
+    end
+
+    # Lays out the item using the given layout.
+    def layout(layout_identifier)
+      # Get layout
+      layout ||= @item.site.layouts.find { |l| l.identifier == layout_identifier.cleaned_identifier }
+      raise Nanoc3::Errors::UnknownLayout.new(layout_identifier) if layout.nil?
+
+      # Get filter
+      filter_name, filter_args  = @item.site.compiler.filter_for_layout(layout)
+      raise Nanoc3::Errors::CannotDetermineFilter.new(layout_identifier) if filter_name.nil?
+
+      # Get filter class
+      filter_class = Nanoc3::Filter.named(filter_name)
+      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
+
+      # Create filter
+      filter = filter_class.new(assigns.merge({ :layout => layout }))
+
+      # Create "pre" snapshot
+      snapshot(:pre)
+
+      # Layout
+      @item.site.compiler.stack.push(layout)
+      Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name)
+      @content[:last] = filter.run(layout.raw_content, filter_args)
+      Nanoc3::NotificationCenter.post(:filtering_ended,   self, filter_name)
+      @item.site.compiler.stack.pop
+
+      # Create "post" snapshot
+      snapshot(:post)
+    end
+
+    # Creates a snapshot of the current compiled item content.
+    def snapshot(snapshot_name)
+      @content[snapshot_name] = @content[:last]
+    end
+
+    # Writes the item rep's compiled content to the rep's output file.
+    def write
+      # Create parent directory
+      FileUtils.mkdir_p(File.dirname(self.raw_path))
+
+      # Check if file will be created
+      @created = !File.file?(self.raw_path)
+
+      # Remember old content
+      if File.file?(self.raw_path)
+        old_content = File.read(self.raw_path)
+      end
+
+      # Write
+      File.open(self.raw_path, 'w') { |io| io.write(@content[:last]) }
+      @written = true
+
+      # Check if file was modified
+      @modified = File.read(self.raw_path) != old_content
+    end
+
+    def inspect
+      "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} item.identifier=#{self.item.identifier}>"
+    end
+
+  end
+
+end

data/lib/nanoc3/base/layout.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # A Nanoc3::Layout represents a layout in a nanoc site. It has content,
+  # attributes (for determining which filter to use for laying out an item),
+  # an identifier (because layouts are organised hierarchically), and a
+  # modification time (to speed up compilation).
+  class Layout
+
+    # The Nanoc3::Site this layout belongs to.
+    attr_accessor :site
+
+    # The raw content of this layout.
+    attr_reader :raw_content
+
+    # A hash containing this layout's attributes.
+    attr_reader :attributes
+
+    # This layout's identifier, starting and ending with a slash.
+    attr_accessor :identifier
+
+    # 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.
+    #
+    # +identifier+:: This layout's identifier.
+    #
+    # +mtime+:: The time when this layout was last modified.
+    def initialize(raw_content, attributes, identifier, mtime=nil)
+      @raw_content  = raw_content
+      @attributes   = attributes.symbolize_keys
+      @identifier   = identifier.cleaned_identifier
+      @mtime        = mtime
+    end
+
+    # Requests the attribute with the given key.
+    def [](key)
+      @attributes[key]
+    end
+
+    def inspect
+      "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier}>"
+    end
+
+  end
+
+end

data/lib/nanoc3/base/notification_center.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Nanoc3::NotificationCenter provides a way to send notifications between
+  # objects. It allows blocks associated with a certain notification name to
+  # be registered; these blocks will be called when the notification with the
+  # given name is posted.
+  #
+  # It is a slightly different implementation of the Observer pattern; the
+  # table of subscribers is not stored in the observable object itself, but in
+  # the notification center.
+  class NotificationCenter
+
+    class << self
+
+      # Adds the given block to the list of blocks that should be called when
+      # the notification with the given name is received.
+      #
+      # +name+:: The name of the notification that will be posted.
+      #
+      # +id+:: An identifier for the block. This is only used to be able to
+      #        remove the block (using the remove method) later. Defaults to
+      #        nil.
+      def on(name, id=nil, &block)
+        initialize_if_necessary(name)
+
+        # Add observer
+        @notifications[name] << { :id => id, :block => block }
+      end
+
+      # Posts a notification with the given name. All arguments wil be passed
+      # to the blocks handling the notification.
+      def post(name, *args)
+        initialize_if_necessary(name)
+
+        # Notify all observers
+        @notifications[name].each do |observer|
+          observer[:block].call(*args)
+        end
+      end
+
+      # Removes the block with the given identifier from the list of blocks
+      # that should be called when the notification with the given name is
+      # posted.
+      #
+      # +name+:: The name of the notification that will be posted.
+      #
+      # +id+:: The identifier of the block that should be removed.
+      def remove(name, id)
+        initialize_if_necessary(name)
+
+        # Remove relevant observers
+        @notifications[name].reject! { |i| i[:id] == id }
+      end
+
+    private
+
+      def initialize_if_necessary(name)
+        @notifications ||= {}       # name => observers dictionary
+        @notifications[name] ||= [] # list of observers
+      end
+
+    end
+
+  end
+
+end

data/lib/nanoc3/base/plugin.rb

@@ -0,0 +1,88 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # Nanoc3::Plugin is the superclass for all plugins, such as filters
+  # (Nanoc3::Filter), data sources (Nanoc3::DataSource) and VCSes
+  # (Nanoc3::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
+
+      # Registers the given class as a plugin.
+      #
+      # +superclass+:: The superclass of the plugin. For example:
+      #                Nanoc::Filter, Nanoc::VCS.
+      #
+      # +class_or_name+:: The class to register. This can be a string, in
+      #                   which case it will be automatically converted to a
+      #                   proper class at lookup. For example:
+      #                   'Nanoc::Filters::ERB', Nanoc::Filters::Haml.
+      #
+      # +identifiers+:: One or more symbols identifying the class. For
+      #                 example: :haml, :erb.
+      def register(superclass, class_or_name, *identifiers)
+        MAP[superclass] ||= {}
+
+        identifiers.each do |identifier|
+          MAP[superclass][identifier.to_sym] = class_or_name
+        end
+      end
+
+      # Returns the the plugin with the given name. Only subclasses of this
+      # class will be searched. For example, calling this method on
+      # Nanoc3::Filter will cause only Nanoc3::Filter subclasses to be searched.
+      def named(name)
+        # Initialize
+        MAP[self] ||= {}
+
+        # Lookup
+        class_or_name = MAP[self][name.to_sym]
+
+        # Get class
+        if class_or_name.is_a?(String)
+          class_or_name.scan(/\w+/).inject(self) { |memo, part| memo.const_get(part) }
+        else
+          class_or_name
+        end
+      end
+
+      # Returns a list of all plugins in the following format:
+      #
+      #   { :class => ..., :superclass => ..., :identifiers => ... }
+      def all
+        plugins = []
+        MAP.each_pair do |superclass, submap|
+          submap.each_pair do |identifier, klass|
+            # Find existing plugin
+            existing_plugin = plugins.find do |p|
+              p[:class] == klass && p[:superclass] == superclass
+            end
+
+            if existing_plugin
+              # Add identifier to existing plugin
+              existing_plugin[:identifiers] << identifier
+              existing_plugin[:identifiers] = existing_plugin[:identifiers].sort_by { |s| s.to_s }
+            else
+              # Create new plugin
+              plugins << {
+                :class       => klass,
+                :superclass  => superclass,
+                :identifiers => [ identifier ]
+              }
+            end
+          end
+        end
+
+        plugins
+      end
+
+    end
+
+  end
+
+end