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

Public Instance methods

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

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

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

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]