Class Nanoc::Filter
In: lib/nanoc/base/compilation/filter.rb
Parent: Context

Nanoc::Filter is responsible for filtering items. It is the superclass for all textual filters.

A filter instance should only be used once. Filters should not be reused since they store state.

When creating a filter with a hash containing assigned variables, those variables will be made available in the `@assigns` instance variable and the {assigns} method. The assigns itself will also be available as instance variables and instance methods.

@example Accessing assigns in different ways

  filter = SomeFilter.new({ :foo => 'bar' })
  filter.instance_eval { @assigns[:foo] }
    # => 'bar'
  filter.instance_eval { assigns[:foo] }
    # => 'bar'
  filter.instance_eval { @foo }
    # => 'bar'
  filter.instance_eval { foo }
    # => 'bar'

@abstract Subclass and override {run} to implement a custom filter.

Methods

Constants

TMP_BINARY_ITEMS_DIR = 'tmp/binary_items'   The path to the directory where temporary binary items are stored

Attributes

assigns  [R]  A hash containing variables that will be made available during filtering.

@return [Hash]

Public Class methods

@return [Boolean] True if this filter can be applied to binary item

  representations, false otherwise

Creates a new filter that has access to the given assigns.

@param [Hash] hash A hash containing variables that should be made

  available during filtering.

@overload requires(*requires)

  Sets the required libraries for this filter.
  @param [Array<String>] requires A list of library names that are required
  @return [void]

@overload requires

  Returns the required libraries for this filter.
  @return [Enumerable<String>] This filter’s list of library names that are required

Requires the filter’s required library if necessary.

@return [void]

@return [Boolean] True if this filter results in a binary item

  representation, false otherwise

Sets the new type for the filter. The type can be `:binary` (default) or `:text`. The given argument can either be a symbol indicating both “from” and “to” types, or a hash where the only key is the “from” type and the only value is the “to” type.

@example Specifying a text-to-text filter

    type :text

@example Specifying a text-to-binary filter

    type :text => :binary

@param [Symbol, Hash] arg The new type of this filter

@return [void]

Public Instance methods

Creates a dependency from the item that is currently being filtered onto the given collection of items. In other words, require the given items to be compiled first before this items is processed.

@param [Array<Nanoc::Item>] items The items that are depended on.

@return [void]

Returns the filename associated with the item that is being filtered.

  It is in the format `item <identifier> (rep <name>)`.

@return [String] The filename

Returns a filename that is used to write data to. This method is only

  used on binary items. When running a binary filter on a file, the
  resulting file must end up in the location returned by this method.

The returned filename will be absolute, so it is safe to change to

  another directory inside the filter.

@return [String] The output filename

Runs the filter on the given content or filename.

@abstract

@param [String] content_or_filename The unprocessed content that should

  be filtered (if the item is a textual item) or the path to the file
  that should be filtered (if the item is a binary item)

@param [Hash] params A hash containing parameters. Filter subclasses can

  use these parameters to allow modifying the filter's behaviour.

@return [String, void] If the filter output binary content, the return

  value is undefined; if the filter outputs textual content, the return
  value will be the filtered content.

Sets up the filter and runs the filter. This method passes its arguments to {run} unchanged and returns the return value from {run}.

@see {run}

[Validate]