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.
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.
Class Method Summary collapse
-
.included(base) ⇒ Object
This method is automatically called when Base is included in a module.
Instance Method Summary collapse
-
#compile(precompiler, text) ⇒ Object
This should be overridden when a filter needs to have access to the Haml evaluation context.
-
#internal_compile(*args) ⇒ Object
Same as #compile, but requires the necessary files first.
-
#lazy_require(*reqs) ⇒ Object
This becomes a class method of modules that include Base.
-
#render(text) ⇒ String
Takes the source text that should be passed to the filter and returns the result of running the filter on that string.
- #render_with_options(text, options) ⇒ String
Class Method Details
.included(base) ⇒ Object
This method is automatically called when Haml::Filters::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
.
44 45 46 47 |
# File 'lib/haml/filters.rb', line 44
def self.included(base)
Filters.defined[base.name.split("::").last.downcase] = base
base.extend(base)
end
|
Instance Method Details
#compile(precompiler, text) ⇒ Object
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 Precompiler instance to compile the string to Ruby code that will be executed in the context of the active Haml template.
Warning: the 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.
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 |
# File 'lib/haml/filters.rb', line 96
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, :escape_html => 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
78 79 80 81 |
# File 'lib/haml/filters.rb', line 78
def internal_compile(*args)
resolve_lazy_requires
compile(*args)
end
|
#lazy_require(*reqs) ⇒ Object
This becomes a class method of modules that include Haml::Filters::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
135 136 137 |
# File 'lib/haml/filters.rb', line 135
def lazy_require(*reqs)
@lazy_requires = reqs
end
|
#render(text) ⇒ String
59 60 61 |
# File 'lib/haml/filters.rb', line 59
def render(text)
raise Error.new("#{self.inspect}#render not defined!")
end
|
#render_with_options(text, options) ⇒ String
Same as #render, but takes a Engine options hash as well. It's only safe to rely on options made available in Engine#options_for_buffer.
70 71 72 |
# File 'lib/haml/filters.rb', line 70
def render_with_options(text, options)
render(text)
end
|