Class List Method List File List

# 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.

## 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_html

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

- - filename

  The name of the Haml file being parsed.

- - 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.

- - ugly

  If set to `true`, Haml makes no attempt to properly indent or format the HTML output.

## Class Method Summary (collapse)

- + buffer_option_keys

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

- + defaults

  The default option values.

- + valid_formats

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

## Instance Method Summary (collapse)

- - [](key)

  Retrieve an option value.

- - []=(key, value)

  Set an option value.

- - ({Symbol => Object}) for_buffer

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

- - (Boolean) html4?

  Whether or not the format is HTML4.

- - (Boolean) html5?

  Whether or not the format is HTML5.

- - (Boolean) html?

  Whether or not the format is any flavor of HTML.

- - (Options) initialize(values = {}, &block) constructor

  A new instance of Options.

- - (Boolean) xhtml?

  Whether or not the format is XHTML.

## Constructor Details

### - (`Options`) initialize(values = {}, &block)

Returns a new instance of Options

    172
    173
    174
    175
    176

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

    def initialize(values = {}, &block)
      defaults.each {|k, v| instance_variable_set :"@#{k}", v}
      values.reject {|k, v| !defaults.has_key?(k) || v.nil?}.each {|k, v| send("#{k}=", v)}
      yield if block_given?
    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.

    57
    58
    59

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

    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']`.

    63
    64
    65

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

    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.

    164
    165
    166

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

    def cdata
      @cdata
    end

### - compiler_class

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

    170
    171
    172

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

    def compiler_class
      @compiler_class
    end

### - encoding

The encoding to use for the HTML output. Only available on Ruby 1.9 or higher. 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"`.

    73
    74
    75

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

    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`.

    82
    83
    84

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

    def escape_attrs
      @escape_attrs
    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.

    92
    93
    94

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

    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.

    98
    99
    100

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

    def filename
      @filename
    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`.

    119
    120
    121

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

    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`.

    103
    104
    105

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

    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`.

    107
    108
    109

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

    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`.

    124
    125
    126

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

    def mime_type
      @mime_type
    end

### - parser_class

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

    167
    168
    169

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

    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.

    132
    133
    134

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

    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`.

    140
    141
    142

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

    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`.

    147
    148
    149

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

    def suppress_eval
      @suppress_eval
    end

### - ugly

If set to `true`, Haml makes no attempt to properly indent or format the HTML output. This significantly improves rendering performance but makes viewing the source unpleasant.

Defaults to `true` in Rails production mode, and `false` everywhere else.

    154
    155
    156

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

    def ugly
      @ugly
    end

## Class Method Details

### + buffer_option_keys

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

Returns:

- Hash

    49
    50
    51

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

    def self.buffer_option_keys
      @buffer_option_keys
    end

### + defaults

The default option values.

Returns:

- Hash

    36
    37
    38

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

    def self.defaults
      @defaults
    end

### + valid_formats

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

Returns:

- Array

    42
    43
    44

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

    def self.valid_formats
      @valid_formats
    end

## Instance Method Details

### - [](key)

Retrieve an option value.

Parameters:

- key —

  The value to retrieve.

    180
    181
    182

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

    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.

    187
    188
    189

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

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

### - (`{Symbol => Object}`) for_buffer

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

    265
    266
    267
    268
    269
    270

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

    def for_buffer
      self.class.buffer_option_keys.inject({}) do |hash, key|
        hash[key] = send(key)
        hash
      end
    end

### - (`Boolean`) html4?

Returns Whether or not the format is HTML4.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML4.

    211
    212
    213

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

    def html4?
      format == :html4
    end

### - (`Boolean`) html5?

Returns Whether or not the format is HTML5.

Returns:

- (`Boolean`) —

  Whether or not the format is HTML5.

    216
    217
    218

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

    def html5?
      format == :html5
    end

### - (`Boolean`) html?

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

Returns:

- (`Boolean`) —

  Whether or not the format is any flavor of HTML.

    206
    207
    208

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

    def html?
      html4? or html5?
    end

### - (`Boolean`) xhtml?

Returns Whether or not the format is XHTML.

Returns:

- (`Boolean`) —

  Whether or not the format is XHTML.

    201
    202
    203

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

    def xhtml?
      not html?
    end