Module | Sass::Util |
In: |
lib/sass/util/subset_map.rb
lib/sass/util.rb |
A module containing various useful functions.
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)})/) |
Throws a NotImplementedError for an abstract method.
@param obj [Object] `self` @raise [NotImplementedError]
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 a sub-array of `minuend` containing only elements that are also in `subtrahend`. Ensures that the return value has the same order as `minuend`, even on Rubinius where that‘s not guaranteed by {Array#-}.
@param minuend [Array] @param subtrahend [Array] @return [Array]
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
Asserts that `value` falls within `range` (inclusive), leaving room for slight floating-point errors.
@param name [String] The name of the value. Used in the error message. @param range [Range] The allowed range of values. @param value [Numeric, Sass::Script::Number] The value to check. @param unit [String] The unit of the value. Used in error reporting. @return [Numeric] `value` adjusted to fall within range, if it
was outside by a floating-point margin.
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`
Prepare a value for a destructuring assignment (e.g. `a, b = val`). This works around a performance bug when using ActiveSupport, and only needs to be called when `val` is likely to be `nil` reasonably often.
See [this bug report](redmine.ruby-lang.org/issues/4917).
@param val [Object] @return [Object]
Like `Dir.glob`, but works with backslash-separated paths on Windows.
@param path [String]
Performs the equivalent of `enum.group_by.to_a`, but with a guaranteed order. Unlike [hash_to_a], the resulting order isn‘t sorted key order; instead, it‘s the same order as `group_by` has under Ruby 1.9 (key appearance order).
@param enum [Enumerable] @return [Array<[Object, Array]>] An array of pairs.
Converts a Hash to an Array. This is usually identical to `Hash#to_a`, with the following exceptions:
@param hash [Hash] @return [Array]
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]
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.
@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.
@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.
@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.
@example
merge_adjacent_strings([1, "foo", "bar", 2, "baz"]) #=> [1, "foobar", 2, "baz"]
@param arr [Array] @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.
@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]
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]
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`
Returns whether or not `seq1` is a subsequence of `seq2`. That is, whether or not `seq2` contains every element in `seq1` in the same order (and possibly more elements besides).
@param seq1 [Array] @param seq2 [Array] @return [Boolean]
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.
@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 a string description of the character that caused an `Encoding::UndefinedConversionError`.
@param [Encoding::UndefinedConversionError] @return [String]
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]