Class: Nanoc::Filter Abstract

Inherits:
Int::Context
  • Object
show all
Extended by:
DDPlugin::Plugin
Defined in:
lib/nanoc/base/services/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'

Class Method Summary collapse

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Nanoc::Int::Context

Class Method Details

.always_outdatedvoid

This method returns an undefined value.

Marks this filter as always causing the item rep to be outdated. This is useful for filters that cannot do dependency tracking properly.



101
102
103
# File 'lib/nanoc/base/services/filter.rb', line 101

def always_outdated
  @always_outdated = true
end

.define(ident, &block) ⇒ Object



35
36
37
38
39
40
# File 'lib/nanoc/base/services/filter.rb', line 35

def define(ident, &block)
  filter_class = Class.new(::Nanoc::Filter) { identifier(ident) }
  filter_class.send(:define_method, :run) do |content, params|
    instance_exec(content, params, &block)
  end
end

.named!(name) ⇒ Object

Raises:

  • (Nanoc::Int::Errors::UnknownFilter)


42
43
44
45
46
# File 'lib/nanoc/base/services/filter.rb', line 42

def named!(name)
  klass = named(name)
  raise Nanoc::Int::Errors::UnknownFilter.new(name) if klass.nil?
  klass
end

.requires(*requires) ⇒ void .requiresEnumerable<String>

Overloads:

  • .requires(*requires) ⇒ void

    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

  • .requiresEnumerable<String>

    Returns the required libraries for this filter.

    Returns:

    • (Enumerable<String>)

      This filter’s list of library names that are required



112
113
114
115
116
117
118
# File 'lib/nanoc/base/services/filter.rb', line 112

def requires(*requires)
  if requires.any?
    @requires = requires
  else
    @requires || []
  end
end

.type(arg) ⇒ void

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



64
65
66
67
68
69
70
71
72
# File 'lib/nanoc/base/services/filter.rb', line 64

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

Instance Method Details

#depend_on(items) ⇒ void

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.



212
213
214
# File 'lib/nanoc/base/services/filter.rb', line 212

def depend_on(items)
  items.flat_map(&:reps).flat_map(&:raw_path)
end

#output_filenameString

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



181
182
183
184
# File 'lib/nanoc/base/services/filter.rb', line 181

def output_filename
  @output_filename ||=
    Nanoc::Int::TempFilenameFactory.instance.create(TMP_BINARY_ITEMS_DIR)
end

#run(content_or_filename, params = {}) ⇒ String, void

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)


169
170
171
# File 'lib/nanoc/base/services/filter.rb', line 169

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