Class: Nanoc::Filter Abstract
- Inherits:
-
Context
- Object
- Context
- Nanoc::Filter
- Extended by:
- PluginRegistry::PluginMethods
- Defined in:
- lib/nanoc/base/compilation/filter.rb
Overview
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.
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 =
'binary_items'
Instance Attribute Summary (collapse)
-
- (Hash) assigns
readonly
A hash containing variables that will be made available during filtering.
Class Method Summary (collapse)
-
+ (Boolean) from_binary?
True if this filter can be applied to binary item representations, false otherwise.
-
+ (Object) requires(*requires)
-
+ (void) setup
Requires the filter’s required library if necessary.
-
+ (Boolean) to_binary?
True if this filter results in a binary item representation, false otherwise.
-
+ (void) type(arg)
Sets the new type for the filter.
Instance Method Summary (collapse)
-
- (void) depend_on(items)
Creates a dependency from the item that is currently being filtered onto the given collection of items.
-
- (String) filename
Returns the filename associated with the item that is being filtered.
-
- (Filter) initialize(hash = {})
constructor
Creates a new filter that has access to the given assigns.
-
- (String) output_filename
Returns a filename that is used to write data to.
-
- (String, void) run(content_or_filename, params = {})
abstract
Runs the filter on the given content or filename.
-
- (Object) setup_and_run(*args)
Sets up the filter and runs the filter.
Methods included from PluginRegistry::PluginMethods
all, identifier, identifiers, named, register
Methods inherited from Context
Constructor Details
- (Filter) initialize(hash = {})
Creates a new filter that has access to the given assigns.
110 111 112 113 |
# File 'lib/nanoc/base/compilation/filter.rb', line 110 def initialize(hash = {}) @assigns = hash super end |
Instance Attribute Details
- (Hash) assigns (readonly)
A hash containing variables that will be made available during filtering.
37 38 39 |
# File 'lib/nanoc/base/compilation/filter.rb', line 37 def assigns @assigns end |
Class Method Details
+ (Boolean) from_binary?
Returns True if this filter can be applied to binary item representations, false otherwise
69 70 71 |
# File 'lib/nanoc/base/compilation/filter.rb', line 69 def from_binary? (@from || :text) == :binary end |
+ (void) requires(*requires) + (Enumerable<String>) requires
86 87 88 89 90 91 92 |
# File 'lib/nanoc/base/compilation/filter.rb', line 86 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.
97 98 99 100 101 102 |
# File 'lib/nanoc/base/compilation/filter.rb', line 97 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
75 76 77 |
# File 'lib/nanoc/base/compilation/filter.rb', line 75 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.
59 60 61 62 63 64 65 |
# File 'lib/nanoc/base/compilation/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 |
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.
176 177 178 179 180 181 182 183 184 185 186 187 188 |
# File 'lib/nanoc/base/compilation/filter.rb', line 176 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>)
.
159 160 161 162 163 164 165 166 167 |
# File 'lib/nanoc/base/compilation/filter.rb', line 159 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.
150 151 152 153 |
# File 'lib/nanoc/base/compilation/filter.rb', line 150 def output_filename @output_filename ||= Nanoc::TempFilenameFactory.instance.create(TMP_BINARY_ITEMS_DIR) end |
- (String, void) run(content_or_filename, params = {})
Runs the filter on the given content or filename.
138 139 140 |
# File 'lib/nanoc/base/compilation/filter.rb', line 138 def run(content_or_filename, params = {}) raise NotImplementedError.new('Nanoc::Filter subclasses must implement #run') end |