nanoc 4.0.0a1 → 4.0.0a2

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

@@ -70,7 +70,7 @@ module Nanoc::Int
 
       # Get rest of params
       @attributes   = attributes.__nanoc_symbolize_keys_recursively
-      @identifier   = Nanoc::Identifier.new(identifier)
+      @identifier   = Nanoc::Identifier.from(identifier)
 
       # Set mtime
       @attributes.merge!(mtime: params[:mtime]) if params[:mtime]

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

@@ -21,7 +21,9 @@ module Nanoc::Int
     DELEGATED_METHODS = (Array.instance_methods + Enumerable.instance_methods).map(&:to_sym) - EXCLUDED_METHODS
     def_delegators :@items, *DELEGATED_METHODS
 
-    def initialize
+    def initialize(config)
+      @config = config
+
       @items = []
     end
 
@@ -33,7 +35,7 @@ module Nanoc::Int
 
     def [](*args)
       if 1 == args.size && args.first.is_a?(String)
-        item_with_identifier(args.first)
+        item_with_identifier(args.first) || item_matching_glob(args.first)
       elsif 1 == args.size && args.first.is_a?(Regexp)
         @items.select { |i| i.identifier.to_s =~ args.first }
       else
@@ -60,6 +62,15 @@ module Nanoc::Int
       end
     end
 
+    def item_matching_glob(glob)
+      if use_globs?
+        pat = Nanoc::Int::Pattern.from(glob)
+        @items.find { |i| pat.match?(i.identifier) }
+      else
+        nil
+      end
+    end
+
     def build_mapping
       @mapping = {}
       @items.each do |item|
@@ -67,5 +78,9 @@ module Nanoc::Int
       end
       @mapping.freeze
     end
+
+    def use_globs?
+      @config[:pattern_syntax] == 'glob'
+    end
   end
 end

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

@@ -29,7 +29,7 @@ module Nanoc::Int
     def initialize(raw_content, attributes, identifier, params = {})
       @raw_content  = raw_content
       @attributes   = attributes.__nanoc_symbolize_keys_recursively
-      @identifier   = Nanoc::Identifier.new(identifier)
+      @identifier   = Nanoc::Identifier.from(identifier)
     end
 
     # Requests the attribute with the given key.

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

@@ -176,6 +176,7 @@ module Nanoc::Int
 
       item_map = {}
       @items.each do |item|
+        next if item.identifier !~ /\/\z/
         item_map[item.identifier.to_s] = item
       end
 
@@ -324,11 +325,11 @@ module Nanoc::Int
       @items_loaded = true
 
       # Get items
-      @items = Nanoc::Int::ItemArray.new
+      @items = Nanoc::Int::ItemArray.new(@config)
       data_sources.each do |ds|
         items_in_ds = ds.items
         items_in_ds.each do |i|
-          i.identifier = Nanoc::Identifier.new(File.join(ds.items_root, i.identifier.to_s))
+          i.identifier = i.identifier.prefix(ds.items_root)
           i.site = self
         end
         @items.concat(items_in_ds)
@@ -346,7 +347,7 @@ module Nanoc::Int
       data_sources.each do |ds|
         layouts_in_ds = ds.layouts
         layouts_in_ds.each do |l|
-          l.identifier = Nanoc::Identifier.new(File.join(ds.layouts_root, l.identifier.to_s))
+          l.identifier = l.identifier.prefix(ds.layouts_root)
         end
         @layouts.concat(layouts_in_ds)
       end

data/lib/nanoc/base/views/config.rb

@@ -2,6 +2,9 @@
 
 module Nanoc
   class ConfigView
+    # @api private
+    NONE = Object.new
+
     # @api private
     def initialize(config)
       @config = config
@@ -12,6 +15,25 @@ module Nanoc
       @config
     end
 
+    # @see Hash#fetch
+    def fetch(key, fallback=NONE, &block)
+      @config.fetch(key) do
+        if !fallback.equal?(NONE)
+          fallback
+        elsif block_given?
+          yield(key)
+        else
+          raise KeyError, "key not found: #{key.inspect}"
+        end
+      end
+    end
+
+    # @see Hash#key?
+    def key?(key)
+      @config.key?(key)
+    end
+
+    # @see Hash#[]
     def [](key)
       @config[key]
     end

data/lib/nanoc/base/views/item.rb

@@ -2,6 +2,9 @@
 
 module Nanoc
   class ItemView
+    # @api private
+    NONE = Object.new
+
     # @api private
     def initialize(item)
       @item = item
@@ -12,39 +15,112 @@ module Nanoc
       @item
     end
 
+    # @see Object#==
     def ==(other)
       identifier == other.identifier
     end
     alias_method :eql?, :==
 
+    # @see Object#hash
     def hash
       self.class.hash ^ identifier.hash
     end
 
+    # @return [Nanoc::Identifier]
     def identifier
       @item.identifier
     end
 
+    # @see Hash#fetch
+    def fetch(key, fallback=NONE, &block)
+      res = @item[key] # necessary for dependency tracking
+
+      if @item.attributes.key?(key)
+        res
+      else
+        if !fallback.equal?(NONE)
+          fallback
+        elsif block_given?
+          yield(key)
+        else
+          raise KeyError, "key not found: #{key.inspect}"
+        end
+      end
+    end
+
+    # @see Hash#key?
+    def key?(key)
+      _res = @item[key] # necessary for dependency tracking
+      @item.attributes.key?(key)
+    end
+
+    # @see Hash#[]
     def [](key)
       @item[key]
     end
 
+    # Returns the compiled content.
+    #
+    # @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 content of the given rep at the given snapshot.
     def compiled_content(params = {})
       @item.compiled_content(params)
     end
 
+    # Returns the item 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.
+    #
+    # @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.
+    #
+    # @option params [Symbol] :snapshot (:last) The snapshot for which the
+    #   path should be returned.
+    #
+    # @return [String] The item’s path.
     def path(params = {})
       @item.path(params)
     end
 
+    # Returns the children of this item. For items with identifiers that have
+    # extensions, returns an empty collection.
+    #
+    # @return [Enumerable<Nanoc::ItemView>]
     def children
       @item.children.map { |i| Nanoc::ItemView.new(i) }
     end
 
+    # Returns the parent of this item, if one exists. For items with identifiers
+    # that have extensions, returns nil.
+    #
+    # @return [Nanoc::ItemView] if the item has a parent
+    #
+    # @return [nil] if the item has no parent
+    def parent
+      Nanoc::ItemView.new(@item.parent)
+    end
+
+    # @return [Boolean] True if the item is binary, false otherwise
     def binary?
       @item.binary?
     end
 
+    # For textual items, returns the raw (source) content of this item; for
+    # binary items, returns `nil`.
+    #
+    # @return [String] if the item is textual
+    #
+    # @return [nil] if the item is binary
     def raw_content
       @item.raw_content
     end

data/lib/nanoc/base/views/item_collection.rb

@@ -19,20 +19,62 @@ module Nanoc
       Nanoc::ItemView
     end
 
+    # Calls the given block once for each item, passing that item as a parameter.
+    #
+    # @yieldparam [Nanoc::ItemView] item
+    #
+    # @yieldreturn [void]
+    #
+    # @return [self]
     def each
       @items.each { |i| yield view_class.new(i) }
+      self
     end
 
+    # @return [Integer]
+    def size
+      @items.size
+    end
+
+    # @overload at(string)
+    #
+    #   Finds the item whose identifier matches the given string.
+    #
+    #   @param [String] string
+    #
+    #   @return [nil] if no item matches the string
+    #
+    #   @return [Nanoc::ItemView] if an item was found
     def at(arg)
       item = @items.at(arg)
       item && view_class.new(item)
     end
 
-    def [](*args)
-      res = @items[*args]
+    # @overload [](string)
+    #
+    #   Finds the item whose identifier matches the given string.
+    #
+    #   If the glob syntax is enabled, the string can be a glob, in which case
+    #   this method finds the first item that matches the given glob.
+    #
+    #   @param [String] string
+    #
+    #   @return [nil] if no item matches the string
+    #
+    #   @return [Nanoc::ItemView] if an item was found
+    #
+    # @overload [](regex)
+    #
+    #   Finds the item whose identifier matches the given regular expression.
+    #
+    #   @param [Regex] regex
+    #
+    #   @return [nil] if no item matches the regex
+    #
+    #   @return [Nanoc::ItemView] if an item was found
+    def [](arg)
+      res = @items[arg]
       case res
-      when Array
-        res.map { |r| view_class.new(r) }
       when nil
         nil
       else

data/lib/nanoc/base/views/item_rep.rb

@@ -12,27 +12,50 @@ module Nanoc
       @item_rep
     end
 
+    # @see Object#==
     def ==(other)
       item.identifier == other.item.identifier && name == other.name
     end
     alias_method :eql?, :==
 
+    # @see Object#hash
     def hash
       self.class.hash ^ item.identifier.hash ^ name.hash
     end
 
+    # @return [Symbol]
     def name
       @item_rep.name
     end
 
+    # Returns the compiled content.
+    #
+    # @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 content at the given snapshot.
     def compiled_content(params = {})
       @item_rep.compiled_content(params)
     end
 
+    # Returns 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.
+    #
+    # @option params [Symbol] :snapshot (:last) The snapshot for which the
+    #   path should be returned.
+    #
+    # @return [String] The item rep’s path.
     def path(params = {})
       @item_rep.path(params)
     end
 
+    # Returns the item that this item rep belongs to.
+    #
+    # @return [Nanoc::ItemView]
     def item
       Nanoc::ItemView.new(@item_rep.item)
     end

data/lib/nanoc/base/views/layout.rb

@@ -12,19 +12,23 @@ module Nanoc
       @layout
     end
 
+    # @see Object#==
     def ==(other)
       identifier == other.identifier
     end
     alias_method :eql?, :==
 
+    # @see Object#hash
     def hash
       self.class.hash ^ identifier.hash
     end
 
+    # @return [Nanoc::Identifier]
     def identifier
       @layout.identifier
     end
 
+    # @see Hash#[]
     def [](key)
       @layout[key]
     end

data/lib/nanoc/base/views/layout_collection.rb

@@ -11,7 +11,7 @@ module Nanoc
 
     # @api private
     def unwrap
-      @item
+      @layouts
     end
 
     # @api private
@@ -19,8 +19,14 @@ module Nanoc
       Nanoc::LayoutView
     end
 
+    # Calls the given block once for each layout, passing that layout as a parameter.
+    #
+    # @yieldparam [Nanoc::LayoutView] layout
+    #
+    # @yieldreturn [void]
     def each
       @layouts.each { |l| yield view_class.new(l) }
+      self
     end
   end
 end

data/lib/nanoc/base/views/mutable_config.rb

@@ -2,6 +2,11 @@
 
 module Nanoc
   class MutableConfigView < Nanoc::ConfigView
+    # Sets the value for the given attribute.
+    #
+    # @param [Symbol] key
+    #
+    # @see Hash#[]=
     def []=(key, value)
       @config[key] = value
     end

data/lib/nanoc/base/views/mutable_item.rb

@@ -2,8 +2,23 @@
 
 module Nanoc
   class MutableItemView < Nanoc::ItemView
+    # Sets the value for the given attribute.
+    #
+    # @param [Symbol] key
+    #
+    # @see Hash#[]=
     def []=(key, value)
       unwrap[key] = value
     end
+
+    # Updates the attributes based on the given hash.
+    #
+    # @param [Hash] hash
+    #
+    # @return [self]
+    def update_attributes(hash)
+      hash.each { |k, v| unwrap[k] = v }
+      self
+    end
   end
 end