# Class: Haml::Buffer

Inherits:
  Object
  - Object
  - Haml::Buffer
  show all

Includes:
  Helpers, Util

Defined in:
  lib/haml/buffer.rb

## Overview

This class is used only internally. It holds the buffer of HTML that is eventually output as the resulting document. It’s called from within the precompiled code, and helps reduce the amount of processing done within `instance_eval`ed code.

## Instance Attribute Summary collapse

- #active ⇒ Boolean writeonly
- #buffer ⇒ String

  The string that holds the compiled HTML.

- #capture_position ⇒ Fixnum?

  nil if there’s no capture_haml block running, and the position at which it’s beginning the capture if there is one.

- #options ⇒ {String => Object}

  The options hash passed in from Engine.

- #upper ⇒ Buffer

  The Buffer for the enclosing Haml document.

## Instance Method Summary collapse

- #active? ⇒ Boolean

  Whether or not this buffer is currently being used to render a Haml template.

- #adjust_tabs(tab_change)

  Modifies the indentation of the document.

- #html4? ⇒ Boolean

  Whether or not the format is HTML4.

- #html5? ⇒ Boolean

  Whether or not the format is HTML5.

- #html? ⇒ Boolean

  Whether or not the format is any flavor of HTML.

- #initialize(upper = nil, options = {}) ⇒ Buffer constructor

  A new instance of Buffer.

- #push_text(text, tab_change, dont_tab_up)

  Appends text to the buffer, properly tabulated.

- #rstrip!

  Remove the whitespace from the right side of the buffer string.

- #tabulation ⇒ Fixnum

  The current indentation level of the document.

- #tabulation=(val)

  Sets the current tabulation of the document.

- #toplevel? ⇒ Boolean

  Whether or not this buffer is a top-level template, as opposed to a nested partial.

- #xhtml? ⇒ Boolean

  Whether or not the format is XHTML.

### Methods included from Util

#balance, #check_encoding, #check_haml_encoding, #contains_interpolation?, #handle_interpolation, #html_safe, #human_indentation, #inspect_obj, #rails_xss_safe?, #silence_warnings, #unescape_interpolation

### Methods included from Helpers

action_view?, #block_is_haml?, #capture_haml, #escape_once, #find_and_preserve, #haml_concat, #haml_indent, #haml_tag, #haml_tag_if, #html_attrs, #html_escape, #init_haml_helpers, #is_haml?, #list_of, #non_haml, #precede, #preserve, #succeed, #surround, #tab_down, #tab_up, #with_tabs

### Methods included from Helpers::ActionViewExtensions

#page_class, #with_raw_haml_concat

## Constructor Details

### #initialize(upper = nil, options = {}) ⇒ `Buffer`

Returns a new instance of Buffer.

Parameters:

- upper (`Buffer`) (defaults to: `nil`) —

  The parent buffer

- options (`{Symbol => Object}`) (defaults to: `{}`) —

  An options hash. See Engine#options_for_buffer

    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103

    # File 'lib/haml/buffer.rb', line 92

    def initialize(upper = nil, options = {})
      @active     = true
      @upper      = upper
      @options    = Options.buffer_defaults
      @options    = @options.merge(options) unless options.empty?
      @buffer     = new_encoded_string
      @tabulation = 0

      # The number of tabs that Engine thinks we should have
      # @real_tabs + @tabulation is the number of tabs actually output
      @real_tabs = 0
    end

## Instance Attribute Details

### #active=(value) ⇒ `Boolean` (writeonly)

Returns:

- (`Boolean`)

See Also:

- #active?

    39
    40
    41

    # File 'lib/haml/buffer.rb', line 39

    def active=(value)
      @active = value
    end

### #buffer ⇒ `String`

The string that holds the compiled HTML. This is aliased as `_erbout` for compatibility with ERB-specific code.

Returns:

- (`String`)

    16
    17
    18

    # File 'lib/haml/buffer.rb', line 16

    def buffer
      @buffer
    end

### #capture_position ⇒ `Fixnum`?

nil if there’s no capture_haml block running, and the position at which it’s beginning the capture if there is one.

Returns:

- (`Fixnum`, `nil`)

    35
    36
    37

    # File 'lib/haml/buffer.rb', line 35

    def capture_position
      @capture_position
    end

### #options ⇒ `{String => Object}`

The options hash passed in from Engine.

Returns:

- (`{String => Object}`)

See Also:

- Options#for_buffer

    22
    23
    24

    # File 'lib/haml/buffer.rb', line 22

    def options
      @options
    end

### #upper ⇒ `Buffer`

The Haml::Buffer for the enclosing Haml document. This is set for partials and similar sorts of nested templates. It’s `nil` at the top level (see #toplevel?).

Returns:

- (`Buffer`)

    29
    30
    31

    # File 'lib/haml/buffer.rb', line 29

    def upper
      @upper
    end

## Instance Method Details

### #active? ⇒ `Boolean`

Whether or not this buffer is currently being used to render a Haml template. Returns `false` if a subtemplate is being rendered, even if it’s a subtemplate of this buffer’s template.

Returns:

- (`Boolean`)

    72
    73
    74

    # File 'lib/haml/buffer.rb', line 72

    def active?
      @active
    end

### #adjust_tabs(tab_change)

Modifies the indentation of the document.

Parameters:

- tab_change (`Fixnum`) —

  The number of tabs by which to increase or decrease the document’s indentation

    129
    130
    131

    # File 'lib/haml/buffer.rb', line 129

    def adjust_tabs(tab_change)
      @real_tabs += tab_change
    end

### #html4? ⇒ `Boolean`

Returns Whether or not the format is HTML4.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML4

    52
    53
    54

    # File 'lib/haml/buffer.rb', line 52

    def html4?
      @options[:format] == :html4
    end

### #html5? ⇒ `Boolean`

Returns Whether or not the format is HTML5.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML5.

    57
    58
    59

    # File 'lib/haml/buffer.rb', line 57

    def html5?
      @options[:format] == :html5
    end

### #html? ⇒ `Boolean`

Returns Whether or not the format is any flavor of HTML.

Returns:

- (`Boolean`) —

  Whether or not the format is any flavor of HTML

    47
    48
    49

    # File 'lib/haml/buffer.rb', line 47

    def html?
      html4? or html5?
    end

### #push_text(text, tab_change, dont_tab_up)

Appends text to the buffer, properly tabulated. Also modifies the document’s indentation.

Parameters:

- text (`String`) —

  The text to append

- tab_change (`Fixnum`) —

  The number of tabs by which to increase or decrease the document’s indentation

- dont_tab_up (`Boolean`) —

  If true, don’t indent the first line of `text`

    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123

    # File 'lib/haml/buffer.rb', line 112

    def push_text(text, tab_change, dont_tab_up)
      if @tabulation > 0
        # Have to push every line in by the extra user set tabulation.
        # Don't push lines with just whitespace, though,
        # because that screws up precompiled indentation.
        text.gsub!(/^(?!\s+$)/m, tabs)
        text.sub!(tabs, '') if dont_tab_up
      end

      @real_tabs += tab_change
      @buffer << text
    end

### #rstrip!

Remove the whitespace from the right side of the buffer string. Doesn’t do anything if we’re at the beginning of a capture_haml block.

    135
    136
    137
    138
    139
    140
    141
    142

    # File 'lib/haml/buffer.rb', line 135

    def rstrip!
      if capture_position.nil?
        buffer.rstrip!
        return
      end

      buffer << buffer.slice!(capture_position..-1).rstrip
    end

### #tabulation ⇒ `Fixnum`

Returns The current indentation level of the document.

Returns:

- (`Fixnum`) —

  The current indentation level of the document

    77
    78
    79

    # File 'lib/haml/buffer.rb', line 77

    def tabulation
      @real_tabs + @tabulation
    end

### #tabulation=(val)

Sets the current tabulation of the document.

Parameters:

- val (`Fixnum`) —

  The new tabulation

    84
    85
    86
    87

    # File 'lib/haml/buffer.rb', line 84

    def tabulation=(val)
      val = val - @real_tabs
      @tabulation = val > -1 ? val : 0
    end

### #toplevel? ⇒ `Boolean`

Returns Whether or not this buffer is a top-level template, as opposed to a nested partial.

Returns:

- (`Boolean`) —

  Whether or not this buffer is a top-level template, as opposed to a nested partial

    63
    64
    65

    # File 'lib/haml/buffer.rb', line 63

    def toplevel?
      upper.nil?
    end

### #xhtml? ⇒ `Boolean`

Returns Whether or not the format is XHTML.

Returns:

- (`Boolean`) —

  Whether or not the format is XHTML

    42
    43
    44

    # File 'lib/haml/buffer.rb', line 42

    def xhtml?
      not html?
    end