Parent

Class/Module Index [+]

Quicksearch

Nanoc3::Filter

Nanoc3::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.

Constants

TMP_BINARY_ITEMS_DIR

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

from_binary?() click to toggle source

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

representations, false otherwise
# File lib/nanoc3/base/filter.rb, line 69
def from_binary?
  (@from || :text) == :binary
end
new(hash={}) click to toggle source

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.
# File lib/nanoc3/base/filter.rb, line 85
def initialize(hash={})
  @assigns = hash
  super
end
to_binary?() click to toggle source

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

representation, false otherwise
# File lib/nanoc3/base/filter.rb, line 75
def to_binary?
  (@to || :text) == :binary
end
type(arg) click to toggle source

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]

# File lib/nanoc3/base/filter.rb, line 59
def type(arg)
  if arg.is_a?(Hash)
    @from, @to = arg.keys[0], arg.values[0]
  else
    @from, @to = arg, arg
  end
end

Public Instance Methods

filename() click to toggle source

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

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

@return [String] The filename

# File lib/nanoc3/base/filter.rb, line 130
def filename
  if assigns[:layout]
    "layout #{assigns[:layout].identifier}"
  elsif assigns[:item]
    "item #{assigns[:item].identifier} (rep #{assigns[:item_rep].name})"
  else
    '?'
  end
end
output_filename() click to toggle source

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.

@return [String] The output filename

# File lib/nanoc3/base/filter.rb, line 113
def output_filename
  @output_filename ||= begin
    require 'tempfile'

    FileUtils.mkdir_p(TMP_BINARY_ITEMS_DIR)
    tempfile = Tempfile.new(filename.gsub(/[^a-z]/, '-'), TMP_BINARY_ITEMS_DIR)
    new_filename = tempfile.path
    tempfile.close!

    new_filename
  end
end
run(content_or_filename, params={}) click to toggle source

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.
# File lib/nanoc3/base/filter.rb, line 104
def run(content_or_filename, params={})
  raise NotImplementedError.new("Nanoc3::Filter subclasses must implement #run")
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.