Context
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.
The path to the directory where temporary binary items are stored
@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
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
@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
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
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
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
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
Generated with the Darkfish Rdoc Generator 2.