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

A module containing various useful functions.

Methods

Classes and Modules

Class Haml::Util::StaticConditionalContext

Constants

RUBY_VERSION = ::RUBY_VERSION.split(".").map {|s| s.to_i}   An array of ints representing the Ruby version number.

Public Instance methods

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

@param text [Object]

[Source]

     # File lib/haml/util.rb, line 199
199:     def assert_html_safe!(text)
200:       return unless rails_xss_safe? && text && !text.to_s.html_safe?
201:       raise Haml::Error.new("Expected #{text.inspect} to be HTML-safe.")
202:     end

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

[Source]

     # File lib/haml/util.rb, line 168
168:     def av_template_class(name)
169:       return ActionView.const_get("Template#{name}") if ActionView.const_defined?("Template#{name}")
170:       return ActionView::Template.const_get(name.to_s)
171:     end

This is used for methods in {Haml::Buffer} that need to be very fast, and take a lot of boolean parameters that are known at compile-time. Instead of passing the parameters in normally, a separate method is defined for every possible combination of those parameters; these are then called using \{static_method_name}.

To define a static method, an ERB template for the method is provided. All conditionals based on the static parameters are done as embedded Ruby within this template. For example:

    def_static_method(Foo, :my_static_method, [:foo, :bar], :baz, :bang, <<RUBY)
      <% if baz && bang %>
        return foo + bar
      <% elsif baz || bang %>
        return foo - bar
      <% else %>
        return 17
      <% end %>
    RUBY

\{static_method_name} can be used to call static methods.

@overload def_static_method(klass, name, args, *vars, erb) @param klass [Module] The class on which to define the static method @param name [to_s] The (base) name of the static method @param args [Array<Symbol>] The names of the arguments to the defined methods

  (**not** to the ERB template)

@param vars [Array<Symbol>] The names of the static boolean variables

  to be made available to the ERB template

@param erb [String] The template for the method code

[Source]

     # File lib/haml/util.rb, line 295
295:     def def_static_method(klass, name, args, *vars)
296:       erb = vars.pop
297:       powerset(vars).each do |set|
298:         context = StaticConditionalContext.new(set).instance_eval {binding}
299:         klass.class_eval("def \#{static_method_name(name, *vars.map {|v| set.include?(v)})}(\#{args.join(', ')})\n  \#{ERB.new(erb).result(context)}\nend\n")
300:       end
301:     end

A version of `Enumerable#enum_with_index` that works in Ruby 1.8 and 1.9.

@param enum [Enumerable] The enumerable to get the enumerator for @return [Enumerator] The with-index enumerator

[Source]

     # File lib/haml/util.rb, line 240
240:     def enum_with_index(enum)
241:       ruby1_8? ? enum.enum_with_index : enum.each_with_index
242:     end

Checks to see if a class has a given method. For example:

    Haml::Util.has?(:public_instance_method, String, :gsub) #=> true

Method collections like `Class#instance_methods` return strings in Ruby 1.8 and symbols in Ruby 1.9 and on, so this handles checking for them in a compatible way.

@param attr [to_s] The (singular) name of the method-collection method

  (e.g. `:instance_methods`, `:private_methods`)

@param klass [Module] The class to check the methods of which to check @param method [String, Symbol] The name of the method do check for @return [Boolean] Whether or not the given collection has the given method

[Source]

     # File lib/haml/util.rb, line 232
232:     def has?(attr, klass, method)
233:       klass.send("#{attr}s").include?(ruby1_8? ? method.to_s : method.to_sym)
234:     end

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] @return [String] `text`, marked as HTML-safe

[Source]

     # File lib/haml/util.rb, line 190
190:     def html_safe(text)
191:       return text.html_safe if defined?(ActiveSupport::SafeBuffer)
192:       text.html_safe!
193:     end

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

[Source]

    # File lib/haml/util.rb, line 82
82:     def map_hash(hash, &block)
83:       to_hash(hash.map(&block))
84:     end

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

[Source]

    # File lib/haml/util.rb, line 47
47:     def map_keys(hash)
48:       to_hash(hash.map {|k, v| [yield(k), v]})
49:     end

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

[Source]

    # File lib/haml/util.rb, line 64
64:     def map_vals(hash)
65:       to_hash(hash.map {|k, v| [k, yield(v)]})
66:     end

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

[Source]

     # File lib/haml/util.rb, line 115
115:     def merge_adjacent_strings(enum)
116:       e = enum.inject([]) do |a, e|
117:         if e.is_a?(String) && a.last.is_a?(String)
118:           a.last << e
119:         else
120:           a << e
121:         end
122:         a
123:       end
124:     end

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`

[Source]

     # File lib/haml/util.rb, line 95
 95:     def powerset(arr)
 96:       arr.inject([Set.new].to_set) do |powerset, el|
 97:         new_powerset = Set.new
 98:         powerset.each do |subset|
 99:           new_powerset << subset
100:           new_powerset << subset + [el]
101:         end
102:         new_powerset
103:       end
104:     end

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]

[Source]

     # File lib/haml/util.rb, line 154
154:     def rails_env
155:       return Rails.env.to_s if defined?(Rails.root)
156:       return RAILS_ENV.to_s if defined?(RAILS_ENV)
157:       return nil
158:     end

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]

[Source]

     # File lib/haml/util.rb, line 143
143:     def rails_root
144:       return Rails.root.to_s if defined?(Rails.root)
145:       return RAILS_ROOT.to_s if defined?(RAILS_ROOT)
146:       return nil
147:     end

[Source]

     # File lib/haml/util.rb, line 204
204:     def rails_safe_buffer_class
205:       return ActionView::SafeBuffer if defined?(ActionView::SafeBuffer)
206:       ActiveSupport::SafeBuffer
207:     end

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]

[Source]

     # File lib/haml/util.rb, line 180
180:     def rails_xss_safe?
181:       false
182:     end

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

@return [Boolean]

[Source]

     # File lib/haml/util.rb, line 214
214:     def ruby1_8?
215:       Haml::Util::RUBY_VERSION[0] == 1 && Haml::Util::RUBY_VERSION[1] < 9
216:     end

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

[Source]

    # File lib/haml/util.rb, line 18
18:     def scope(file)
19:       File.join(File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__)))), file)
20:     end

Silence all output to STDERR within a block.

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

[Source]

     # File lib/haml/util.rb, line 129
129:     def silence_warnings
130:       the_real_stderr, $stderr = $stderr, StringIO.new
131:       yield
132:     ensure
133:       $stderr = the_real_stderr
134:     end

Computes the name for a method defined via \{def_static_method}.

@param name [String] The base name of the static method @param vars [Array<Boolean>] The static variable assignment @return [String] The real name of the static method

[Source]

     # File lib/haml/util.rb, line 313
313:     def static_method_name(name, *vars)
314:       "#{name}_#{vars.map {|v| !!v}.join('_')}"
315:     end

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

[Source]

    # File lib/haml/util.rb, line 30
30:     def to_hash(arr)
31:       arr.compact.inject({}) {|h, (k, v)| h[k] = v; h}
32:     end

[Validate]