Class: Nanoc::Filter Abstract

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

Overview

This class is abstract.

Subclass and override #run to implement a custom filter.

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.

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

Nanoc::Filters::AsciiDoc, Nanoc::Filters::BlueCloth, Nanoc::Filters::CodeRay, Nanoc::Filters::CoffeeScript, Nanoc::Filters::ColorizeSyntax, Nanoc::Filters::ERB, Nanoc::Filters::Erubis, Nanoc::Filters::Haml, Nanoc::Filters::Handlebars, Nanoc::Filters::Kramdown, Nanoc::Filters::Less, Nanoc::Filters::Markaby, Nanoc::Filters::Maruku, Nanoc::Filters::Mustache, Nanoc::Filters::Pandoc, Nanoc::Filters::RDiscount, Nanoc::Filters::RDoc, Nanoc::Filters::Rainpress, Nanoc::Filters::RedCloth, Nanoc::Filters::Redcarpet, Nanoc::Filters::RelativizePaths, Nanoc::Filters::RubyPants, Nanoc::Filters::Sass, Nanoc::Filters::Slim, Nanoc::Filters::Typogruby, Nanoc::Filters::UglifyJS, Nanoc::Filters::XSL, Nanoc::Filters::YUICompressor

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

all, 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.



111
112
113
114
 
# File 'lib/nanoc/base/compilation/filter.rb', line 111

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/nanoc/base/compilation/filter.rb', line 38

def assigns
  @assigns
end

Class Method Details

+ (Boolean) from_binary?

Returns 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/nanoc/base/compilation/filter.rb', line 70

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

+ (void) requires(*requires) + (Enumerable<String>) requires

Overloads:

  • + (void) requires(*requires)

    This method returns an undefined value.

    Sets the required libraries for this filter.

    Parameters:

    • requires (Array<String>) —

      A list of library names that are required

  • + (Enumerable<String>) requires

    Returns the required libraries for this filter.

    Returns:

    • (Enumerable<String>) —

      This filter’s list of library names that are required



87
88
89
90
91
92
93
 
# File 'lib/nanoc/base/compilation/filter.rb', line 87

def requires(*requires)
  if requires.size > 0
    @requires = requires
  else
    @requires || []
  end
end

+ (void) setup

This method returns an undefined value.

Requires the filter’s required library if necessary.



98
99
100
101
102
103
 
# File 'lib/nanoc/base/compilation/filter.rb', line 98

def setup
  @setup ||= begin
    requires.each { |r| require r }
    true
  end
end

+ (Boolean) to_binary?

Returns 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/nanoc/base/compilation/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/nanoc/base/compilation/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

- (void) depend_on(items)

This method returns an undefined value.

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.

Parameters:



183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/nanoc/base/compilation/filter.rb', line 183

def depend_on(items)
  # Notify
  items.each do |item|
    Nanoc::NotificationCenter.post(:visit_started, item)
    Nanoc::NotificationCenter.post(:visit_ended,   item)
  end

  # Raise unmet dependency error if necessary
  items.each do |item|
    rep = item.reps.find { |r| !r.compiled? }
    raise Nanoc::Errors::UnmetDependency.new(rep) if rep
  end
end

- (String) filename

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

Returns:



166
167
168
169
170
171
172
173
174
 
# File 'lib/nanoc/base/compilation/filter.rb', line 166

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.

The returned filename will be absolute, so it is safe to change to another directory inside the filter.

Returns:

  • (String) —

    The output filename



151
152
153
154
155
156
157
158
159
160
 
# File 'lib/nanoc/base/compilation/filter.rb', line 151

def output_filename
  @output_filename ||= begin
    FileUtils.mkdir_p(TMP_BINARY_ITEMS_DIR)
    tempfile = Tempfile.new('', TMP_BINARY_ITEMS_DIR)
    new_filename = tempfile.path
    tempfile.close!

    File.expand_path(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) 


139
140
141
 
# File 'lib/nanoc/base/compilation/filter.rb', line 139

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

- (Object) setup_and_run(*args)

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

See Also:

  • Nanoc::Filter.{{#run}


120
121
122
123
 
# File 'lib/nanoc/base/compilation/filter.rb', line 120

def setup_and_run(*args)
  self.class.setup
  run(*args)
end