Class Haml::Engine
In: lib/haml/engine.rb
Parent: Object

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

Methods

Included Modules

Precompiler

Attributes

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]

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

@return [{Symbol => Object}]

Public Class methods

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

Public Instance methods

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<Symbol>] The names of the locals that can be passed to the proc

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

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

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

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]

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 `instance_eval` 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 [to_proc] A block that can be yielded to within the template @return [String] The rendered template

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<Symbol>] The names of the locals that can be passed to the proc @return [Proc] The proc that will run the template

to_html(scope = Object.new, locals = {}, &block)

Alias for render

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

Protected Instance methods

Returns a subset of \{options}: those that {Haml::Buffer} cares about. All of the values here are such that when `inspect` 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

[Validate]