Parent

Included Modules

Haml::Engine

This is the frontend for using Haml programmatically. It can be directly used by the user by creating a new instance and calling {#render} to render the template. For example:

    template = File.read('templates/really_cool_template.haml')
    haml_engine = Haml::Engine.new(template)
    output = haml_engine.render
    puts output

Attributes

options[RW]

The options hash. See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.

@return [{Symbol => Object}]

indentation[RW]

The indentation used in the Haml document, or `nil` if the indentation is ambiguous (for example, for a single-level document).

@return [String]

Public Class Methods

new(template, options = {}) click to toggle source

Precompiles the Haml template.

@param template [String] The Haml template @param options [{Symbol => Object}] An options hash;

  see {file:HAML_REFERENCE.md#haml_options the Haml options documentation}

@raise [Haml::Error] if there’s a Haml syntax error in the template

     # File lib/haml/engine.rb, line 74
 74:     def initialize(template, options = {})
 75:       @options = {
 76:         :suppress_eval => false,
 77:         :attr_wrapper => "'",
 78: 
 79:         # Don't forget to update the docs in doc-src/HAML_REFERENCE.md
 80:         # if you update these
 81:         :autoclose => ]meta img link br hr input area param col base],
 82:         :preserve => ]textarea pre code],
 83: 
 84:         :filename => '(haml)',
 85:         :line => 1,
 86:         :ugly => false,
 87:         :format => :xhtml,
 88:         :escape_html => false,
 89:         :escape_attrs => true,
 90:       }
 91: 
 92: 
 93:       template = check_haml_encoding(template) do |msg, line|
 94:         raise Haml::Error.new(msg, line)
 95:       end
 96: 
 97:       unless ruby1_8?
 98:         @options[:encoding] = Encoding.default_internal || template.encoding
 99:         @options[:encoding] = "utf-8" if @options[:encoding].name == "US-ASCII"
100:       end
101:       @options.merge! options.reject {|k, v| v.nil?}
102:       @index = 0
103: 
104:       unless [:xhtml, :html4, :html5].include?(@options[:format])
105:         raise Haml::Error, "Invalid output format #{@options[:format].inspect}"
106:       end
107: 
108:       if @options[:encoding] && @options[:encoding].is_a?(Encoding)
109:         @options[:encoding] = @options[:encoding].name
110:       end
111: 
112:       # :eod is a special end-of-document marker
113:       @template = (template.rstrip).split(/\r\n|\r|\n/) + [:eod, :eod]
114:       @template_index = 0
115:       @to_close_stack = []
116:       @output_tabs = 0
117:       @template_tabs = 0
118:       @flat = false
119:       @newlines = 0
120:       @precompiled = ''
121:       @to_merge = []
122:       @tab_change  = 0
123: 
124:       compile(parse)
125:     rescue Haml::Error => e
126:       if @index || e.line
127:         e.backtrace.unshift "#{@options[:filename]}:#{(e.line ? e.line + 1 : @index) + @options[:line] - 1}"
128:       end
129:       raise
130:     end

Public Instance Methods

def_method(object, name, *local_names) click to toggle source

Defines a method on `object` with the given name that renders the template and returns the result as a string.

If `object` is a class or module, the method will instead by defined as an instance method. For example:

    t = Time.now
    Haml::Engine.new("%p\n  Today's date is\n  .date= self.to_s").def_method(t, :render)
    t.render #=> "<p>\n  Today's date is\n  <div class='date'>Fri Nov 23 18:28:29 -0800 2007</div>\n</p>\n"

    Haml::Engine.new(".upcased= upcase").def_method(String, :upcased_div)
    "foobar".upcased_div #=> "<div class='upcased'>FOOBAR</div>\n"

The first argument of the defined method is a hash of local variable names to values. However, due to an unfortunate Ruby quirk, the local variables which can be assigned must be pre-declared. This is done with the `local_names` argument. For example:

    # This works
    obj = Object.new
    Haml::Engine.new("%p= foo").def_method(obj, :render, :foo)
    obj.render(:foo => "Hello!") #=> "<p>Hello!</p>"

    # This doesn't
    obj = Object.new
    Haml::Engine.new("%p= foo").def_method(obj, :render)
    obj.render(:foo => "Hello!") #=> NameError: undefined local variable or method `foo'

Note that Haml modifies the evaluation context (either the scope object or the `self` object of the scope binding). It extends {Haml::Helpers}, and various instance variables are set (all prefixed with `haml_`).

@param object [Object, Module] The object on which to define the method @param name [String, Symbol] The name of the method to define @param local_names [Array] The names of the locals that can be passed to the proc

     # File lib/haml/engine.rb, line 275
275:     def def_method(object, name, *local_names)
276:       method = object.is_a?(Module) ? :module_eval : :instance_eval
277: 
278:       object.send(method, "def #{name}(_haml_locals = {}); #{precompiled_with_ambles(local_names)}; end",
279:                   @options[:filename], @options[:line])
280:     end
html4?() click to toggle source

@return [Boolean] Whether or not the format is HTML4.

    # File lib/haml/engine.rb, line 46
46:     def html4?
47:       @options[:format] == :html4
48:     end
html5?() click to toggle source

@return [Boolean] Whether or not the format is HTML5.

    # File lib/haml/engine.rb, line 51
51:     def html5?
52:       @options[:format] == :html5
53:     end
html?() click to toggle source

@return [Boolean] Whether or not the format is any flavor of HTML.

    # File lib/haml/engine.rb, line 41
41:     def html?
42:       html4? or html5?
43:     end
precompiled() click to toggle source

The source code that is evaluated to produce the Haml document.

In Ruby 1.9, this is automatically converted to the correct encoding (see {file:HAML_REFERENCE.md#encoding-option the `:encoding` option}).

@return [String]

    # File lib/haml/engine.rb, line 61
61:     def precompiled
62:       return @precompiled if ruby1_8?
63:       encoding = Encoding.find(@options[:encoding])
64:       return @precompiled.force_encoding(encoding) if encoding == Encoding::BINARY
65:       return @precompiled.encode(encoding)
66:     end
render(scope = Object.new, locals = {}, &block) click to toggle source

Processes the template and returns the result as a string.

`scope` is the context in which the template is evaluated. If it’s a `Binding` or `Proc` object, Haml uses it as the second argument to `Kernel#eval`; otherwise, Haml just uses its `#` context.

Note that Haml modifies the evaluation context (either the scope object or the `self` object of the scope binding). It extends {Haml::Helpers}, and various instance variables are set (all prefixed with `haml_`). For example:

    s = "foobar"
    Haml::Engine.new("%p= upcase").render(s) #=> "<p>FOOBAR</p>"

    # s now extends Haml::Helpers
    s.respond_to?(:html_attrs) #=> true

`locals` is a hash of local variables to make available to the template. For example:

    Haml::Engine.new("%p= foo").render(Object.new, :foo => "Hello, world!") #=> "<p>Hello, world!</p>"

If a block is passed to render, that block is run when `yield` is called within the template.

Due to some Ruby quirks, if `scope` is a `Binding` or `Proc` object and a block is given, the evaluation context may not be quite what the user expects. In particular, it’s equivalent to passing `eval(“self”, scope)` as `scope`. This won’t have an effect in most cases, but if you’re relying on local variables defined in the context of `scope`, they won’t work.

@param scope [Binding, Proc, Object] The context in which the template is evaluated @param locals [{Symbol => Object}] Local variables that will be made available

  to the template

@param block [#] A block that can be yielded to within the template @return [String] The rendered template

     # File lib/haml/engine.rb, line 173
173:     def render(scope = Object.new, locals = {}, &block)
174:       buffer = Haml::Buffer.new(scope.instance_variable_get('@haml_buffer'), options_for_buffer)
175: 
176:       if scope.is_a?(Binding) || scope.is_a?(Proc)
177:         scope_object = eval("self", scope)
178:         scope = scope_object.instance_eval{binding} if block_given?
179:       else
180:         scope_object = scope
181:         scope = scope_object.instance_eval{binding}
182:       end
183: 
184:       set_locals(locals.merge(:_hamlout => buffer, :_erbout => buffer.buffer), scope, scope_object)
185: 
186:       scope_object.instance_eval do
187:         extend Haml::Helpers
188:         @haml_buffer = buffer
189:       end
190: 
191:       eval(precompiled + ";" + precompiled_method_return_value,
192:         scope, @options[:filename], @options[:line])
193:     ensure
194:       # Get rid of the current buffer
195:       scope_object.instance_eval do
196:         @haml_buffer = buffer.upper if buffer
197:       end
198:     end
Also aliased as: to_html
render_proc(scope = Object.new, *local_names) click to toggle source

Returns a proc that, when called, renders the template and returns the result as a string.

`scope` works the same as it does for render.

The first argument of the returned proc is a hash of local variable names to values. However, due to an unfortunate Ruby quirk, the local variables which can be assigned must be pre-declared. This is done with the `local_names` argument. For example:

    # This works
    Haml::Engine.new("%p= foo").render_proc(Object.new, :foo).call :foo => "Hello!"
      #=> "<p>Hello!</p>"

    # This doesn't
    Haml::Engine.new("%p= foo").render_proc.call :foo => "Hello!"
      #=> NameError: undefined local variable or method `foo'

The proc doesn’t take a block; any yields in the template will fail.

@param scope [Binding, Proc, Object] The context in which the template is evaluated @param local_names [Array] The names of the locals that can be passed to the proc @return [Proc] The proc that will run the template

     # File lib/haml/engine.rb, line 225
225:     def render_proc(scope = Object.new, *local_names)
226:       if scope.is_a?(Binding) || scope.is_a?(Proc)
227:         scope_object = eval("self", scope)
228:       else
229:         scope_object = scope
230:         scope = scope_object.instance_eval{binding}
231:       end
232: 
233:       eval("Proc.new { |*_haml_locals| _haml_locals = _haml_locals[0] || {};" +
234:            precompiled_with_ambles(local_names) + "}\n", scope, @options[:filename], @options[:line])
235:     end
to_html(scope = Object.new, locals = {}, &block) click to toggle source
Alias for: render
xhtml?() click to toggle source

@return [Boolean] Whether or not the format is XHTML.

    # File lib/haml/engine.rb, line 36
36:     def xhtml?
37:       not html?
38:     end

Protected Instance Methods

options_for_buffer() click to toggle source

Returns a subset of {#options}: those that {Haml::Buffer} cares about. All of the values here are such that when `#` is called on the hash, it can be `Kernel#eval`ed to get the same result back.

See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.

@return [{Symbol => Object}] The options hash

     # File lib/haml/engine.rb, line 291
291:     def options_for_buffer
292:       {
293:         :autoclose => @options[:autoclose],
294:         :preserve => @options[:preserve],
295:         :attr_wrapper => @options[:attr_wrapper],
296:         :ugly => @options[:ugly],
297:         :format => @options[:format],
298:         :encoding => @options[:encoding],
299:         :escape_html => @options[:escape_html],
300:         :escape_attrs => @options[:escape_attrs],
301:       }
302:     end

Private Instance Methods

set_locals(locals, scope, scope_object) click to toggle source
     # File lib/haml/engine.rb, line 306
306:     def set_locals(locals, scope, scope_object)
307:       scope_object.send(:instance_variable_set, '@_haml_locals', locals)
308:       set_locals = locals.keys.map { |k| "#{k} = @_haml_locals[#{k.inspect}]" }.join("\n")
309:       eval(set_locals, scope)
310:     end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.