# Class: Haml::Options

Inherits:
  Object
  - Object
  - Haml::Options
  show all

Defined in:
  lib/haml/options.rb

## Overview

This class encapsulates all of the configuration options that Haml understands. Please see the Haml Reference to learn how to set the options.

## Class Attribute Summary collapse

- .buffer_option_keys readonly

  An array of keys that will be used to provide a hash of options to Buffer.

- .valid_formats readonly

  An array of valid values for the `:format` option.

## Instance Attribute Summary collapse

- #attr_wrapper

  The character that should wrap element attributes.

- #autoclose

  A list of tag names that should be automatically self-closed if they have no content.

- #cdata

  Whether to include CDATA sections around javascript and css blocks when using the `:javascript` or `:css` filters.

- #compiler_class

  The compiler class to use.

- #encoding

  The encoding to use for the HTML output.

- #escape_attrs

  Sets whether or not to escape HTML-sensitive characters in attributes.

- #escape_filter_interpolations

  Sets whether or not to escape HTML-sensitive characters in interpolated strings.

- #escape_html

  Sets whether or not to escape HTML-sensitive characters in script.

- #filename

  The name of the Haml file being parsed.

- #filters

  Key is filter name in String and value is Class to use.

- #format

  Determines the output format.

- #hyphenate_data_attrs

  If set to `true`, Haml will convert underscores to hyphens in all Custom Data Attributes As of Haml 4.0, this defaults to `true`.

- #line

  The line offset of the Haml template being parsed.

- #mime_type

  The mime type that the rendered document will be served with.

- #parser_class

  The parser class to use.

- #preserve

  A list of tag names that should automatically have their newlines preserved using the Helpers#preserve helper.

- #remove_whitespace

  If set to `true`, all tags are treated as if both whitespace removal options were present.

- #suppress_eval

  Whether or not attribute hashes and Ruby scripts designated by `=` or `~` should be evaluated.

- #trace

  Enable template tracing.

## Class Method Summary collapse

- .buffer_defaults ⇒ {Symbol => Object}

  Returns a subset of defaults: those that Buffer cares about.

- .defaults

  The default option values.

- .wrap(options)

## Instance Method Summary collapse

- #[](key)

  Retrieve an option value.

- #[]=(key, value)

  Set an option value.

- #for_buffer ⇒ {Symbol => Object}

  Returns a non-default subset of options: those that Buffer cares about.

- #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(values = {}) ⇒ Options constructor

  A new instance of Options.

- #xhtml? ⇒ Boolean

  Whether or not the format is XHTML.

## Constructor Details

### #initialize(values = {}) ⇒ `Options`

Returns a new instance of Options.

    174
    175
    176
    177
    178

    # File 'lib/haml/options.rb', line 174

    def initialize(values = {})
      defaults.each {|k, v| instance_variable_set :"@#{k}", v}
      values.each {|k, v| send("#{k}=", v) if defaults.has_key?(k) && !v.nil?}
      yield if block_given?
    end

## Class Attribute Details

### .buffer_option_keys (readonly)

An array of keys that will be used to provide a hash of options to Buffer.

Returns:

- Hash

    26
    27
    28

    # File 'lib/haml/options.rb', line 26

    def buffer_option_keys
      @buffer_option_keys
    end

### .valid_formats (readonly)

An array of valid values for the `:format` option.

Returns:

- Array

    21
    22
    23

    # File 'lib/haml/options.rb', line 21

    def valid_formats
      @valid_formats
    end

## Instance Attribute Details

### #attr_wrapper

The character that should wrap element attributes. This defaults to `'` (an apostrophe). Characters of this type within the attributes will be escaped (e.g. by replacing them with `&apos;`) if the character is an apostrophe or a quotation mark.

    49
    50
    51

    # File 'lib/haml/options.rb', line 49

    def attr_wrapper
      @attr_wrapper
    end

### #autoclose

A list of tag names that should be automatically self-closed if they have no content. This can also contain regular expressions that match tag names (or any object which responds to `#===`). Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.

    55
    56
    57

    # File 'lib/haml/options.rb', line 55

    def autoclose
      @autoclose
    end

### #cdata

Whether to include CDATA sections around javascript and css blocks when using the `:javascript` or `:css` filters.

This option also affects the `:sass`, `:scss`, `:less` and `:coffeescript` filters.

Defaults to `false` for html, `true` for xhtml. Cannot be changed when using xhtml.

    155
    156
    157

    # File 'lib/haml/options.rb', line 155

    def cdata
      @cdata
    end

### #compiler_class

The compiler class to use. Defaults to Haml::Compiler.

    161
    162
    163

    # File 'lib/haml/options.rb', line 161

    def compiler_class
      @compiler_class
    end

### #encoding

The encoding to use for the HTML output. This can be a string or an `Encoding` Object. Note that Haml does not automatically re-encode Ruby values; any strings coming from outside the application should be converted before being passed into the Haml template. Defaults to `Encoding.default_internal`; if that’s not set, defaults to the encoding of the Haml template; if that’s `US-ASCII`, defaults to `"UTF-8"`.

    64
    65
    66

    # File 'lib/haml/options.rb', line 64

    def encoding
      @encoding
    end

### #escape_attrs

Sets whether or not to escape HTML-sensitive characters in attributes. If this is true, all HTML-sensitive characters in attributes are escaped. If it’s set to false, no HTML-sensitive characters in attributes are escaped. If it’s set to `:once`, existing HTML escape sequences are preserved, but other HTML-sensitive characters are escaped.

Defaults to `true`.

    73
    74
    75

    # File 'lib/haml/options.rb', line 73

    def escape_attrs
      @escape_attrs
    end

### #escape_filter_interpolations

Sets whether or not to escape HTML-sensitive characters in interpolated strings. See also Escaping HTML and Unescaping HTML.

Defaults to the current value of `escape_html`.

    90
    91
    92

    # File 'lib/haml/options.rb', line 90

    def escape_filter_interpolations
      @escape_filter_interpolations
    end

### #escape_html

Sets whether or not to escape HTML-sensitive characters in script. If this is true, `=` behaves like `&=`; otherwise, it behaves like `!=`. Note that if this is set, `!=` should be used for yielding to subtemplates and rendering partials. See also Escaping HTML and Unescaping HTML.

Defaults to false.

    83
    84
    85

    # File 'lib/haml/options.rb', line 83

    def escape_html
      @escape_html
    end

### #filename

The name of the Haml file being parsed. This is only used as information when exceptions are raised. This is automatically assigned when working through ActionView, so it’s really only useful for the user to assign when dealing with Haml programatically.

    96
    97
    98

    # File 'lib/haml/options.rb', line 96

    def filename
      @filename
    end

### #filters

Key is filter name in String and value is Class to use. Defaults to {}.

    172
    173
    174

    # File 'lib/haml/options.rb', line 172

    def filters
      @filters
    end

### #format

Determines the output format. The default is `:html5`. The other options are `:html4` and `:xhtml`. If the output is set to XHTML, then Haml automatically generates self-closing tags and wraps the output of the Javascript and CSS-like filters inside CDATA. When the output is set to `:html5` or `:html4`, XML prologs are ignored. In all cases, an appropriate doctype is generated from `!!!`.

If the mime_type of the template being rendered is `text/xml` then a format of `:xhtml` will be used even if the global output format is set to `:html4` or `:html5`.

    117
    118
    119

    # File 'lib/haml/options.rb', line 117

    def format
      @format
    end

### #hyphenate_data_attrs

If set to `true`, Haml will convert underscores to hyphens in all Custom Data Attributes As of Haml 4.0, this defaults to `true`.

    101
    102
    103

    # File 'lib/haml/options.rb', line 101

    def hyphenate_data_attrs
      @hyphenate_data_attrs
    end

### #line

The line offset of the Haml template being parsed. This is useful for inline templates, similar to the last argument to `Kernel#eval`.

    105
    106
    107

    # File 'lib/haml/options.rb', line 105

    def line
      @line
    end

### #mime_type

The mime type that the rendered document will be served with. If this is set to `text/xml` then the format will be overridden to `:xhtml` even if it has set to `:html4` or `:html5`.

    122
    123
    124

    # File 'lib/haml/options.rb', line 122

    def mime_type
      @mime_type
    end

### #parser_class

The parser class to use. Defaults to Haml::Parser.

    158
    159
    160

    # File 'lib/haml/options.rb', line 158

    def parser_class
      @parser_class
    end

### #preserve

A list of tag names that should automatically have their newlines preserved using the Helpers#preserve helper. This means that any content given on the same line as the tag will be preserved. For example, `%textarea= "Foo\nBar"` compiles to `<textarea>Foo&#x000A;Bar</textarea>`. Defaults to `['textarea', 'pre']`. See also Whitespace Preservation.

    130
    131
    132

    # File 'lib/haml/options.rb', line 130

    def preserve
      @preserve
    end

### #remove_whitespace

If set to `true`, all tags are treated as if both whitespace removal options were present. Use with caution as this may cause whitespace-related formatting errors.

Defaults to `false`.

    138
    139
    140

    # File 'lib/haml/options.rb', line 138

    def remove_whitespace
      @remove_whitespace
    end

### #suppress_eval

Whether or not attribute hashes and Ruby scripts designated by `=` or `~` should be evaluated. If this is `true`, said scripts are rendered as empty strings.

Defaults to `false`.

    145
    146
    147

    # File 'lib/haml/options.rb', line 145

    def suppress_eval
      @suppress_eval
    end

### #trace

Enable template tracing. If true, it will add a ‘data-trace’ attribute to each tag generated by Haml. The value of the attribute will be the source template name and the line number from which the tag was generated, separated by a colon. On Rails applications, the path given will be a relative path as from the views directory. On non-Rails applications, the path will be the full path.

    169
    170
    171

    # File 'lib/haml/options.rb', line 169

    def trace
      @trace
    end

## Class Method Details

### .buffer_defaults ⇒ `{Symbol => Object}`

Returns a subset of defaults: those that Buffer cares about.

Returns:

- (`{Symbol => Object}`) —

  The options hash

    30
    31
    32
    33
    34

    # File 'lib/haml/options.rb', line 30

    def buffer_defaults
      @buffer_defaults ||= buffer_option_keys.inject({}) do |hash, key|
        hash.merge(key => defaults[key])
      end
    end

### .defaults

The default option values.

Returns:

- Hash

    15
    16
    17

    # File 'lib/haml/options.rb', line 15

    def defaults
      @defaults ||= Haml::TempleEngine.options.to_hash.merge(encoding: 'UTF-8')
    end

### .wrap(options)

    36
    37
    38
    39
    40
    41
    42

    # File 'lib/haml/options.rb', line 36

    def wrap(options)
      if options.is_a?(Options)
        options
      else
        Options.new(options)
      end
    end

## Instance Method Details

### #[](key)

Retrieve an option value.

Parameters:

- key —

  The value to retrieve.

    182
    183
    184

    # File 'lib/haml/options.rb', line 182

    def [](key)
      send key
    end

### #[]=(key, value)

Set an option value.

Parameters:

- key —

  The key to set.

- value —

  The value to set for the key.

    189
    190
    191

    # File 'lib/haml/options.rb', line 189

    def []=(key, value)
      send "#{key}=", value
    end

### #for_buffer ⇒ `{Symbol => Object}`

Returns a non-default subset of options: those that 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 the Haml options documentation.

Returns:

- (`{Symbol => Object}`) —

  The options hash

    257
    258
    259
    260
    261
    262
    263
    264
    265

    # File 'lib/haml/options.rb', line 257

    def for_buffer
      self.class.buffer_option_keys.inject({}) do |hash, key|
        value = public_send(key)
        if self.class.buffer_defaults[key] != value
          hash[key] = value
        end
        hash
      end
    end

### #html4? ⇒ `Boolean`

Returns Whether or not the format is HTML4.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML4.

    212
    213
    214

    # File 'lib/haml/options.rb', line 212

    def html4?
      format == :html4
    end

### #html5? ⇒ `Boolean`

Returns Whether or not the format is HTML5.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML5.

    217
    218
    219

    # File 'lib/haml/options.rb', line 217

    def html5?
      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.

    207
    208
    209

    # File 'lib/haml/options.rb', line 207

    def html?
      html4? or html5?
    end

### #xhtml? ⇒ `Boolean`

Returns Whether or not the format is XHTML.

Returns:

- (`Boolean`) —

  Whether or not the format is XHTML.

    202
    203
    204

    # File 'lib/haml/options.rb', line 202

    def xhtml?
      not html?
    end