Parent

Class/Module Index [+]

Quicksearch

Nanoc::ItemRep

A single representation (rep) of an item ({Nanoc::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.

Attributes

binary[R]

@return [Boolean] true if this rep is currently binary; false otherwise

binary?[R]

@return [Boolean] true if this rep is currently binary; false otherwise

item[R]

@return [Nanoc::Item] The item to which this rep belongs

name[R]

@return [Symbol] The representation's unique name

snapshots[RW]

@return [Array] A list of snapshots, represented as arrays where the

first element is the snapshot name (a Symbol) and the last element is
a Boolean indicating whether the snapshot is final or not

Public Class Methods

new(item, name) click to toggle source

Creates a new item representation for the given item.

@param [Nanoc::Item] item The item to which the new representation will

belong.

@param [Symbol] name The unique name for the new item representation.

# File lib/nanoc/base/result_data/item_rep.rb, line 209
def initialize(item, name)
  # Set primary attributes
  @item   = item
  @name   = name

  # Set binary
  @binary = @item.binary?

  # Set default attributes
  @raw_paths  = {}
  @paths      = {}
  @assigns    = {}
  @snapshots  = []
  initialize_content

  # Reset flags
  @compiled = false
end

Public Instance Methods

compiled_content(params={}) click to toggle source

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/nanoc/base/result_data/item_rep.rb, line 237
def compiled_content(params={})
  # Make sure we're not binary
  if self.item.binary?
    raise Nanoc::Errors::CannotGetCompiledContentOfBinaryItem.new(self)
  end

  # Notify
  Nanoc::NotificationCenter.post(:visit_started, self.item)
  Nanoc::NotificationCenter.post(:visit_ended,   self.item)

  # Get name of last pre-layout snapshot
  snapshot = params.fetch(:snapshot) { @content[:pre] ? :pre : :last }
  is_moving = [ :pre, :post, :last ].include?(snapshot)

  # Check existance of snapshot
  if !is_moving && snapshots.find { |s| s.first == snapshot && s.last == true }.nil?
    raise Nanoc::Errors::NoSuchSnapshot.new(self, snapshot)
  end

  # Require compilation
  if @content[snapshot].nil? || (!self.compiled? && is_moving)
    raise Nanoc::Errors::UnmetDependency.new(self)
  else
    @content[snapshot]
  end
end
filter(filter_name, filter_args={}) click to toggle source

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 {Nanoc::CompilerDSL#compile}).

@see Nanoc::ItemRepProxy#filter

@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/nanoc/base/result_data/item_rep.rb, line 322
def filter(filter_name, filter_args={})
  # Get filter class
  klass = filter_named(filter_name)
  raise Nanoc::Errors::UnknownFilter.new(filter_name) if klass.nil?

  # Check whether filter can be applied
  if klass.from_binary? && !self.binary?
    raise Nanoc::Errors::CannotUseBinaryFilter.new(self, klass)
  elsif !klass.from_binary? && self.binary?
    raise Nanoc::Errors::CannotUseTextualFilter.new(self, klass)
  end

  begin
    # Notify start
    Nanoc::NotificationCenter.post(:filtering_started, self, filter_name)

    # Create filter
    filter = klass.new(assigns)

    # Run filter
    source = self.binary? ? temporary_filenames[:last] : @content[:last]
    result = filter.setup_and_run(source, filter_args)
    if klass.to_binary?
      temporary_filenames[:last] = filter.output_filename
    else
      @content[:last] = result
      @content[:last].freeze
    end
    @binary = klass.to_binary?

    # 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, :final => false) unless self.binary?
  ensure
    # Notify end
    Nanoc::NotificationCenter.post(:filtering_ended, self, filter_name)
  end
end
has_snapshot?(snapshot_name) click to toggle source

Checks whether content exists at a given snapshot.

@return [Boolean] True if content exists for the snapshot with the

given name, false otherwise

@since 3.2.0

# File lib/nanoc/base/result_data/item_rep.rb, line 270
def has_snapshot?(snapshot_name)
  !@content[snapshot_name].nil?
end
inspect() click to toggle source
# File lib/nanoc/base/result_data/item_rep.rb, line 467
def inspect
  "<#{self.class} name=\"#{self.name}\" binary=#{self.binary?} raw_path=\"#{self.raw_path}\" item.identifier=\"#{self.item.identifier}\">"
end
is_proxy?() click to toggle source

Returns false because this item is not yet a proxy, and therefore does need to be wrapped in a proxy during compilation.

@api private

@return [false]

@see Nanoc::ItemRepRecorderProxy#is_proxy? @see Nanoc::ItemRepProxy#is_proxy?

# File lib/nanoc/base/result_data/item_rep.rb, line 454
def is_proxy?
  false
end
layout(layout, filter_name, filter_args) click to toggle source

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 {Nanoc::CompilerDSL#compile}).

@see Nanoc::ItemRepProxy#layout

@param [Nanoc::Layout] layout The layout to use

@param [Symbol] filter_name The name of the filter to layout the item

representations' content with

@param [Hash] filter_args The filter arguments that should be passed to

the filter's #run method

@return [void]

# File lib/nanoc/base/result_data/item_rep.rb, line 384
def layout(layout, filter_name, filter_args)
  # Check whether item can be laid out
  raise Nanoc::Errors::CannotLayoutBinaryItem.new(self) if self.binary?

  # Create "pre" snapshot
  if @content[:post].nil?
    snapshot(:pre, :final => true)
  end

  # Create filter
  klass = filter_named(filter_name)
  raise Nanoc::Errors::UnknownFilter.new(filter_name) if klass.nil?
  filter = klass.new(assigns.merge({ :layout => layout }))

  # Visit
  Nanoc::NotificationCenter.post(:visit_started, layout)
  Nanoc::NotificationCenter.post(:visit_ended,   layout)

  begin
    # Notify start
    Nanoc::NotificationCenter.post(:processing_started, layout)
    Nanoc::NotificationCenter.post(:filtering_started,  self, filter_name)

    # Layout
    @content[:last] = filter.setup_and_run(layout.raw_content, filter_args)

    # Create "post" snapshot
    snapshot(:post, :final => false)
  ensure
    # Notify end
    Nanoc::NotificationCenter.post(:filtering_ended,  self, filter_name)
    Nanoc::NotificationCenter.post(:processing_ended, layout)
  end
end
path(params={}) click to toggle source

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

# File lib/nanoc/base/result_data/item_rep.rb, line 298
def path(params={})
  Nanoc3::NotificationCenter.post(:visit_started, self.item)
  Nanoc3::NotificationCenter.post(:visit_ended,   self.item)

  snapshot_name = params[:snapshot] || :last
  @paths[snapshot_name]
end
raw_path(params={}) click to toggle source

Returns the item rep’s raw path. It includes the path to the output directory and the full filename.

@option params [Symbol] :snapshot (:last) The snapshot for which the

path should be returned

@return [String] The item rep’s path

# File lib/nanoc/base/result_data/item_rep.rb, line 281
def raw_path(params={})
  Nanoc3::NotificationCenter.post(:visit_started, self.item)
  Nanoc3::NotificationCenter.post(:visit_ended,   self.item)

  snapshot_name = params[:snapshot] || :last
  @raw_paths[snapshot_name]
end
reference() click to toggle source

Returns an object that can be used for uniquely identifying objects.

@api private

@return [Object] An unique reference to this object

# File lib/nanoc/base/result_data/item_rep.rb, line 463
def reference
  [ type, self.item.identifier, self.name ]
end
snapshot(snapshot_name, params={}) click to toggle source

Creates a snapshot of the current compiled item content.

@param [Symbol] snapshot_name The name of the snapshot to create

@option params [Boolean] :final (true) True if this is the final time

the snapshot will be updated; false if it is a non-final moving
snapshot (such as `:pre`, `:post` or `:last`)

@return [void]

# File lib/nanoc/base/result_data/item_rep.rb, line 428
def snapshot(snapshot_name, params={})
  is_final = params.fetch(:final) { true }
  @content[snapshot_name] = @content[:last] unless self.binary?
  self.write(snapshot_name) if is_final
end
to_recording_proxy() click to toggle source

Returns a recording proxy that is used for determining whether the compilation has changed, and thus whether the item rep needs to be recompiled.

@api private

@return [Nanoc::ItemRepRecorderProxy] The recording proxy

# File lib/nanoc/base/result_data/item_rep.rb, line 441
def to_recording_proxy
  Nanoc::ItemRepRecorderProxy.new(self)
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.