Module: Haml::Filters::Base

Module | Haml::Filters::Base
In: | lib/haml/filters.rb

The base module for Haml filters. User-defined filters should be modules including this module.

A user-defined filter should override either Base#render or Base compile. Base#render is the most common. It takes a string, the filter source, and returns another string, the result of the filter. For example:

      module Haml::Filters::Sass
        include Haml::Filters::Base

        def render(text)
          ::Sass::Engine.new(text).render
        end
      end

For details on overriding compile, see its documentation.

### Methods

compile lazy_require render render_with_options

### Public Instance methods

compile(precompiler, text)

compile should be overridden when a filter needs to have access to the Haml evaluation context. Rather than applying a filter to a string at compile-time, compile uses the Haml::Precompiler instance to compile the string to Ruby code that will be executed in the context of the active Haml template.

Warning: the Haml::Precompiler interface is neither well-documented nor guaranteed to be stable. If you want to make use of it, you‘ll probably need to look at the source code and should test your filter when upgrading to new Haml versions.

[Source]

        # File lib/haml/filters.rb, line 70
    70:       def compile(precompiler, text)
    71:         resolve_lazy_requires
    72:         filter = self
    73:         precompiler.instance_eval do
    74:           if contains_interpolation?(text)
    75:             return if options[:suppress_eval]
    76:
    77:             push_script("find_and_preserve(\#{filter.inspect}.render_with_options(\#{unescape_interpolation(text)}, _hamlout.options))\n", false)
    78:             return
    79:           end
    80:
    81:           rendered = Haml::Helpers::find_and_preserve(filter.render_with_options(text, precompiler.options), precompiler.options[:preserve])
    82:
    83:           if !options[:ugly]
    84:             push_text(rendered.rstrip.gsub("\n", "\n#{'  ' * @output_tabs}"))
    85:           else
    86:             push_text(rendered.rstrip)
    87:           end
    88:         end
    89:       end

lazy_require(*reqs)

This becomes a class method of modules that include Base. It allows the module to specify one or more Ruby files that Haml should try to require when compiling the filter.

The first file specified is tried first, then the second, etc. If none are found, the compilation throws an exception.

For example:

      module Haml::Filters::Markdown
        lazy_require 'rdiscount', 'peg_markdown', 'maruku', 'bluecloth'

        ...
      end

[Source]

         # File lib/haml/filters.rb, line 110
    110:       def lazy_require(*reqs)
    111:         @lazy_requires = reqs
    112:       end

render(text)

Takes a string, the source text that should be passed to the filter, and returns the string resulting from running the filter on `text`.

This should be overridden in most individual filter modules to render text with the given filter. If compile is overridden, however, render doesn‘t need to be.

[Source]

        # File lib/haml/filters.rb, line 44
    44:       def render(text)
    45:         raise Error.new("#{self.inspect}#render not defined!")
    46:       end

render_with_options(text, options)

Same as render, but takes the Haml options hash as well. It‘s only safe to rely on options made available in Haml::Engine#options_for_buffer.

[Source]

        # File lib/haml/filters.rb, line 50
    50:       def render_with_options(text, options)
    51:         render(text)
    52:       end

[Validate]