Module Haml::Util
In: lib/haml/util/subset_map.rb
lib/haml/util.rb

A module containing various useful functions.

Methods

Classes and Modules

Class Haml::Util::SubsetMap

Constants

RUBY_VERSION = ::RUBY_VERSION.split(".").map {|s| s.to_i}   An array of ints representing the Ruby version number. @api public
RUBY_ENGINE = defined?(::RUBY_ENGINE) ? ::RUBY_ENGINE : "ruby"   The Ruby engine we‘re running under. Defaults to `"ruby"` if the top-level constant is undefined. @api public
ENCODINGS_TO_CHECK = %w[UTF-8 UTF-16BE UTF-16LE UTF-32BE UTF-32LE]   We could automatically add in any non-ASCII-compatible encodings here, but there‘s not really a good way to do that without manually checking that each encoding encodes all ASCII characters properly, which takes long enough to affect the startup time of the CLI.
CHARSET_REGEXPS = Hash.new do |h, e| h[e] = begin # /\A(?:\uFEFF)?@charset "(.*?)"|\A(\uFEFF)/ Regexp.new(/\A(?:#{_enc("\uFEFF", e)})?#{ _enc('@charset "', e)}(.*?)#{_enc('"', e)}|\A(#{ _enc("\uFEFF", e)})/)

Public Instance methods

Returns whether this environment is using ActionPack of a version greater than or equal to that specified.

@param version [String] The string version number to check against.

  Should be greater than or equal to Rails 3,
  because otherwise ActionPack::VERSION isn't autoloaded

@return [Boolean]

Returns whether this environment is using ActionPack version 3.0.0 or greater.

@return [Boolean]

Assert that a given object (usually a String) is HTML safe according to Rails’ XSS handling, if it‘s loaded.

@param text [Object]

Returns an ActionView::Template* class. In pre-3.0 versions of Rails, most of these classes were of the form `ActionView::TemplateFoo`, while afterwards they were of the form `ActionView;:Template::Foo`.

@param name [to_s] The name of the class to get.

  For example, `:Error` will return `ActionView::TemplateError`
  or `ActionView::Template::Error`.

Returns information about the caller of the previous method.

@param entry [String] An entry in the `caller` list, or a similarly formatted string @return [[String, Fixnum, (String, nil)]] An array containing the filename, line, and method name of the caller.

  The method name may be nil

Checks that the encoding of a string is valid in Ruby 1.9 and cleans up potential encoding gotchas like the UTF-8 BOM. If it‘s not, yields an error string describing the invalid character and the line on which it occurrs.

@param str [String] The string of which to check the encoding @yield [msg] A block in which an encoding error can be raised.

  Only yields if there is an encoding error

@yieldparam msg [String] The error message to be raised @return [String] `str`, potentially with encoding gotchas like BOMs removed

Like {\check_encoding}, but also checks for a Ruby-style `-# coding:` comment at the beginning of the template and uses that encoding if it exists.

The Sass encoding rules are simple. If a `-# coding:` comment exists, we assume that that‘s the original encoding of the document. Otherwise, we use whatever encoding Ruby has.

Haml uses the same rules for parsing coding comments as Ruby. This means that it can understand Emacs-style comments (e.g. `-*- encoding: "utf-8" -*-`), and also that it cannot understand non-ASCII-compatible encodings such as `UTF-16` and `UTF-32`.

@param str [String] The Haml template of which to check the encoding @yield [msg] A block in which an encoding error can be raised.

  Only yields if there is an encoding error

@yieldparam msg [String] The error message to be raised @return [String] The original string encoded properly @raise [ArgumentError] if the document declares an unknown encoding

Like {\check_encoding}, but also checks for a `@charset` declaration at the beginning of the file and uses that encoding if it exists.

The Sass encoding rules are simple. If a `@charset` declaration exists, we assume that that‘s the original encoding of the document. Otherwise, we use whatever encoding Ruby has. Then we convert that to UTF-8 to process internally. The UTF-8 end result is what‘s returned by this method.

@param str [String] The string of which to check the encoding @yield [msg] A block in which an encoding error can be raised.

  Only yields if there is an encoding error

@yieldparam msg [String] The error message to be raised @return [(String, Encoding)] The original string encoded as UTF-8,

  and the source encoding of the string (or `nil` under Ruby 1.8)

@raise [Encoding::UndefinedConversionError] if the source encoding

  cannot be converted to UTF-8

@raise [ArgumentError] if the document uses an unknown encoding with `@charset`

The same as `Kernel#warn`, but is silenced by \{silence_haml_warnings}.

@param msg [String]

Returns the given text, marked as being HTML-safe. With older versions of the Rails XSS-safety mechanism, this destructively modifies the HTML-safety of `text`.

@param text [String, nil] @return [String, nil] `text`, marked as HTML-safe

Intersperses a value in an enumerable, as would be done with `Array#join` but without concatenating the array together afterwards.

@param enum [Enumerable] @param val @return [Array]

Whether or not this is running on IronRuby.

@return [Boolean]

Computes a single longest common subsequence for `x` and `y`. If there are more than one longest common subsequences, the one returned is that which starts first in `x`.

@param x [Array] @param y [Array] @yield [a, b] An optional block to use in place of a check for equality

  between elements of `x` and `y`.

@yieldreturn [Object, nil] If the two values register as equal,

  this will return the value to use in the LCS array.

@return [Array] The LCS

Maps the key-value pairs of a hash according to a block. For example:

    map_hash({:foo => "bar", :baz => "bang"}) {|k, v| [k.to_s, v.to_sym]}
      #=> {"foo" => :bar, "baz" => :bang}

@param hash [Hash] The hash to map @yield [key, value] A block in which the key-value pairs are transformed @yieldparam [key] The hash key @yieldparam [value] The hash value @yieldreturn [(Object, Object)] The new value for the `[key, value]` pair @return [Hash] The mapped hash @see map_keys @see map_vals

Maps the keys in a hash according to a block. For example:

    map_keys({:foo => "bar", :baz => "bang"}) {|k| k.to_s}
      #=> {"foo" => "bar", "baz" => "bang"}

@param hash [Hash] The hash to map @yield [key] A block in which the keys are transformed @yieldparam key [Object] The key that should be mapped @yieldreturn [Object] The new value for the key @return [Hash] The mapped hash @see map_vals @see map_hash

Maps the values in a hash according to a block. For example:

    map_values({:foo => "bar", :baz => "bang"}) {|v| v.to_sym}
      #=> {:foo => :bar, :baz => :bang}

@param hash [Hash] The hash to map @yield [value] A block in which the values are transformed @yieldparam value [Object] The value that should be mapped @yieldreturn [Object] The new value for the value @return [Hash] The mapped hash @see map_keys @see map_hash

Concatenates all strings that are adjacent in an array, while leaving other elements as they are. For example:

    merge_adjacent_strings([1, "foo", "bar", 2, "baz"])
      #=> [1, "foobar", 2, "baz"]

@param enum [Enumerable] @return [Array] The enumerable with strings merged

Return an array of all possible paths through the given arrays.

@param arrs [Array<Array>] @return [Array<Arrays>]

@example paths([[1, 2], [3, 4], [5]]) #=>

  # [[1, 3, 5],
  #  [2, 3, 5],
  #  [1, 4, 5],
  #  [2, 4, 5]]

Computes the powerset of the given array. This is the set of all subsets of the array. For example:

    powerset([1, 2, 3]) #=>
      Set[Set[], Set[1], Set[2], Set[3], Set[1, 2], Set[2, 3], Set[1, 3], Set[1, 2, 3]]

@param arr [Enumerable] @return [Set<Set>] The subsets of `arr`

Returns the environment of the Rails application, if this is running in a Rails context. Returns `nil` if no such environment is defined.

@return [String, nil]

Returns the root of the Rails application, if this is running in a Rails context. Returns `nil` if no such root is defined.

@return [String, nil]

The class for the Rails SafeBuffer XSS protection class. This varies depending on Rails version.

@return [Class]

Whether or not ActionView‘s XSS protection is available and enabled, as is the default for Rails 3.0+, and optional for version 2.3.5+. Overridden in haml/template.rb if this is the case.

@return [Boolean]

Restricts a number to falling within a given range. Returns the number if it falls within the range, or the closest value in the range if it doesn‘t.

@param value [Numeric] @param range [Range<Numeric>] @return [Numeric]

Whether or not this is running under Ruby 1.8 or lower.

Note that IronRuby counts as Ruby 1.8, because it doesn‘t support the Ruby 1.9 encoding API.

@return [Boolean]

Whether or not this is running under Ruby 1.8.6 or lower. Note that lower versions are not officially supported.

@return [Boolean]

Returns the path of a file relative to the Haml root directory.

@param file [String] The filename relative to the Haml root @return [String] The filename relative to the the working directory

Silences all Haml warnings within a block.

@yield A block in which no Haml warnings will be printed

Silence all output to STDERR within a block.

@yield A block in which no output will be printed to STDERR

Destructively strips whitespace from the beginning and end of the first and last elements, respectively, in the array (if those elements are strings).

@param arr [Array] @return [Array] `arr`

Substitutes a sub-array of one array with another sub-array.

@param ary [Array] The array in which to make the substitution @param from [Array] The sequence of elements to replace with `to` @param to [Array] The sequence of elements to replace `from` with

Converts an array of `[key, value]` pairs to a hash. For example:

    to_hash([[:foo, "bar"], [:baz, "bang"]])
      #=> {:foo => "bar", :baz => "bang"}

@param arr [Array<(Object, Object)>] An array of pairs @return [Hash] A hash

Returns whether one version string represents the same or a more recent version than another.

@param v1 [String] A version string. @param v2 [String] Another version string. @return [Boolean]

Returns whether one version string represents a more recent version than another.

@param v1 [String] A version string. @param v2 [String] Another version string. @return [Boolean]

Whether or not this is running on Windows.

@return [Boolean]

[Validate]