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).
The descriptive strings for each outdatedness reason. This hash is used by the {outdatedness_reason} method.
@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
@return [Boolean] true if this rep’s output file was created during the current or last compilation session; false otherwise
@return [Boolean] true if this rep’s output file was created during the current or last compilation session; false otherwise
@return [Boolean] true if this rep is forced to be dirty (e.g. because of the `–force` commandline option); false otherwise
@return [Boolean] true if this rep’s output file has changed since the last time it was compiled; false otherwise
@return [Boolean] true if this rep’s output file has changed since the last time it was compiled; false otherwise
@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.
@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.
Creates a new item representation for the given item.
@param [Nanoc3::Item] item The item to which the new representation will belong.
@param [Symbol] name The unique name for the new item representation.
# File lib/nanoc3/base/item_rep.rb, line 88 def initialize(item, name) # Set primary attributes @item = item @name = name # Set binary @binary = @item.binary? # Initialize content and filenames initialize_content @old_content = nil # Reset flags @compiled = false @modified = false @created = false @written = false @force_outdated = false end
@return [Hash] The assignments that should be available when compiling the content.
# File lib/nanoc3/base/item_rep.rb, line 178 def assigns if self.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).
@return [String] The compiled content at the given snapshot (or the default snapshot if no snapshot is specified)
# File lib/nanoc3/base/item_rep.rb, line 204 def compiled_content(params={}) # Notify Nanoc3::NotificationCenter.post(:visit_started, self.item) Nanoc3::NotificationCenter.post(:visit_ended, self.item) # Debug puts "*** Attempting to fetch content for #{self.inspect}" if $DEBUG # Require compilation raise Nanoc3::Errors::UnmetDependency.new(self) unless compiled? # Get name of last pre-layout snapshot snapshot_name = params[:snapshot] if @content[:pre] snapshot_name ||= :pre else snapshot_name ||= :last end # Check presence of snapshot if @content[snapshot_name].nil? warn "WARNING: The “#{self.item.identifier}” item (rep “#{self.name}”) does not have the requested snapshot named #{snapshot_name.inspect}.\n\n* Make sure that you are requesting the correct snapshot.\n* It is not possible to request the compiled content of a binary item representation; if this item is marked as binary even though you believe it should be textual, you may need to add the extension of this item to the site configuration’s `text_extensions` array.".make_compatible_with_env end # Get content @content[snapshot_name] end
@deprecated Use {Nanoc3::ItemRep#compiled_content} instead.
# File lib/nanoc3/base/item_rep.rb, line 233 def content_at_snapshot(snapshot=:pre) compiled_content(:snapshot => snapshot) end
Creates and returns a diff between the compiled content before the current compilation session and the content compiled in the current 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
# File lib/nanoc3/base/item_rep.rb, line 393 def diff if self.binary? nil else @diff_thread.join if @diff_thread @diff end end
Runs the item content through the given filter with the given arguments. This method will replace the content of the `:last` snapshot with the filtered content of the last snapshot.
This method is supposed to be called only in a compilation rule block (see {Nanoc3::CompilerDSL#compile}).
@param [Symbol] filter_name The name of the filter to run the item representations’ content through
@param [Hash] filter_args The filter arguments that should be passed to the filter’s run method
@return [void]
# File lib/nanoc3/base/item_rep.rb, line 260 def filter(filter_name, filter_args={}) # Get filter class klass = filter_named(filter_name) raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil? # Check whether filter can be applied if klass.from_binary? && !self.binary? raise Nanoc3::Errors::CannotUseBinaryFilter.new(self, klass) elsif !klass.from_binary? && self.binary? raise Nanoc3::Errors::CannotUseTextualFilter.new(self, klass) end # Create filter filter = klass.new(assigns) # Run filter Nanoc3::NotificationCenter.post(:filtering_started, self, filter_name) source = self.binary? ? @filenames[:last] : @content[:last] result = filter.run(source, filter_args) if klass.to_binary? @filenames[:last] = filter.output_filename else @content[:last] = result end @binary = klass.to_binary? Nanoc3::NotificationCenter.post(:filtering_ended, self, filter_name) # Check whether file was written if self.binary? && !File.file?(filter.output_filename) raise RuntimeError, "The #{filter_name.inspect} filter did not write anything to the required output file, #{filter.output_filename}." end # Create snapshot snapshot(@content[:post] ? :post : :pre) unless self.binary? end
Resets the compilation progress for this item representation. This is necessary when an unmet dependency is detected during compilation. This method should probably not be called directly.
@return [void]
# File lib/nanoc3/base/item_rep.rb, line 242 def forget_progress initialize_content end
# File lib/nanoc3/base/item_rep.rb, line 402 def inspect "<#{self.class}:0x#{self.object_id.to_s(16)} name=#{self.name} binary=#{self.binary?} raw_path=#{self.raw_path} item.identifier=#{self.item.identifier}>" end
Lays out the item using the given layout. This method will replace the content of the `:last` snapshot with the laid out content of the last snapshot.
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 item should be laid out with
@return [void]
# File lib/nanoc3/base/item_rep.rb, line 308 def layout(layout_identifier) # Check whether item can be laid out raise Nanoc3::Errors::CannotLayoutBinaryItem.new(self) if self.binary? # Create "pre" snapshot snapshot(:pre) unless @content[:pre] # Create filter layout = layout_with_identifier(layout_identifier) filter, filter_name, filter_args = filter_for_layout(layout) # 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
@return [Boolean] true if this item rep’s output file is outdated and must be regenerated, false otherwise
# File lib/nanoc3/base/item_rep.rb, line 172 def outdated? !outdatedness_reason.nil? end
Calculates the reason why this item representation is outdated. The output will be a hash with a `:type` key, containing the reason why the item is outdated in the form of a symbol, and a `:description` key, containing a descriptive string that can be printed if necessary.
For documentation on the types that this method can return, check the {OUTDATEDNESS_REASON_DESCRIPTIONS} hash in this class.
@return [Hash, nil] A hash containing the reason why this item rep is
outdated, both in the form of a symbol and as a descriptive string, or nil if the item representation is not outdated.
# File lib/nanoc3/base/item_rep.rb, line 119 def outdatedness_reason # Get reason symbol reason = lambda do # Outdated if we don't know return :no_mtime if @item.mtime.nil? # Outdated if the dependency tracker says so return :forced if @force_outdated # Outdated if compiled file doesn't exist (yet) return :no_raw_path if self.raw_path.nil? return :not_written if !File.file?(self.raw_path) # Get compiled mtime compiled_mtime = File.stat(self.raw_path).mtime # Outdated if file too old return :source_modified if @item.mtime > compiled_mtime # Outdated if layouts outdated return :layouts_outdated if @item.site.layouts.any? do |l| l.mtime.nil? || l.mtime > compiled_mtime end # Outdated if code outdated return :code_outdated if @item.site.code_snippets.any? do |cs| cs.mtime.nil? || cs.mtime > compiled_mtime end # Outdated if config outdated return :config_outdated if @item.site.config_mtime.nil? return :config_outdated if @item.site.config_mtime > compiled_mtime # Outdated if rules outdated return :rules_outdated if @item.site.rules_mtime.nil? return :rules_outdated if @item.site.rules_mtime > compiled_mtime return nil end[] # Build reason symbol and description if reason.nil? nil else { :type => reason, :description => OUTDATEDNESS_REASON_DESCRIPTIONS[reason] } end end
Creates a snapshot of the current compiled item content.
@param [Symbol] snapshot_name The name of the snapshot to create
@return [void]
# File lib/nanoc3/base/item_rep.rb, line 335 def snapshot(snapshot_name) target = self.binary? ? @filenames : @content target[snapshot_name] = target[:last] end
Writes the item rep’s compiled content to the rep’s output file.
This method should not be called directly, even in a compilation block; the compiler is responsible for calling this method.
@return [void]
# File lib/nanoc3/base/item_rep.rb, line 346 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) if self.binary? # Calculate hash of old content if File.file?(self.raw_path) hash_old = hash_for_file(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_for_file(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 # Generate diff generate_diff # Check if file was modified @modified = File.read(self.raw_path) != @old_content end end
Generated with the Darkfish Rdoc Generator 2.