Class: Nanoc3::Filter Abstract

Inherits:
Context show all
Extended by:
PluginRegistry::PluginMethods
Defined in:
lib/nanoc3/base/filter.rb

Overview

This class is abstract.

Subclass and override #run to implement a custom 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.

Examples:

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'

Direct Known Subclasses

Nanoc3::Filters::BlueCloth, Nanoc3::Filters::CodeRay, Nanoc3::Filters::ColorizeSyntax, Nanoc3::Filters::ERB, Nanoc3::Filters::Erubis, Nanoc3::Filters::Haml, Nanoc3::Filters::Kramdown, Nanoc3::Filters::Less, Nanoc3::Filters::Markaby, Nanoc3::Filters::Maruku, Nanoc3::Filters::RDiscount, Nanoc3::Filters::RDoc, Nanoc3::Filters::Rainpress, Nanoc3::Filters::RedCloth, Nanoc3::Filters::RelativizePaths, Nanoc3::Filters::RubyPants, Nanoc3::Filters::Sass

Constant Summary

TMP_BINARY_ITEMS_DIR =

The path to the directory where temporary binary items are stored

'tmp/binary_items'

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from PluginRegistry::PluginMethods

identifier, identifiers, named, register

Methods inherited from Context

#get_binding

Constructor Details

- (Filter) initialize(hash = {})

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

Parameters:

  • hash (Hash) (defaults to: {}) —

    A hash containing variables that should be made available during filtering.



86
87
88
89
 
# File 'lib/nanoc3/base/filter.rb', line 86

def initialize(hash={})
  @assigns = hash
  super
end

Instance Attribute Details

- (Hash) assigns (readonly)

A hash containing variables that will be made available during filtering.

Returns:



38
39
40
 
# File 'lib/nanoc3/base/filter.rb', line 38

def assigns
  @assigns
end

Class Method Details

+ (Boolean) from_binary?

True if this filter can be applied to binary item representations, false otherwise

Returns:

  • (Boolean) —

    True if this filter can be applied to binary item representations, false otherwise



70
71
72
 
# File 'lib/nanoc3/base/filter.rb', line 70

def from_binary?
  (@from || :text) == :binary
end

+ (Boolean) to_binary?

True if this filter results in a binary item representation, false otherwise

Returns:

  • (Boolean) —

    True if this filter results in a binary item representation, false otherwise



76
77
78
 
# File 'lib/nanoc3/base/filter.rb', line 76

def to_binary?
  (@to || :text) == :binary
end

+ (void) type(arg)

This method returns an undefined value.

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.

Examples:

Specifying a text-to-text filter

type :text

Specifying a text-to-binary filter

type :text => :binary

Parameters:

  • arg (Symbol, Hash) —

    The new type of this filter



60
61
62
63
64
65
66
 
# File 'lib/nanoc3/base/filter.rb', line 60

def type(arg)
  if arg.is_a?(Hash)
    @from, @to = arg.keys[0], arg.values[0]
  else
    @from, @to = arg, arg
  end
end

Instance Method Details

- (String) filename

Returns the filename associated with the item that is being filtered. It is in the format item <identifier> (rep <name>).

Returns:



131
132
133
134
135
136
137
138
139
 
# File 'lib/nanoc3/base/filter.rb', line 131

def filename
  if assigns[:layout]
    "layout #{assigns[:layout].identifier}"
  elsif assigns[:item]
    "item #{assigns[:item].identifier} (rep #{assigns[:item_rep].name})"
  else
    '?'
  end
end

- (String) output_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.

Returns:

  • (String) —

    The output filename



114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/nanoc3/base/filter.rb', line 114

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

- (String, void) run(content_or_filename, params = {})

This method is abstract.

Runs the filter on the given content or filename.

Parameters:

  • content_or_filename (String) —

    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)

  • params (Hash) (defaults to: {}) —

    A hash containing parameters. Filter subclasses can use these parameters to allow modifying the filter's behaviour.

Returns:

  • (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.

Raises:

  • (NotImplementedError) 


105
106
107
 
# File 'lib/nanoc3/base/filter.rb', line 105

def run(content_or_filename, params={})
  raise NotImplementedError.new("Nanoc3::Filter subclasses must implement #run")
end