Module Haml::Filters::Base
In: lib/haml/filters.rb
Engine Error SyntaxError Buffer StandardError ActionViewExtensions Generic CSS2Sass HTML2Haml HamlSass Haml Sass Template HTML lib/haml/template.rb lib/haml/error.rb lib/haml/engine.rb lib/haml/html.rb lib/haml/buffer.rb Version Util Precompiler ActionViewExtensions Helpers Base Filters lib/haml/exec.rb Exec Haml dot/m_15_0.png

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   resolve_lazy_requires  

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

Private Instance methods

resolve_lazy_requires()

[Source]

     # File lib/haml/filters.rb, line 116
116:       def resolve_lazy_requires
117:         return unless @lazy_requires
118: 
119:         @lazy_requires[0...-1].each do |req|
120:           begin
121:             @required = req
122:             require @required
123:             return
124:           rescue LoadError; end # RCov doesn't see this, but it is run
125:         end
126: 
127:         begin
128:           @required = @lazy_requires[-1]
129:           require @required
130:         rescue LoadError => e
131:           classname = self.name.match(/\w+$/)[0]
132: 
133:           if @lazy_requires.size == 1
134:             raise Error.new("Can't run #{classname} filter; required file '#{@lazy_requires.first}' not found")
135:           else
136:             raise Error.new("Can't run #{classname} filter; required #{@lazy_requires.map { |r| "'#{r}'" }.join(' or ')}, but none were found")
137:           end
138:         end
139:       end

[Validate]