nanoc3 3.2.0a1 → 3.2.0a2

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

@@ -0,0 +1,314 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # The in-memory representation of a nanoc site. It holds references to the
+  # following site data:
+  #
+  # * {#items}         — the list of items         ({Nanoc3::Item})
+  # * {#layouts}       — the list of layouts       ({Nanoc3::Layout})
+  # * {#code_snippets} — the list of code snippets ({Nanoc3::CodeSnippet})
+  # * {#data_sources}  — the list of data sources  ({Nanoc3::DataSource})
+  #
+  # In addition, each site has a {#config} hash which stores the site
+  # configuration.
+  #
+  # The physical representation of a {Nanoc3::Site} is usually a directory
+  # that contains a configuration file, site data, a rakefile, a rules file,
+  # etc. The way site data is stored depends on the data source.
+  class Site
+
+    # The default configuration for a data source. A data source's
+    # configuration overrides these options.
+    DEFAULT_DATA_SOURCE_CONFIG = {
+      :type         => 'filesystem_unified',
+      :items_root   => '/',
+      :layouts_root => '/',
+      :config       => {}
+    }
+
+    # The default configuration for a site. A site's configuration overrides
+    # these options: when a {Nanoc3::Site} is created with a configuration
+    # that lacks some options, the default value will be taken from
+    # `DEFAULT_CONFIG`.
+    DEFAULT_CONFIG = {
+      :text_extensions    => %w( css erb haml htm html js less markdown md php rb sass scss txt xhtml xml ),
+      :output_dir         => 'output',
+      :data_sources       => [ {} ],
+      :index_filenames    => [ 'index.html' ],
+      :enable_output_diff => false
+    }
+
+    # Creates a site object for the site specified by the given
+    # `dir_or_config_hash` argument.
+    #
+    # @param [Hash, String] dir_or_config_hash If a string, contains the path
+    #   to the site directory; if a hash, contains the site configuration.
+    def initialize(dir_or_config_hash)
+      build_config(dir_or_config_hash)
+    end
+
+    # Compiles the site.
+    #
+    # @return [void]
+    def compile
+      compiler.run
+    end
+
+    # Returns the compiler for this site. Will create a new compiler if none
+    # exists yet.
+    #
+    # @return [Nanoc3::Compiler] The compiler for this site
+    def compiler
+      @compiler ||= Compiler.new(self)
+    end
+
+    # Returns the data sources for this site. Will create a new data source if
+    # none exists yet.
+    #
+    # @return [Array<Nanoc3::DataSource>] The list of data sources for this
+    #   site
+    #
+    # @raise [Nanoc3::Errors::UnknownDataSource] if the site configuration
+    #   specifies an unknown data source
+    def data_sources
+      load_code_snippets
+
+      @data_sources ||= begin
+        @config[:data_sources].map do |data_source_hash|
+          # Get data source class
+          data_source_class = Nanoc3::DataSource.named(data_source_hash[:type])
+          raise Nanoc3::Errors::UnknownDataSource.new(data_source_hash[:type]) if data_source_class.nil?
+
+          # Warn about deprecated data sources
+          # TODO [in nanoc 4.0] remove me
+          case data_source_hash[:type]
+            when 'filesystem'
+              warn "Warning: the 'filesystem' data source has been renamed to 'filesystem_verbose'. Using 'filesystem' will work in nanoc 3.1.x, but it will likely not work anymore in a future release of nanoc. Please update your data source configuration and replace 'filesystem' with 'filesystem_verbose'."
+            when 'filesystem_combined', 'filesystem_compact'
+              warn "Warning: the 'filesystem_combined' and 'filesystem_compact' data source has been merged into the new 'filesystem_unified' data source. Using 'filesystem_combined' and 'filesystem_compact' will work in nanoc 3.1.x, but it will likely not work anymore in a future release of nanoc. Please update your data source configuration and replace 'filesystem_combined' and 'filesystem_compact with 'filesystem_unified'."
+          end
+
+          # Create data source
+          data_source_class.new(
+            self,
+            data_source_hash[:items_root],
+            data_source_hash[:layouts_root],
+            data_source_hash[:config] || {}
+          )
+        end
+      end
+    end
+
+    # Returns this site’s code snippets.
+    #
+    # @return [Array<Nanoc3::CodeSnippet>] The list of code snippets in this
+    #   site
+    def code_snippets
+      load
+      @code_snippets
+    end
+
+    # Returns this site’s items.
+    #
+    # @return [Array<Nanoc3::Item>] The list of items in this site
+    def items
+      load
+      @items
+    end
+
+    # Returns this site’s layouts.
+    #
+    # @return [Array<Nanoc3::Layouts>] The list of layout in this site
+    def layouts
+      load
+      @layouts
+    end
+
+    # Returns the site configuration. It has the following keys:
+    #
+    # * `text_extensions` (`Array<String>`) - A list of file extensions that
+    #   will cause nanoc to threat the file as textual instead of binary. When
+    #   the data source finds a content file with an extension that is
+    #   included in this list, it will be marked as textual.
+    #
+    # * `output_dir` (`String`) - The directory to which compiled items will
+    #   be written. This path is relative to the current working directory,
+    #   but can also be an absolute path.
+    #
+    # * `data_sources` (`Array<Hash>`) - A list of data sources for this site.
+    #   See below for documentation on the structure of this list. By default,
+    #   there is only one data source of the filesystem  type mounted at `/`.
+    #
+    # * `index_filenames` (`Array<String>`) - A list of filenames that will be
+    #   stripped off full item paths to create cleaner URLs. For example,
+    #   `/about/` will be used instead of `/about/index.html`). The default
+    #   value should be okay in most cases.
+    #
+    # * `enable_output_diff` (`Boolean`) - True when diffs should be generated
+    #   for the compiled content of this site; false otherwise.
+    #
+    # The list of data sources consists of hashes with the following keys:
+    #
+    # * `:type` (`String`) - The type of data source, i.e. its identifier.
+    #
+    # * `:items_root` (`String`) - The prefix that should be given to all
+    #   items returned by the {#items} method (comparable to mount points
+    #   for filesystems in Unix-ish OSes).
+    #
+    # * `:layouts_root` (`String`) - The prefix that should be given to all
+    #   layouts returned by the {#layouts} method (comparable to mount
+    #   points for filesystems in Unix-ish OSes).
+    #
+    # * `:config` (`Hash`) - A hash containing the configuration for this data
+    #   source. nanoc itself does not use this hash. This is especially
+    #   useful for online data sources; for example, a Twitter data source
+    #   would need the username of the account from which to fetch tweets.
+    #
+    # @return [Hash] The site configuration
+    def config
+      # Add reference to config if necessary
+      if !@config.respond_to?(:reference)
+        def @config.reference
+          :config
+        end
+      end
+
+      # Add data to config if necessary
+      if !@config.respond_to?(:data)
+        def @config.data
+          self.inspect
+        end
+      end
+
+      @config
+    end
+
+    # Fills each item's parent reference and children array with the
+    # appropriate items. It is probably not necessary to call this method
+    # manually; it will be called when appropriate.
+    #
+    # @return [void]
+    def setup_child_parent_links
+      # Clear all links
+      @items.each do |item|
+        item.parent = nil
+        item.children = []
+      end
+
+      @items.each do |item|
+        # Get parent
+        parent_identifier = item.identifier.sub(/[^\/]+\/$/, '')
+        parent = @items.find { |p| p.identifier == parent_identifier }
+        next if parent.nil? or item.identifier == '/'
+
+        # Link
+        item.parent = parent
+        parent.children << item
+      end
+    end
+
+    # TODO document
+    #
+    # @api private
+    def objects
+      # FIXME remove reference to rules
+      items + layouts + code_snippets + [ config, compiler.rules_with_reference ]
+    end
+
+    # @deprecated It is no longer necessary to explicitly load site data. It
+    #   is safe to remove all {#load_data} calls.
+    def load_data(force=false)
+      warn 'It is no longer necessary to call Nanoc3::Site#load_data. This method no longer has any effect. All calls to this method can be safely removed.'
+    end
+
+  private
+
+    # Loads the site data. It is not necessary to call this method explicitly;
+    # it will be called when it is necessary.
+    def load
+      return if @data_loaded
+      @data_loaded = true
+
+      # Load all data
+      load_code_snippets
+      data_sources.each { |ds| ds.use }
+      load_items
+      load_layouts
+      data_sources.each { |ds| ds.unuse }
+      setup_child_parent_links
+
+      # Load compiler too
+      # FIXME this should not be necessary
+      compiler.load
+    end
+
+    # Loads this site’s code and executes it.
+    def load_code_snippets
+      @code_snippets_loaded ||= false
+      return if @code_snippets_loaded
+      @code_snippets_loaded = true
+
+      # Get code snippets
+      @code_snippets = Dir['lib/**/*.rb'].sort.map do |filename|
+        Nanoc3::CodeSnippet.new(
+          File.read(filename),
+          filename
+        )
+      end
+
+      # Execute code snippets
+      @code_snippets.each { |cs| cs.load }
+    end
+
+    # Loads this site’s items, sets up item child-parent relationships and
+    # builds each item's list of item representations.
+    def load_items
+      @items_loaded ||= false
+      return if @items_loaded
+      @items_loaded = true
+
+      # Get items
+      @items = []
+      data_sources.each do |ds|
+        items_in_ds = ds.items
+        items_in_ds.each { |i| i.identifier = File.join(ds.items_root, i.identifier) }
+        @items.concat(items_in_ds)
+      end
+    end
+
+    # Loads this site’s layouts.
+    def load_layouts
+      @layouts_loaded ||= false
+      return if @layouts_loaded
+      @layouts_loaded = true
+
+      # Get layouts
+      @layouts = []
+      data_sources.each do |ds|
+        layouts_in_ds = ds.layouts
+        layouts_in_ds.each { |i| i.identifier = File.join(ds.layouts_root, i.identifier) }
+        @layouts.concat(layouts_in_ds)
+      end
+    end
+
+    # Builds the configuration hash based on the given argument. Also see
+    # {#initialize} for details.
+    def build_config(dir_or_config_hash)
+      if dir_or_config_hash.is_a? String
+        # Read config from config.yaml in given dir
+        config_path = File.join(dir_or_config_hash, 'config.yaml')
+        @config = DEFAULT_CONFIG.merge(YAML.load_file(config_path).symbolize_keys)
+        @config[:data_sources].map! { |ds| ds.symbolize_keys }
+      else
+        # Use passed config hash
+        @config = DEFAULT_CONFIG.merge(dir_or_config_hash)
+      end
+
+      # Merge data sources with default data source config
+      @config[:data_sources].map! { |ds| DEFAULT_DATA_SOURCE_CONFIG.merge(ds) }
+    end
+
+  end
+
+end

data/lib/nanoc3/base/store.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+
+module Nanoc3
+
+  # An abstract superclass for classes that need to store data to the
+  # filesystem, such as checksums, cached compiled content and dependency
+  # graphs.
+  #
+  # @abstract Subclasses must implement {#data} and {#data=}, and may
+  #   implement {#no_data_found} and {#version_mismatch_detected}.
+  #
+  # @api private
+  class Store
+
+    # @return [String] The name of the file where data will be loaded from and
+    #   stored to.
+    attr_reader :filename
+
+    # @return [Numeric] The version number corresponding to the file format
+    #   the data is in. When the file format changes, the version number
+    #   should be incremented.
+    attr_reader :version
+
+    # Creates a new store for the given filename.
+    #
+    # @param [String] filename The name of the file where data will be loaded
+    #   from and stored to.
+    #
+    # @param [Numeric] version The version number corresponding to the file
+    #   format the data is in. When the file format changes, the version
+    #   number should be incremented.
+    def initialize(filename, version)
+      @filename = filename
+      @version  = version
+    end
+
+    # @group Loading and storing data
+
+    # @return The data that should be written to the disk
+    #
+    # @abstract This method must be implemented by the subclass.
+    def data
+      raise NotImplementedError.new("Nanoc3::Store subclasses must implement #data and #data=")
+    end
+
+    # @param new_data The data that has been loaded from the disk
+    #
+    # @abstract This method must be implemented by the subclass.
+    #
+    # @return [void]
+    def data=(new_data)
+      raise NotImplementedError.new("Nanoc3::Store subclasses must implement #data and #data=")
+    end
+
+    # Loads the data from the filesystem into memory. This method will set the
+    #   loaded data using the {#data=} method.
+    #
+    # @return [void]
+    def load
+      # Don’t load twice
+      if @loaded
+        return
+      end
+
+      # Check file existance
+      if !File.file?(self.filename)
+        no_data_found
+        @loaded = true
+        return
+      end
+
+      pstore.transaction do
+        # Check version
+        if pstore[:version] != self.version
+          version_mismatch_detected
+          @loaded = true
+          return
+        end
+
+        # Load
+        self.data = pstore[:data]
+        @loaded = true
+      end
+    end
+
+    # Stores the data contained in memory to the filesystem. This method will
+    #   use the {#data} method to fetch the data that should be written.
+    #
+    # @return [void]
+    def store
+      FileUtils.mkdir_p(File.dirname(self.filename))
+
+      pstore.transaction do
+        pstore[:data]    = self.data
+        pstore[:version] = self.version
+      end
+    end
+
+    # @group Callback methods
+
+    # Callback method that is called when no data file was found. By default,
+    # this implementation does nothing, but it should probably be overridden
+    # by the subclass.
+    #
+    # @return [void]
+    def no_data_found
+    end
+
+    # Callback method that is called when a version mismatch is detected. By
+    # default, this implementation does nothing, but it should probably be
+    # overridden by the subclass.
+    #
+    # @return [void]
+    def version_mismatch_detected
+    end
+
+  private
+
+    def pstore
+      require 'pstore'
+      @pstore ||= PStore.new(self.filename)
+    end
+
+  end
+
+end

data/lib/nanoc3/base.rb

@@ -5,26 +5,37 @@ module Nanoc3
   require 'nanoc3/base/core_ext'
   require 'nanoc3/base/ordered_hash'
 
-  autoload 'Checksummer',          'nanoc3/base/checksummer'
-  autoload 'CodeSnippet',          'nanoc3/base/code_snippet'
-  autoload 'CompiledContentCache', 'nanoc3/base/compiled_content_cache'
-  autoload 'Compiler',             'nanoc3/base/compiler'
-  autoload 'CompilerDSL',          'nanoc3/base/compiler_dsl'
-  autoload 'Config',               'nanoc3/base/config'
+  # Load helper classes
   autoload 'Context',              'nanoc3/base/context'
-  autoload 'DataSource',           'nanoc3/base/data_source'
-  autoload 'DependencyTracker',    'nanoc3/base/dependency_tracker'
   autoload 'DirectedGraph',        'nanoc3/base/directed_graph'
   autoload 'Errors',               'nanoc3/base/errors'
-  autoload 'Filter',               'nanoc3/base/filter'
-  autoload 'Item',                 'nanoc3/base/item'
-  autoload 'ItemRep',              'nanoc3/base/item_rep'
-  autoload 'Layout',               'nanoc3/base/layout'
   autoload 'NotificationCenter',   'nanoc3/base/notification_center'
   autoload 'PluginRegistry',       'nanoc3/base/plugin_registry'
-  autoload 'Rule',                 'nanoc3/base/rule'
-  autoload 'RuleContext',          'nanoc3/base/rule_context'
-  autoload 'Site',                 'nanoc3/base/site'
+  autoload 'Store',                'nanoc3/base/store'
+
+  # Load source data classes
+  autoload 'CodeSnippet',          'nanoc3/base/source_data/code_snippet'
+  autoload 'DataSource',           'nanoc3/base/source_data/data_source'
+  autoload 'Item',                 'nanoc3/base/source_data/item'
+  autoload 'Layout',               'nanoc3/base/source_data/layout'
+  autoload 'Site',                 'nanoc3/base/source_data/site'
+
+  # Load result data classes
+  autoload 'ItemRep',              'nanoc3/base/result_data/item_rep'
+
+  # Load compilation classes
+  autoload 'Checksummer',          'nanoc3/base/compilation/checksummer'
+  autoload 'ChecksumStore',        'nanoc3/base/compilation/checksum_store'
+  autoload 'CompiledContentCache', 'nanoc3/base/compilation/compiled_content_cache'
+  autoload 'Compiler',             'nanoc3/base/compilation/compiler'
+  autoload 'CompilerDSL',          'nanoc3/base/compilation/compiler_dsl'
+  autoload 'DependencyTracker',    'nanoc3/base/compilation/dependency_tracker'
+  autoload 'Filter',               'nanoc3/base/compilation/filter'
+  autoload 'ItemRepProxy',         'nanoc3/base/compilation/item_rep_proxy'
+  autoload 'OutdatednessChecker',  'nanoc3/base/compilation/outdatedness_checker'
+  autoload 'OutdatednessReasons',  'nanoc3/base/compilation/outdatedness_reasons'
+  autoload 'Rule',                 'nanoc3/base/compilation/rule'
+  autoload 'RuleContext',          'nanoc3/base/compilation/rule_context'
 
   # Deprecated; use PluginRepository instead
   # TODO [in nanoc 4.0] remove me

data/lib/nanoc3/cli/base.rb

@@ -5,7 +5,7 @@ module Nanoc3::CLI
   class Base < Cri::Base
 
     # A hash that contains the name of the gem for a given required file. If a
-    # {#require} fails, the gem name is looked up in this hash.
+    # `#require` fails, the gem name is looked up in this hash.
     GEM_NAMES = {
       'adsf'           => 'adsf',
       'bluecloth'      => 'bluecloth',
@@ -13,6 +13,7 @@ module Nanoc3::CLI
       'coderay'        => 'coderay',
       'cri'            => 'cri',
       'erubis'         => 'erubis',
+      'escape'         => 'escape',
       'fssm'           => 'fssm',
       'haml'           => 'haml',
       'json'           => 'json',