Module: Haml::Filters::Base

Included in:
Cdata, 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.

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.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object

:nodoc:



32
33
34
35
36
 
# File 'lib/haml/filters.rb', line 32

def self.included(base) # :nodoc:
  Filters.defined[base.name.split("::").last.downcase] = base
  base.extend(base)
  base.instance_variable_set "@lazy_requires", nil
end

Instance Method Details

#compile(precompiler, text) ⇒ Object

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.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/haml/filters.rb', line 70

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

      push_script(<<RUBY, false)
find_and_preserve(#{filter.inspect}.render_with_options(#{unescape_interpolation(text)}, _hamlout.options))
RUBY
      return
    end

    rendered = Haml::Helpers::find_and_preserve(filter.render_with_options(text, precompiler.options), precompiler.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) ⇒ Object

:nodoc:



54
55
56
57
 
# File 'lib/haml/filters.rb', line 54

def internal_compile(*args) # :nodoc:
  resolve_lazy_requires
  compile(*args)
end

#lazy_require(*reqs) ⇒ Object

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



109
110
111
 
# File 'lib/haml/filters.rb', line 109

def lazy_require(*reqs)
  @lazy_requires = reqs
end

#render(text) ⇒ Object

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.

Raises:



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

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

#render_with_options(text, options) ⇒ Object

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.



50
51
52
 
# File 'lib/haml/filters.rb', line 50

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