Module: Haml::Filters::Base

Included in:
Cdata, Css, ERB, Escaped, Javascript, Markdown, Maruku, Plain, Preserve, Ruby, Sass, Textile
Defined in:
lib/haml/filters.rb

Overview

The base module for Haml filters. User-defined filters should be modules including this module. The name of the filter is taken by downcasing the module name. For instance, if the module is named FooBar, the filter will be :foobar.

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

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.

Note that filters overriding #render automatically support #{} for interpolating Ruby code. Those overriding #compile will need to add such support manually if it's desired.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base)

This method is automatically called when Haml::Filters::Base is included in a module. It automatically defines a filter with the downcased name of that module. For example, if the module is named FooBar, the filter will be :foobar.

Parameters:

  • base (Module, Class) —

    The module that this is included in



44
45
46
47
 
# File 'lib/haml/filters.rb', line 44

def self.included(base)
  Filters.defined[base.name.split("::").last.downcase] = base
  base.extend(base)
end

Instance Method Details

#compile(compiler, text)

This 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 Compiler instance to compile the string to Ruby code that will be executed in the context of the active Haml template.

Warning: the Compiler 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.

Parameters:

  • compiler (Haml::Compiler) —

    The compiler instance

  • text (String) —

    The text of the filter

Raises:



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/haml/filters.rb', line 96

def compile(compiler, text)
  resolve_lazy_requires
  filter = self
  compiler.instance_eval do
    if contains_interpolation?(text)
      return if options[:suppress_eval]

      text = unescape_interpolation(text).gsub(/(\\+)n/) do |s|
        escapes = $1.size
        next s if escapes % 2 == 0
        ("\\" * (escapes - 1)) + "\n"
      end
      # We need to add a newline at the beginning to get the
      # filter lines to line up (since the Haml filter contains
      # a line that doesn't show up in the source, namely the
      # filter name). Then we need to escape the trailing
      # newline so that the whole filter block doesn't take up
      # too many.
      text = "\n" + text.sub(/\n"\Z/, "\\n\"")
      push_script <<RUBY.rstrip, :escape_html => false
find_and_preserve(#{filter.inspect}.render_with_options(#{text}, _hamlout.options))
RUBY
      return
    end

    rendered = Haml::Helpers::find_and_preserve(filter.render_with_options(text, compiler.options), compiler.options[:preserve])

    if !options[:ugly]
      push_text(rendered.rstrip.gsub("\n", "\n#{'  ' * @output_tabs}"))
    else
      push_text(rendered.rstrip)
    end
  end
end

#internal_compile(*args)

Same as #compile, but requires the necessary files first. This is used by Engine and is not intended to be overridden or used elsewhere.

See Also:



78
79
80
81
 
# File 'lib/haml/filters.rb', line 78

def internal_compile(*args)
  resolve_lazy_requires
  compile(*args)
end

#lazy_require(*reqs)

This becomes a class method of modules that include Haml::Filters::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', 'kramdown'

  ...
end

Parameters:

  • reqs (Array<String>) —

    The requires to run



147
148
149
 
# File 'lib/haml/filters.rb', line 147

def lazy_require(*reqs)
  @lazy_requires = reqs
end

#render(text) ⇒ String

Takes the source text that should be passed to the filter and returns the result of running the filter on that string.

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.

Parameters:

  • text (String) —

    The source text for the filter to process

Returns:

  • (String) —

    The filtered result

Raises:



59
60
61
 
# File 'lib/haml/filters.rb', line 59

def render(text)
  raise Error.new("#{self.inspect}#render not defined!")
end

#render_with_options(text, options) ⇒ String

Same as #render, but takes a Engine options hash as well. It's only safe to rely on options made available in Engine#options_for_buffer.

Parameters:

  • text (String) —

    The source text for the filter to process

Returns:

  • (String) —

    The filtered result

Raises:

See Also:



70
71
72
 
# File 'lib/haml/filters.rb', line 70

def render_with_options(text, options)
  render(text)
end