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
The options hash. See {file:HAML_REFERENCE.md#haml_options the Haml options documentation}.
@return [{Symbol => Object}]
The indentation used in the Haml document, or `nil` if the indentation is ambiguous (for example, for a single-level document).
@return [String]
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
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
# 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
@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
@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
@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
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
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
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
# 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
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
# 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.
Generated with the Darkfish Rdoc Generator 1.1.6.