module Haml::Helpers

def self.action_view?

Returns:
  • (Boolean) - Whether or not ActionView is loaded
def self.action_view?
  @@action_view_defined
end

def block_is_haml?(block)

Returns:
  • (Boolean) - Whether or not `block` is defined directly in a Haml template

Parameters:
  • block (Proc) -- A Ruby block
def block_is_haml?(block)
  eval('!!defined?(_hamlout)', block.binding)
end

def capture_haml(*args, &block)

Other tags:
    Yieldparam: args - `args`

Other tags:
    Yield: - A block of Haml code that will be converted to a string

Parameters:
  • args (Array) -- Arguments to pass into the block
def capture_haml(*args, &block)
  buffer = eval('if defined? _hamlout then _hamlout else nil end', block.binding) || haml_buffer
  with_haml_buffer(buffer) do
    position = haml_buffer.buffer.length
    haml_buffer.capture_position = position
    value = block.call(*args)
    captured = haml_buffer.buffer.slice!(position..-1)
    if captured == '' and value != haml_buffer.buffer
      captured = (value.is_a?(String) ? value : nil)
    end
    captured
  end
ensure
  haml_buffer.capture_position = nil
end

def escape_once(text)

Returns:
  • (String) - The sanitized string

Parameters:
  • text (String) -- The string to sanitize
def escape_once(text)
  text = text.to_s
  text.gsub(HTML_ESCAPE_ONCE_REGEX, HTML_ESCAPE)
end

def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)

Other tags:
    Yield: - The block within which to escape newlines

Overloads:
  • find_and_preserve(tags = haml_buffer.options[:preserve])
  • find_and_preserve(input, tags = haml_buffer.options[:preserve])

Parameters:
  • input (String) -- The string within which to escape newlines
  • tags (Array) -- Tags that should have newlines escaped
def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
  return find_and_preserve(capture_haml(&block), input || tags) if block
  tags = tags.each_with_object('') do |t, s|
    s << '|' unless s.empty?
    s << Regexp.escape(t)
  end
  re = /<(#{tags})([^>]*)>(.*?)(<\/\1>)/im
  input.to_s.gsub(re) do |s|
    s =~ re # Can't rely on $1, etc. existing since Rails' SafeBuffer#gsub is incompatible
    "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
  end
end

def haml_bind_proc(&proc)

Returns:
  • (Proc) - A new proc with the new variables bound

Parameters:
  • proc (#call) -- The proc to bind
def haml_bind_proc(&proc)
  _hamlout = haml_buffer
  #double assignment is to avoid warnings
  _erbout = _erbout = _hamlout.buffer
  proc { |*args| proc.call(*args) }
end

def haml_buffer

Returns:
  • (Haml::Buffer) -
def haml_buffer
  @haml_buffer if defined? @haml_buffer
end

def haml_concat(text = "")

Parameters:
  • text (#to_s) -- The text to output
def haml_concat(text = "")
  haml_internal_concat text
  ErrorReturn.new("haml_concat")
end

def haml_indent

Returns:
  • (String) - The indentation string for the current line
def haml_indent
  '  ' * haml_buffer.tabulation
end

def haml_internal_concat(text = "", newline = true, indent = true)

Parameters:
  • indent (Boolean) -- Whether to add indentation to the first line
  • newline (Boolean) -- Whether to add a newline after the text
  • text (#to_s) -- The text to output
def haml_internal_concat(text = "", newline = true, indent = true)
  if haml_buffer.tabulation == 0
    haml_buffer.buffer << "#{text}#{"\n" if newline}"
  else
    haml_buffer.buffer << %[#{haml_indent if indent}#{text.to_s.gsub("\n", "\n#{haml_indent}")}#{"\n" if newline}]
  end
end

def haml_tag(name, *rest, &block)

Parameters:
  • flags (Array) -- Haml end-of-tag flags
  • text (#to_s) -- The text within the tag
  • name (#to_s) -- The name of the tag

Overloads:
  • haml_tag(name, text, *flags, attributes = {})
  • haml_tag(name, *rest, attributes = {})

Other tags:
    Yield: - The block of Haml code within the tag
def haml_tag(name, *rest, &block)
  ret = ErrorReturn.new("haml_tag")
  text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
  flags = []
  flags << rest.shift while rest.first.is_a? Symbol
  attrs = (rest.shift || {})
  attrs.keys.each {|key| attrs[key.to_s] = attrs.delete(key)} unless attrs.empty?
  name, attrs = merge_name_and_attributes(name.to_s, attrs)
  attributes = Haml::AttributeBuilder.build_attributes(haml_buffer.html?,
    haml_buffer.options[:attr_wrapper],
    haml_buffer.options[:escape_attrs],
    haml_buffer.options[:hyphenate_data_attrs],
    attrs)
  if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
    haml_internal_concat_raw "<#{name}#{attributes}#{' /' if haml_buffer.options[:format] == :xhtml}>"
    return ret
  end
  if flags.include?(:/)
    raise Error.new(Error.message(:self_closing_content)) if text
    raise Error.new(Error.message(:illegal_nesting_self_closing)) if block
  end
  tag = "<#{name}#{attributes}>"
  end_tag = "</#{name}>"
  if block.nil?
    text = text.to_s
    if text.include?("\n")
      haml_internal_concat_raw tag
      tab_up
      haml_internal_concat text
      tab_down
      haml_internal_concat_raw end_tag
    else
      haml_internal_concat_raw tag, false
      haml_internal_concat text, false, false
      haml_internal_concat_raw end_tag, true, false
    end
    return ret
  end
  if text
    raise Error.new(Error.message(:illegal_nesting_line, name))
  end
  if flags.include?(:<)
    haml_internal_concat_raw tag, false
    haml_internal_concat "#{capture_haml(&block).strip}", false, false
    haml_internal_concat_raw end_tag, true, false
    return ret
  end
  haml_internal_concat_raw tag
  tab_up
  block.call
  tab_down
  haml_internal_concat_raw end_tag
  ret
end

def haml_tag_if(condition, *tag)

Parameters:
  • tag () -- Definition of the enclosing tag. See \{#haml_tag} for details
  • condition () -- The condition to test to determine whether to render
def haml_tag_if(condition, *tag)
  if condition
    haml_tag(*tag){ yield }
  else
    yield
  end
  ErrorReturn.new("haml_tag_if")
end

def html_attrs(lang = 'en-US')

Returns:
  • ({#to_s => String}) - The attribute hash

Parameters:
  • lang (String) -- The value of `xml:lang` and `lang`
def html_attrs(lang = 'en-US')
  if haml_buffer.options[:format] == :xhtml
    {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
  else
    {:lang => lang}
  end
end

def html_escape(text)

Returns:
  • (String) - The sanitized string

Parameters:
  • text (String) -- The string to sanitize
def html_escape(text)
  ERB::Util.html_escape(text)
end

def init_haml_helpers


context.haml_tag :p, "Stuff"
context.init_haml_helpers
end
include Haml::Helpers
class << context
context = Object.new

For example:
other than the normal setup with ActionView.
This is useful if you want to use the helpers in a context
as a normal ActionView instance using Haml.
Initializes the current object as though it were in the same context

normally in Rails.
Note: this does **not** need to be called when using Haml helpers
def init_haml_helpers
  @haml_buffer = Haml::Buffer.new(haml_buffer, Options.new.for_buffer)
  nil
end

def is_haml?

Returns:
  • (Boolean) - Whether or not the current template is a Haml template
def is_haml?
  !@haml_buffer.nil? && @haml_buffer.active?
end

def list_of(enum, opts={}, &block)

Other tags:
    Yieldparam: item - An element of `enum`

Other tags:
    Yield: - A block which contains Haml code that goes within list items

Parameters:
  • opts (Enumerable<#to_s,#to_s>) -- Each key/value pair will become an attribute pair for each list item element.
  • enum (Enumerable) -- The list of objects to iterate over
def list_of(enum, opts={}, &block)
  opts_attributes = opts.each_with_object('') {|(k, v), s| s << " #{k}='#{v}'"}
  enum.each_with_object('') do |i, ret|
    result = capture_haml(i, &block)
    if result.count("\n") > 1
      result.gsub!("\n", "\n  ")
      result = "\n  #{result.strip!}\n"
    else
      result.strip!
    end
    ret << "\n" unless ret.empty?
    ret << %Q!<li#{opts_attributes}>#{result}</li>!
  end
end

def merge_name_and_attributes(name, attributes_hash = {})

and merges it with the Ruby attributes hash.
Parses the tag name used for \{#haml\_tag}
def merge_name_and_attributes(name, attributes_hash = {})
  # skip merging if no ids or classes found in name
  return name, attributes_hash unless name =~ /^(.+?)?([\.#].*)$/
  return $1 || "div", AttributeBuilder.merge_attributes!(
    Haml::Parser.parse_class_and_id($2), attributes_hash)
end

def non_haml

Other tags:
    Yield: - A block which won't register as Haml
def non_haml
  was_active = @haml_buffer.active?
  @haml_buffer.active = false
  yield
ensure
  @haml_buffer.active = was_active
end

def precede(str, &block)

Other tags:
    Yield: - A block of Haml to prepend to

Parameters:
  • str (String) -- The string to add before the Haml
def precede(str, &block)
  "#{str}#{capture_haml(&block).chomp}\n"
end

def preserve(input = nil, &block)

Other tags:
    Yield: - The block within which to escape newlines

Overloads:
  • preserve
  • preserve(input)

Parameters:
  • input (String) -- The string within which to escape all newlines
def preserve(input = nil, &block)
  return preserve(capture_haml(&block)) if block
  s = input.to_s.chomp("\n")
  s.gsub!(/\n/, '&#x000A;')
  s.delete!("\r")
  s
end

def succeed(str, &block)

Other tags:
    Yield: - A block of Haml to append to

Parameters:
  • str (String) -- The string to add after the Haml
def succeed(str, &block)
  "#{capture_haml(&block).chomp}#{str}\n"
end

def surround(front, back = front, &block)

Other tags:
    Yield: - A block of Haml to surround

Parameters:
  • back (String) -- The string to add after the Haml
  • front (String) -- The string to add before the Haml
def surround(front, back = front, &block)
  output = capture_haml(&block)
  "#{front}#{output.chomp}#{back}\n"
end

def tab_down(i = 1)

Other tags:
    See: #tab_up -

Parameters:
  • i (Fixnum) -- The number of tabs by which to decrease the indentation
def tab_down(i = 1)
  haml_buffer.tabulation -= i
end

def tab_up(i = 1)

Other tags:
    See: #tab_down -

Parameters:
  • i (Fixnum) -- The number of tabs by which to increase the indentation
def tab_up(i = 1)
  haml_buffer.tabulation += i
end

def with_haml_buffer(buffer)

Other tags:
    Yield: - A block in which the given buffer should be used

Parameters:
  • buffer (Haml::Buffer) -- The Haml buffer to use temporarily
def with_haml_buffer(buffer)
  @haml_buffer, old_buffer = buffer, @haml_buffer
  old_buffer.active, old_was_active = false, old_buffer.active? if old_buffer
  @haml_buffer.active, was_active = true, @haml_buffer.active?
  yield
ensure
  @haml_buffer.active = was_active
  old_buffer.active = old_was_active if old_buffer
  @haml_buffer = old_buffer
end

def with_tabs(i)

Other tags:
    Yield: - A block in which the indentation will be `i` spaces

Parameters:
  • i (Fixnum) -- The number of tabs to use
def with_tabs(i)
  old_tabs = haml_buffer.tabulation
  haml_buffer.tabulation = i
  yield
ensure
  haml_buffer.tabulation = old_tabs
end