module 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
Source
# File lib/haml/filters.rb, line 108 def self.included(base) Filters.defined[base.name.split("::").last.downcase] = base base.extend(base) end
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
Public Instance Methods
Source
# File lib/haml/filters.rb, line 162 def compile(compiler, text) filter = self compiler.instance_eval do if contains_interpolation?(text) return if options[:suppress_eval] escape = options[:escape_filter_interpolations] # `escape_filter_interpolations` defaults to `escape_html` if unset. escape = options[:escape_html] if escape.nil? text = unescape_interpolation(text, escape).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.to_s, compiler.options), compiler.options[:preserve]) push_text("#{rendered.rstrip}\n") end end
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::Compiler} instance to compile the string to Ruby
code that will be executed in the context of the active Haml
template.
Warning: the {Haml::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.
@param compiler [Haml::Compiler] The compiler instance @param text [String] The text of the filter @raise [Haml::Error] if none of {#compile}, {#render}, and
\{#render_with_options} are overridden
Source
# File lib/haml/filters.rb, line 142 def internal_compile(*args) compile(*args) end
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 compile
Source
# File lib/haml/filters.rb, line 123 def render(_text) raise Error.new("#{self.inspect}#render not defined!") end
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
Source
# File lib/haml/filters.rb, line 134 def render_with_options(text, _options) render(text) end
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 render
@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