Module | Haml::Filters::Base |
In: |
lib/haml/filters.rb
|
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.
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.
# 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
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
# File lib/haml/filters.rb, line 110 110: def lazy_require(*reqs) 111: @lazy_requires = reqs 112: end
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.
# File lib/haml/filters.rb, line 44 44: def render(text) 45: raise Error.new("#{self.inspect}#render not defined!") 46: end