nanoc3 3.1.0a2 → 3.1.0a3

data/lib/nanoc3/base/item.rb

@@ -22,33 +22,71 @@ module Nanoc3
     # @return [Array<Nanoc3::ItemRep>] This item’s list of item reps
     attr_reader   :reps
 
-    # @return [String] This item's raw, uncompiled content
+    # @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.
+    # nil even for non-root items.
     attr_accessor :parent
 
     # @return [Array<Nanoc3::Item>] The child items of this item
     attr_accessor :children
 
     # @return [Boolean] Whether or not this item is outdated because of its
-    #   dependencies are outdated
+    # dependencies are outdated
     attr_accessor :outdated_due_to_dependencies
     alias_method :outdated_due_to_dependencies?, :outdated_due_to_dependencies
 
-    # @param [String] raw_content The uncompiled item content.
+    # Creates a new item with the given content or filename, attributes and
+    # identifier.
+    #
+    # Note that the API in 3.1 has changed a bit since 3.0; the API remains
+    # backwards compatible, however. Passing the modification time as the 4th
+    # parameter is deprecated; pass it as the `:mtime` method option instead.
+    #
+    # @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 [String, nil] mtime The time when this item was last modified.
-    def initialize(raw_content, attributes, identifier, mtime=nil)
-      @raw_content  = raw_content
+    # @param [Time, Hash, nil] params_or_mtime Extra parameters for the item,
+    # or the time when this item was last modified (deprecated).
+    #
+    # @option params_or_mtime [Time, nil] :mtime (nil) The time when this item
+    # was last modified
+    #
+    # @option params_or_mtime [Symbol, nil] :binary (true) Whether or not this
+    # item is binary
+    def initialize(raw_content_or_raw_filename, attributes, identifier, params_or_mtime=nil)
+      # Get params and mtime
+      # TODO [in nanoc 4.0] clean this up
+      if params_or_mtime.nil? || params_or_mtime.is_a?(Time)
+        params = {}
+        @mtime = params_or_mtime
+      elsif params_or_mtime.is_a?(Hash)
+        params = params_or_mtime
+        @mtime = params[:mtime]
+      end
+
+      # Get type and raw content or raw filename
+      @is_binary = params.has_key?(:binary) ? params[:binary] : true
+      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
-      @mtime        = mtime
 
       @parent       = nil
       @children     = []
@@ -61,7 +99,7 @@ module Nanoc3
     # @param [Symbol] rep_name The name of the representation to return
     #
     # @return [Nanoc3::ItemRep] The representation with the given name
-    def rep(rep_name)
+    def rep_named(rep_name)
       @reps.find { |r| r.name == rep_name }
     end
 
@@ -70,17 +108,17 @@ module Nanoc3
     # 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.
+    # from which the compiled content should be fetched. By default, the
+    # compiled content will be fetched from the default representation.
     #
     # @option params [String] :snapshot (:last) The name of the snapshot from
-    #   which to fetch the compiled content. By default, the fully compiled
-    #   content will be fetched, with all filters and layouts applied--not the
-    #   pre-layout content.
+    # which to fetch the compiled content. By default, the fully compiled
+    # content will be fetched, with all filters and layouts applied--not the
+    # pre-layout content.
     #
     # @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)
+    # rep if no rep is specified) at the given snapshot (or the default
+    # snapshot if no snapshot is specified)
     def compiled_content(params={})
       # Get rep
       rep_name = params[:rep] || :default
@@ -98,11 +136,11 @@ module Nanoc3
     # 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.
+    # 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)
+    # rep is specified)
     def path(params={})
       rep_name = params[:rep] || :default
 
@@ -138,6 +176,11 @@ module Nanoc3
       @attributes[key] = value
     end
 
+    # @return [Boolean] True if the item is binary; false if it is not
+    def binary?
+      !!@is_binary
+    end
+
     # Determines whether this item (or rather, its reps) is outdated and
     # should be recompiled (or rather, its reps should be recompiled).
     #
@@ -147,7 +190,7 @@ module Nanoc3
     end
 
     def inspect
-      "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier}>"
+      "<#{self.class}:0x#{self.object_id.to_s(16)} identifier=#{self.identifier} binary?=#{self.binary?}>"
     end
 
   end

data/lib/nanoc3/base/item_rep.rb

@@ -27,46 +27,45 @@ module Nanoc3
     attr_reader   :name
 
     # @return [Boolean] true if this rep is forced to be dirty (e.g. because
-    #   of the `--force` commandline option); false otherwise
+    # of the `--force` commandline option); false otherwise
     attr_accessor :force_outdated
 
     # @return [Boolean] true if this rep’s output file has changed since the
-    #   last time it was compiled; false otherwise
+    # last time it was compiled; false otherwise
     attr_accessor :modified
     alias_method :modified?, :modified
 
     # @return [Boolean] true if this rep’s output file was created during the
-    #   current or last compilation session; false otherwise
+    # current or last compilation session; false otherwise
     attr_accessor :created
     alias_method :created?, :created
 
-    # @return [Boolean] true if this representation has already been
-    #   compiled during the current or last compilation session; false
-    #   otherwise
+    # @return [Boolean] true if this representation has already been compiled
+    # during the current or last compilation session; false otherwise
     attr_accessor :compiled
     alias_method :compiled?, :compiled
 
     # @return [Boolean] true if this representation’s compiled content has
-    #   been written during the current or last compilation session; false
-    #   otherwise
+    # been written during the current or last compilation session; false
+    # otherwise
     attr_reader :written
     alias_method :written?, :written
 
     # @return [String] 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.
+    # 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
 
     # @return [String] 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.
+    # 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.
     #
     # @param [Nanoc3::Item] item The item to which the new representation will
-    #   belong.
+    # belong.
     #
     # @param [Symbol] name The unique name for the new item representation.
     def initialize(item, name)
@@ -74,12 +73,19 @@ module Nanoc3
       @item = item
       @name = name
 
-      # Initialize content
-      @content = {
-        :raw  => @item.raw_content,
-        :last => @item.raw_content,
-        :pre  => @item.raw_content
-      }
+      # Initialize content and filenames
+      if @item.binary?
+        @filenames = {
+          :raw  => @item.raw_filename,
+          :last => @item.raw_filename
+        }
+      else
+        @content = {
+          :raw  => @item.raw_content,
+          :last => @item.raw_content,
+          :pre  => @item.raw_content
+        }
+      end
       @old_content = nil
 
       # Reset flags
@@ -91,7 +97,7 @@ module Nanoc3
     end
 
     # @return [Boolean] true if this item rep's output file is outdated and
-    #   must be regenerated, false otherwise
+    # must be regenerated, false otherwise
     def outdated?
       # Outdated if we don't know
       return true if @item.mtime.nil?
@@ -131,26 +137,40 @@ module Nanoc3
     end
 
     # @return [Hash] The assignments that should be available when compiling
-    #   the content.
+    # the content.
     def assigns
-      {
-        :content    => @content[:last],
+      if item.binary?
+        content_or_filename_assigns = { :filename => @filenames[:last] }
+      else
+        content_or_filename_assigns = { :content => @content[:last] }
+      end
+
+      content_or_filename_assigns.merge({
         :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 compiled content from a given snapshot.
     #
-    # @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).
+    # @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 at the given snapshot (or the
+    # default snapshot if no snapshot is specified)
     def compiled_content(params={})
+      # Check whether content can be fetched
+      # TODO get proper exception
+      if @item.binary?
+        raise RuntimeError, "attempted to fetch compiled content from a binary item"
+      end
+
       # Notify
       Nanoc3::NotificationCenter.post(:visit_started, self.item)
       Nanoc3::NotificationCenter.post(:visit_ended,   self.item)
@@ -186,10 +206,10 @@ module Nanoc3
     # (see {Nanoc3::CompilerDSL#compile}).
     #
     # @param [Symbol] filter_name The name of the filter to run the item
-    #   representations' content through
+    # representations' content through
     #
     # @param [Hash] filter_args The filter arguments that should be passed to
-    #   the filter's #run method
+    # the filter's #run method
     #
     # @return [void]
     def filter(filter_name, filter_args={})
@@ -198,13 +218,25 @@ module Nanoc3
       raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
       filter = klass.new(assigns)
 
+      # Check whether filter can be applied
+      if klass.binary? && !item.binary?
+        raise Nanoc3::Errors::CannotUseBinaryFilter.new(self, klass)
+      elsif !klass.binary? && item.binary?
+        raise Nanoc3::Errors::CannotUseTextualFilter.new(self, klass)
+      end
+
       # Run filter
       Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name)
-      @content[:last] = filter.run(@content[:last], filter_args)
+      if item.binary?
+        filter.run(@filenames[:last], filter_args)
+        @filenames[:last] = filter.output_filename
+      else
+        @content[:last] = filter.run(@content[:last], filter_args)
+      end
       Nanoc3::NotificationCenter.post(:filtering_ended, self, filter_name)
 
       # Create snapshot
-      snapshot(@content[:post] ? :post : :pre)
+      snapshot(@content[:post] ? :post : :pre) unless item.binary?
     end
 
     # Lays out the item using the given layout. This method will replace the
@@ -214,11 +246,14 @@ module Nanoc3
     # This method is supposed to be called only in a compilation rule block
     # (see {Nanoc3::CompilerDSL#compile}).
     #
-    # @param [String] layout_identifier The identifier of the layout the ite
-    #   should be laid out with
+    # @param [String] layout_identifier The identifier of the layout the item
+    # should be laid out with
     #
     # @return [void]
     def layout(layout_identifier)
+      # Check whether item can be laid out
+      raise Nanoc3::Errors::CannotLayoutBinaryItem.new(self) if item.binary?
+
       # Create "pre" snapshot
       snapshot(:pre) unless @content[:pre]
 
@@ -243,7 +278,8 @@ module Nanoc3
     #
     # @return [void]
     def snapshot(snapshot_name)
-      @content[snapshot_name] = @content[:last]
+      target = @item.binary? ? @filenames : @content
+      target[snapshot_name] = target[:last]
     end
 
     # Writes the item rep's compiled content to the rep's output file.
@@ -259,17 +295,34 @@ module Nanoc3
       # 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
+      if @item.binary?
+        # Calculate hash of old content
+        if File.file?(self.raw_path)
+          hash_old = hash(self.raw_path)
+          size_old = File.size(self.raw_path)
+        end
+
+        # Copy
+        FileUtils.cp(@filenames[:last], self.raw_path)
+        @written = true
+
+        # Check if file was modified
+        size_new = File.size(self.raw_path)
+        hash_new = hash(self.raw_path) if size_old == size_new
+        @modified = (size_old != size_new || hash_old != hash_new)
+      else
+        # 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
+        # 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
+        # Check if file was modified
+        @modified = File.read(self.raw_path) != @old_content
+      end
     end
 
     # Creates and returns a diff between the compiled content before the
@@ -277,9 +330,13 @@ module Nanoc3
     # compilation session.
     #
     # @return [String, nil] The difference between the old and new compiled
-    #   content in `diff(1)` format, or nil if there is no previous compiled
-    #   content
+    # content in `diff(1)` format, or nil if there is no previous compiled
+    # content
     def diff
+      # Check if content can be diffed
+      # TODO allow binary diffs
+      return nil if @item.binary?
+
       # Check if old content exists
       if @old_content.nil? or self.raw_path.nil?
         nil
@@ -289,7 +346,7 @@ module Nanoc3
     end
 
     def inspect
-      "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} item.identifier=#{self.item.identifier}>"
+      "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} item.identifier=#{self.item.identifier} item.binary?=#{@item.binary?}>"
     end
 
   private
@@ -342,6 +399,18 @@ module Nanoc3
       nil
     end
 
+    # Returns a hash of the given filename
+    def hash(filename)
+      digest = Digest::SHA1.new
+      File.open(filename, 'r') do |io|
+        until io.eof
+          data = io.readpartial(2**10)
+          digest.update(data)
+        end
+      end
+      digest.hexdigest
+    end
+
   end
 
 end

data/lib/nanoc3/base/layout.rb

@@ -16,7 +16,7 @@ module Nanoc3
     attr_reader :attributes
 
     # @return [String] This layout's identifier, starting and ending with a
-    #  slash
+    # slash
     attr_accessor :identifier
 
     # @return [Time] The time when this layout was last modified
@@ -24,18 +24,31 @@ module Nanoc3
 
     # Creates a new layout.
     #
-    # @param [String] content The raw content of this layout.
+    # @param [String] raw_content The raw content of this layout.
     #
     # @param [Hash] attributes A hash containing this layout's attributes.
     #
     # @param [String] identifier This layout's identifier.
     #
-    # @param [Time, nil] mtime The time when this layout was last modified.
-    def initialize(raw_content, attributes, identifier, mtime=nil)
+    # @param [Time, Hash, nil] params_or_mtime Extra parameters for the
+    # layout, or the time when this layout was last modified (deprecated).
+    #
+    # @option params_or_mtime [Time, nil] :mtime (nil) The time when this
+    # layout was last modified
+    def initialize(raw_content, attributes, identifier, params_or_mtime=nil)
+      # Get params and mtime
+      # TODO [in nanoc 4.0] clean this up
+      if params_or_mtime.nil? || params_or_mtime.is_a?(Time)
+        params = {}
+        @mtime = params_or_mtime
+      elsif params_or_mtime.is_a?(Hash)
+        params = params_or_mtime
+        @mtime = params[:mtime]
+      end
+
       @raw_content  = raw_content
       @attributes   = attributes.symbolize_keys
       @identifier   = identifier.cleaned_identifier
-      @mtime        = mtime
     end
 
     # Requests the attribute with the given key.

data/lib/nanoc3/base/notification_center.rb

@@ -17,12 +17,12 @@ module Nanoc3
       # the notification with the given name is received.
       #
       # @param [String, Symbol] name The name of the notification that will
-      #   cause the given block to be called.
+      # cause the given block to be called.
       #
       # @param [String, Symbol, nil] id An identifier for the block. This is
-      #   only used to be able to remove the block (using the remove method)
-      #   later. Can be nil, but this is not recommended because it prevents
-      #   the given notification block from being unregistered.
+      # only used to be able to remove the block (using the remove method)
+      # later. Can be nil, but this is not recommended because it prevents
+      # the given notification block from being unregistered.
       #
       # @yield [*args] Will be executed with the arguments passed to {.post}
       #
@@ -37,10 +37,10 @@ module Nanoc3
       # Posts a notification with the given name and the given arguments.
       #
       # @param [String, Symbol] name The name of the notification that should
-      #   be posted.
+      # be posted.
       #
       # @param args Arguments that wil be passed to the blocks handling the
-      #   notification.
+      # notification.
       #
       # @return [void]
       def post(name, *args)
@@ -57,10 +57,10 @@ module Nanoc3
       # posted.
       #
       # @param [String, Symbol] name The name of the notification that should
-      #   no longer be registered.
+      # no longer be registered.
       #
       # @param [String, Symbol] id The identifier of the block that should be
-      #   removed.
+      # removed.
       #
       # @return [void]
       def remove(name, id)

data/lib/nanoc3/base/plugin_registry.rb

@@ -15,7 +15,7 @@ module Nanoc3
       # Sets the identifiers for this plugin.
       #
       # @param [Array<Symbol>] identifier A list of identifiers to assign to
-      #   this plugin.
+      # this plugin.
       #
       # @return [void]
       def identifiers(*identifiers)
@@ -34,10 +34,10 @@ module Nanoc3
       # Registers the given class as a plugin with the given identifier.
       #
       # @param [Class, String] class_or_name The class to register, or a
-      #   string containing the class name to register.
+      # string containing the class name to register.
       #
       # @param [Array<Symbol>] identifiers A list of identifiers to assign to
-      #   this plugin.
+      # this plugin.
       #
       # @return [void]
       def register(class_or_name, *identifiers)
@@ -79,15 +79,15 @@ module Nanoc3
     # Registers the given class as a plugin.
     #
     # @param [Class] superclass The superclass of the plugin. For example:
-    #   {Nanoc3::Filter}, {Nanoc3::Extra::VCS}.
+    # {Nanoc3::Filter}, {Nanoc3::Extra::VCS}.
     #
     # @param [Class, String] 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: `Nanoc3::Filters::ERB`,
-    #   `"Nanoc3::Filters::Haml"`.
+    # a string, in which case it will be automatically converted to a proper
+    # class at lookup. For example: `Nanoc3::Filters::ERB`,
+    # `"Nanoc3::Filters::Haml"`.
     #
     # @param [Symbol] identifiers One or more symbols identifying the class.
-    #   For example: `:haml`, :`erb`.
+    # For example: `:haml`, :`erb`.
     #
     # @return [void]
     def register(superclass, class_or_name, *identifiers)
@@ -122,7 +122,7 @@ module Nanoc3
     # Returns a list of all plugins. The returned list of plugins is an array
     # with array elements in the following format:
     #
-    #     { :class => ..., :superclass => ..., :identifiers => ... }
+    #   { :class => ..., :superclass => ..., :identifiers => ... }
     #
     # @return [Array<Hash>] A list of all plugins in the format described
     def all

data/lib/nanoc3/base/rule.rb

@@ -6,12 +6,12 @@ module Nanoc3
   class Rule
 
     # @return [Regexp] The regex that determines which items this rule can be
-    #   applied to. This rule can be applied to items with a identifier
-    #   matching this regex.
+    # applied to. This rule can be applied to items with a identifier matching
+    # this regex.
     attr_reader :identifier_regex
 
     # @return [Symbol] The name of the representation that will be compiled
-    #   using this rule
+    # using this rule
     attr_reader :rep_name
 
     # Creates a new item compilation rule with the given identifier regex,
@@ -19,13 +19,13 @@ module Nanoc3
     # item rep as its argument.
     #
     # @param [Regexp] identifier_regex A regular expression that will be used
-    #   to determine whether this rule is applicable to certain items.
+    # to determine whether this rule is applicable to certain items.
     #
     # @param [String, Symbol] rep_name The name of the item representation
-    #   where this rule can be applied to
+    # where this rule can be applied to
     #
     # @param [Proc] block A block that will be called when matching items are
-    #   compiled
+    # compiled
     def initialize(identifier_regex, rep_name, block)
       @identifier_regex = identifier_regex
       @rep_name         = rep_name.to_sym
@@ -36,7 +36,7 @@ module Nanoc3
     # @param [Nanoc3::Item] item The item to check
     #
     # @return [Boolean] true if this rule can be applied to the given item
-    #   rep, false otherwise
+    # rep, false otherwise
     def applicable_to?(item)
       item.identifier =~ @identifier_regex
     end
@@ -44,7 +44,7 @@ module Nanoc3
     # Applies this rule to the given item rep.
     #
     # @param [Nanoc3::ItemRep] rep The item representation where this rule
-    #   should be applied to
+    # should be applied to
     #
     # @return [void]
     def apply_to(rep)

data/lib/nanoc3/base/rule_context.rb

@@ -17,7 +17,7 @@ module Nanoc3
     # Creates a new rule context for the given iterm representation.
     #
     # @param [Nanoc3::ItemRep] rep The item representation for which to create
-    #   a new rule context.
+    # a new rule context.
     def initialize(rep)
       item    = rep.item
       site    = item.site
@@ -41,10 +41,10 @@ module Nanoc3
     # @see Nanoc3::ItemRep#filter
     #
     # @param [Symbol] filter_name The name of the filter to run the item
-    #   representations' content through
+    # representations' content through
     #
     # @param [Hash] filter_args The filter arguments that should be passed to
-    #   the filter's #run method
+    # the filter's #run method
     #
     # @return [void]
     def filter(filter_name, filter_args={})
@@ -56,8 +56,8 @@ module Nanoc3
     #
     # @see Nanoc3::ItemRep#layout
     #
-    # @param [String] layout_identifier The identifier of the layout the ite
-    #   should be laid out with
+    # @param [String] layout_identifier The identifier of the layout the item
+    # should be laid out with
     #
     # @return [void]
     def layout(layout_identifier)