Class: Nanoc3::Filter

### Home Classes Methods

### In Files

- lib/nanoc3/base/filter.rb

### Parent

Nanoc3::Context

### Methods

- ::from_binary?
- ::new
- ::to_binary?
- ::type
- #filename
- #output_filename
- #run

### Files

- ChangeLog
- LICENSE

### Class/Module Index

Quicksearch

- Nanoc3
- Nanoc3::ArrayExtensions
- Nanoc3::CLI
- Nanoc3::CLI::Base
- Nanoc3::CLI::Commands
- Nanoc3::CLI::Commands::Autocompile
- Nanoc3::CLI::Commands::Compile
- Nanoc3::CLI::Commands::CreateItem
- Nanoc3::CLI::Commands::CreateLayout
- Nanoc3::CLI::Commands::CreateSite
- Nanoc3::CLI::Commands::Debug
- Nanoc3::CLI::Commands::Help
- Nanoc3::CLI::Commands::Info
- Nanoc3::CLI::Commands::Update
- Nanoc3::CLI::Commands::View
- Nanoc3::CLI::Logger
- Nanoc3::CodeSnippet
- Nanoc3::Compiler
- Nanoc3::CompilerDSL
- Nanoc3::Context
- Nanoc3::DataSource
- Nanoc3::DataSources
- Nanoc3::DataSources::Delicious
- Nanoc3::DataSources::Filesystem
- Nanoc3::DataSources::FilesystemCombined
- Nanoc3::DataSources::FilesystemCompact
- Nanoc3::DataSources::FilesystemUnified
- Nanoc3::DataSources::FilesystemVerbose
- Nanoc3::DataSources::LastFM
- Nanoc3::DataSources::Twitter
- Nanoc3::DependencyTracker
- Nanoc3::DirectedGraph
- Nanoc3::Errors
- Nanoc3::Errors::CannotDetermineFilter
- Nanoc3::Errors::CannotLayoutBinaryItem
- Nanoc3::Errors::CannotUseBinaryFilter
- Nanoc3::Errors::CannotUseTextualFilter
- Nanoc3::Errors::DataNotYetAvailable
- Nanoc3::Errors::Generic
- Nanoc3::Errors::NoMatchingCompilationRuleFound
- Nanoc3::Errors::NoMatchingRoutingRuleFound
- Nanoc3::Errors::NoRulesFileFound
- Nanoc3::Errors::RecursiveCompilation
- Nanoc3::Errors::UnknownDataSource
- Nanoc3::Errors::UnknownFilter
- Nanoc3::Errors::UnknownLayout
- Nanoc3::Errors::UnmetDependency
- Nanoc3::Extra
- Nanoc3::Extra::AutoCompiler
- Nanoc3::Extra::CHiCk
- Nanoc3::Extra::CHiCk::CacheController
- Nanoc3::Extra::CHiCk::Client
- Nanoc3::Extra::CHiCk::RackClient
- Nanoc3::Extra::Context
- Nanoc3::Extra::Deployers
- Nanoc3::Extra::Deployers::Rsync
- Nanoc3::Extra::FileProxy
- Nanoc3::Extra::TimeExtensions
- Nanoc3::Extra::VCS
- Nanoc3::Extra::VCSes
- Nanoc3::Extra::VCSes::Bazaar
- Nanoc3::Extra::VCSes::Dummy
- Nanoc3::Extra::VCSes::Git
- Nanoc3::Extra::VCSes::Mercurial
- Nanoc3::Extra::VCSes::Subversion
- Nanoc3::Extra::Validators
- Nanoc3::Extra::Validators::Links
- Nanoc3::Extra::Validators::Links::EachPairEnumerator
- Nanoc3::Extra::Validators::W3C
- Nanoc3::Filter
- Nanoc3::Filters
- 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
- Nanoc3::HashExtensions
- Nanoc3::Helpers
- Nanoc3::Helpers::Blogging
- Nanoc3::Helpers::Breadcrumbs
- Nanoc3::Helpers::Capturing
- Nanoc3::Helpers::Filtering
- Nanoc3::Helpers::HTMLEscape
- Nanoc3::Helpers::LinkTo
- Nanoc3::Helpers::Rendering
- Nanoc3::Helpers::Tagging
- Nanoc3::Helpers::Text
- Nanoc3::Helpers::XMLSitemap
- Nanoc3::Item
- Nanoc3::ItemRep
- Nanoc3::Layout
- Nanoc3::NotificationCenter
- Nanoc3::PluginRegistry
- Nanoc3::PluginRegistry::PluginMethods
- Nanoc3::Rule
- Nanoc3::RuleContext
- Nanoc3::Site
- Nanoc3::StringExtensions
- Nanoc3::Tasks
- Nanoc3::Tasks::Clean
- Array
- Enumerable
- Hash
- Object
- OrderedHash
- String
- Time

No matching classes.

# Nanoc3::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.

@example 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'

@abstract Subclass and override {run} to implement a custom filter.

### Constants

TMP_BINARY_ITEMS_DIR

  The path to the directory where temporary binary items are stored

### Attributes

assigns[R]

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

@return [Hash]

### Public Class Methods

from_binary?() click to toggle source

@return [Boolean] True if this filter can be applied to binary item

    representations, false otherwise

    # File lib/nanoc3/base/filter.rb, line 69
    def from_binary?
      (@from || :text) == :binary
    end

new(hash={}) click to toggle source

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

@param [Hash] hash A hash containing variables that should be made

    available during filtering.

    # File lib/nanoc3/base/filter.rb, line 85
    def initialize(hash={})
      @assigns = hash
      super
    end

to_binary?() click to toggle source

@return [Boolean] True if this filter results in a binary item

    representation, false otherwise

    # File lib/nanoc3/base/filter.rb, line 75
    def to_binary?
      (@to || :text) == :binary
    end

type(arg) click to toggle source

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.

@example Specifying a text-to-text filter

    type :text

@example Specifying a text-to-binary filter

    type :text => :binary

@param [Symbol, Hash] arg The new type of this filter

@return [void]

    # File lib/nanoc3/base/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

### Public Instance Methods

filename() click to toggle source

Returns the filename associated with the item that is being filtered.

    It is in the format `item <identifier> (rep <name>)`.

@return [String] The filename

    # File lib/nanoc3/base/filter.rb, line 130
    def filename
      if assigns[:layout]
        "layout #{assigns[:layout].identifier}"
      elsif assigns[:item]
        "item #{assigns[:item].identifier} (rep #{assigns[:item_rep].name})"
      else
        '?'
      end
    end

output_filename() click to toggle source

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.

@return [String] The output filename

    # File lib/nanoc3/base/filter.rb, line 113
    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

run(content_or_filename, params={}) click to toggle source

Runs the filter on the given content or filename.

@abstract

@param [String] content_or_filename 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)

@param [Hash] params A hash containing parameters. Filter subclasses can

    use these parameters to allow modifying the filter's behaviour.

@return [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.

    # File lib/nanoc3/base/filter.rb, line 104
    def run(content_or_filename, params={})
      raise NotImplementedError.new("Nanoc3::Filter subclasses must implement #run")
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.