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.
106 107 108 109 |
# File 'lib/nanoc/base/compilation/filter.rb', line 106 def initialize(hash = {}) @assigns = hash super end |
Instance Attribute Details
- (Hash) assigns (readonly)
A hash containing variables that will be made available during filtering.
35 36 37 |
# File 'lib/nanoc/base/compilation/filter.rb', line 35 def assigns @assigns end |
Class Method Details
+ (Boolean) from_binary?
Returns True if this filter can be applied to binary item representations, false otherwise
66 67 68 |
# File 'lib/nanoc/base/compilation/filter.rb', line 66 def from_binary? (@from || :text) == :binary end |
+ (void) requires(*requires) + (Enumerable<String>) requires
83 84 85 86 87 88 89 |
# File 'lib/nanoc/base/compilation/filter.rb', line 83 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.
94 95 96 97 98 99 |
# File 'lib/nanoc/base/compilation/filter.rb', line 94 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
72 73 74 |
# File 'lib/nanoc/base/compilation/filter.rb', line 72 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.
56 57 58 59 60 61 62 |
# File 'lib/nanoc/base/compilation/filter.rb', line 56 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.
172 173 174 175 176 177 178 179 180 181 182 183 184 |
# File 'lib/nanoc/base/compilation/filter.rb', line 172 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>)
.
155 156 157 158 159 160 161 162 163 |
# File 'lib/nanoc/base/compilation/filter.rb', line 155 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.
146 147 148 149 |
# File 'lib/nanoc/base/compilation/filter.rb', line 146 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.
134 135 136 |
# File 'lib/nanoc/base/compilation/filter.rb', line 134 def run(content_or_filename, params = {}) # rubocop:disable Lint/UnusedMethodArgument raise NotImplementedError.new('Nanoc::Filter subclasses must implement #run') end |