Class Index [+]

Quicksearch

Haml::Filters::Base

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.

Public Class Methods

included(base) click to toggle source

This method is automatically called when {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`.

@param base [Module, Class] The module that this is included in

    # File lib/haml/filters.rb, line 44
44:       def self.included(base)
45:         Filters.defined[base.name.split("::").last.downcase] = base
46:         base.extend(base)
47:       end

Public Instance Methods

compile(precompiler, text) click to toggle source

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 {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.

@param precompiler [Haml::Precompiler] The precompiler instance @param text [String] The text of the filter @raise [Haml::Error] if none of {#compile}, {#render}, and {#render_with_options} are overridden

     # File lib/haml/filters.rb, line 96
 96:       def compile(precompiler, text)
 97:         resolve_lazy_requires
 98:         filter = self
 99:         precompiler.instance_eval do
100:           if contains_interpolation?(text)
101:             return if options[:suppress_eval]
102: 
103:             text = unescape_interpolation(text).gsub(/(\\+)n/) do |s|
104:               escapes = $1.size
105:               next s if escapes % 2 == 0
106:               ("\\" * (escapes - 1)) + "\n"
107:             end
108:             newline if text.gsub!(/\n"\Z/, "\\n\"")
109:             push_script find_and_preserve(#{filter.inspect}.render_with_options(#{text}, _hamlout.options)).strip, :escape_html => false
110:             return
111:           end
112: 
113:           rendered = Haml::Helpers::find_and_preserve(filter.render_with_options(text, precompiler.options), precompiler.options[:preserve])
114: 
115:           if !options[:ugly]
116:             push_text(rendered.rstrip.gsub("\n", "\n#{'  ' * @output_tabs}"))
117:           else
118:             push_text(rendered.rstrip)
119:           end
120: 
121:           (text.count("\n") - 1).times {newline}
122:           resolve_newlines
123:           newline
124:         end
125:       end
internal_compile(*args) click to toggle source

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

@see #

    # File lib/haml/filters.rb, line 78
78:       def internal_compile(*args)
79:         resolve_lazy_requires
80:         compile(*args)
81:       end
lazy_require(*reqs) click to toggle source

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

@param reqs [Array] The requires to run

     # File lib/haml/filters.rb, line 145
145:       def lazy_require(*reqs)
146:         @lazy_requires = reqs
147:       end
render(text) click to toggle source

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.

@param text [String] The source text for the filter to process @return [String] The filtered result @raise [Haml::Error] if it’s not overridden

    # File lib/haml/filters.rb, line 59
59:       def render(text)
60:         raise Error.new("#{self.inspect}#render not defined!")
61:       end
render_with_options(text, options) click to toggle source

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

@see # @param text [String] The source text for the filter to process @return [String] The filtered result @raise [Haml::Error] if it or {#render} isn’t overridden

    # File lib/haml/filters.rb, line 70
70:       def render_with_options(text, options)
71:         render(text)
72:       end

Private Instance Methods

resolve_lazy_requires() click to toggle source
     # File lib/haml/filters.rb, line 151
151:       def resolve_lazy_requires
152:         return unless @lazy_requires
153: 
154:         @lazy_requires[0...1].each do |req|
155:           begin
156:             @required = req
157:             require @required
158:             return
159:           rescue LoadError; end # RCov doesn't see this, but it is run
160:         end
161: 
162:         begin
163:           @required = @lazy_requires[1]
164:           require @required
165:         rescue LoadError => e
166:           classname = self.name.match(/\w+$/)[0]
167: 
168:           if @lazy_requires.size == 1
169:             raise Error.new("Can't run #{classname} filter; required file '#{@lazy_requires.first}' not found")
170:           else
171:             raise Error.new("Can't run #{classname} filter; required #{@lazy_requires.map { |r| "'#{r}'" }.join(' or ')}, but none were found")
172:           end
173:         end
174:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.