Module: Sass::Util

Extended by:
Util
Included in:
Engine, Plugin, Plugin::Compiler, Script::Color, Util, Version
Defined in:
lib/sass/util.rb,
lib/sass/util/test.rb,
lib/sass/util/subset_map.rb

Overview

A module containing various useful functions.

Defined Under Namespace

Modules: Test Classes: MultibyteStringScanner, StaticConditionalContext, SubsetMap

Constant Summary collapse

RUBY_VERSION =

An array of ints representing the Ruby version number.

::RUBY_VERSION.split(".").map {|s| s.to_i}
RUBY_ENGINE =

The Ruby engine we're running under. Defaults to "ruby" if the top-level constant is undefined.

defined?(::RUBY_ENGINE) ? ::RUBY_ENGINE : "ruby"
ENCODINGS_TO_CHECK =

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.

%w[UTF-8 UTF-16BE UTF-16LE UTF-32BE UTF-32LE]
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)})/)
    rescue Encoding::ConverterNotFoundError => _
      nil # JRuby on Java 5 doesn't support UTF-32
    rescue
      # /\A@charset "(.*?)"/
      Regexp.new(/\A#{_enc('@charset "', e)}(.*?)#{_enc('"', e)}/)
    end
end
@@silence_warnings = 
false

Instance Method Summary collapse

Instance Method Details

#abstract(obj)

Throws a NotImplementedError for an abstract method.

Parameters:

  • obj (Object) —

    self

Raises:

  • (NotImplementedError) 


380
381
382
 
# File 'lib/sass/util.rb', line 380

def abstract(obj)
  raise NotImplementedError.new("#{obj.class} must implement ##{caller_info[2]}")
end

#ap_geq?(version) ⇒ Boolean

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

Parameters:

  • 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

Returns:

  • (Boolean) 


455
456
457
458
459
460
461
 
# File 'lib/sass/util.rb', line 455

def ap_geq?(version)
  # The ActionPack module is always loaded automatically in Rails >= 3
  return false unless defined?(ActionPack) && defined?(ActionPack::VERSION) &&
    defined?(ActionPack::VERSION::STRING)

  version_geq(ActionPack::VERSION::STRING, version)
end

#ap_geq_3? ⇒ Boolean

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

Returns:

  • (Boolean) 


444
445
446
 
# File 'lib/sass/util.rb', line 444

def ap_geq_3?
  ap_geq?("3.0.0.beta1")
end

#array_minus(minuend, subtrahend) ⇒ Array

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

Parameters:

  • minuend (Array)
  • subtrahend (Array)

Returns:

  • (Array) 


266
267
268
269
270
 
# File 'lib/sass/util.rb', line 266

def array_minus(minuend, subtrahend)
  return minuend - subtrahend unless rbx?
  set = Set.new(minuend) - subtrahend
  minuend.select {|e| set.include?(e)}
end

#av_template_class(name)

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.

Parameters:

  • name (#to_s) —

    The name of the class to get. For example, :Error will return ActionView::TemplateError or ActionView::Template::Error.



471
472
473
474
 
# File 'lib/sass/util.rb', line 471

def av_template_class(name)
  return ActionView.const_get("Template#{name}") if ActionView.const_defined?("Template#{name}")
  return ActionView::Template.const_get(name.to_s)
end

#caller_info(entry = nil) ⇒ [String, Fixnum, (String, nil)]

Returns information about the caller of the previous method.

Parameters:

  • entry (String) (defaults to: nil) —

    An entry in the #caller list, or a similarly formatted string

Returns:

  • ([String, Fixnum, (String, nil)]) —

    An array containing the filename, line, and method name of the caller. The method name may be nil



328
329
330
331
332
333
334
335
336
 
# File 'lib/sass/util.rb', line 328

def caller_info(entry = nil)
  # JRuby evaluates `caller` incorrectly when it's in an actual default argument.
  entry ||= caller[1]
  info = entry.scan(/^(.*?):(-?.*?)(?::.*`(.+)')?$/).first
  info[1] = info[1].to_i
  # This is added by Rubinius to designate a block, but we don't care about it.
  info[2].sub!(/ \{\}\Z/, '') if info[2]
  info
end

#check_encoding(str) {|msg| ... } ⇒ String

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.

Parameters:

  • str (String) —

    The string of which to check the encoding

Yields:

  • (msg) —

    A block in which an encoding error can be raised. Only yields if there is an encoding error

Yield Parameters:

  • msg (String) —

    The error message to be raised

Returns:

  • (String) —

    str, potentially with encoding gotchas like BOMs removed



585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
 
# File 'lib/sass/util.rb', line 585

def check_encoding(str)
  if ruby1_8?
    return str.gsub(/\A\xEF\xBB\xBF/, '') # Get rid of the UTF-8 BOM
  elsif str.valid_encoding?
    # Get rid of the Unicode BOM if possible
    if str.encoding.name =~ /^UTF-(8|16|32)(BE|LE)?$/
      return str.gsub(Regexp.new("\\A\uFEFF".encode(str.encoding.name)), '')
    else
      return str
    end
  end

  encoding = str.encoding
  newlines = Regexp.new("\r\n|\r|\n".encode(encoding).force_encoding("binary"))
  str.force_encoding("binary").split(newlines).each_with_index do |line, i|
    begin
      line.encode(encoding)
    rescue Encoding::UndefinedConversionError => e
      yield <<MSG.rstrip, i + 1
Invalid #{encoding.name} character #{undefined_conversion_error_char(e)}
MSG
    end
  end
  return str
end

#check_range(name, range, value, unit = '') ⇒ Numeric

Asserts that value falls within range (inclusive), leaving room for slight floating-point errors.

Parameters:

  • name (String) —

    The name of the value. Used in the error message.

  • range (Range) —

    The allowed range of values.

  • value (Numeric, Sass::Script::Number) —

    The value to check.

  • unit (String) (defaults to: '') —

    The unit of the value. Used in error reporting.

Returns:

  • (Numeric) —

    value adjusted to fall within range, if it was outside by a floating-point margin.

Raises:

  • (ArgumentError) 


295
296
297
298
299
300
301
302
303
304
 
# File 'lib/sass/util.rb', line 295

def check_range(name, range, value, unit='')
  grace = (-0.00001..0.00001)
  str = value.to_s
  value = value.value if value.is_a?(Sass::Script::Number)
  return value if range.include?(value)
  return range.first if grace.include?(value - range.first)
  return range.last if grace.include?(value - range.last)
  raise ArgumentError.new(
    "#{name} #{str} must be between #{range.first}#{unit} and #{range.last}#{unit}")
end

#check_sass_encoding(str) {|msg| ... } ⇒ (String, 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.

Parameters:

  • str (String) —

    The string of which to check the encoding

Yields:

  • (msg) —

    A block in which an encoding error can be raised. Only yields if there is an encoding error

Yield Parameters:

  • msg (String) —

    The error message to be raised

Returns:

  • ((String, Encoding)) —

    The original string encoded as UTF-8, and the source encoding of the string (or nil under Ruby 1.8)

Raises:

  • (Encoding::UndefinedConversionError) —

    if the source encoding cannot be converted to UTF-8

  • (ArgumentError) —

    if the document uses an unknown encoding with @charset



630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
 
# File 'lib/sass/util.rb', line 630

def check_sass_encoding(str, &block)
  return check_encoding(str, &block), nil if ruby1_8?
  # We allow any printable ASCII characters but double quotes in the charset decl
  bin = str.dup.force_encoding("BINARY")
  encoding = Sass::Util::ENCODINGS_TO_CHECK.find do |enc|
    re = Sass::Util::CHARSET_REGEXPS[enc]
    re && bin =~ re
  end
  charset, bom = $1, $2
  if charset
    charset = charset.force_encoding(encoding).encode("UTF-8")
    if endianness = encoding[/[BL]E$/]
      begin
        Encoding.find(charset + endianness)
        charset << endianness
      rescue ArgumentError # Encoding charset + endianness doesn't exist
      end
    end
    str.force_encoding(charset)
  elsif bom
    str.force_encoding(encoding)
  end

  str = check_encoding(str, &block)
  return str.encode("UTF-8"), str.encoding
end

#destructure(val) ⇒ Object

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.

Parameters:

  • val (Object)

Returns:

  • (Object) 


530
531
532
 
# File 'lib/sass/util.rb', line 530

def destructure(val)
  val || []
end

#enum_cons(enum, n) ⇒ Enumerator

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

Parameters:

  • enum (Enumerable) —

    The enumerable to get the enumerator for

  • n (Fixnum) —

    The size of each cons

Returns:

  • (Enumerator) —

    The consed enumerator



717
718
719
 
# File 'lib/sass/util.rb', line 717

def enum_cons(enum, n)
  ruby1_8? ? enum.enum_cons(n) : enum.each_cons(n)
end

#enum_slice(enum, n) ⇒ Enumerator

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

Parameters:

  • enum (Enumerable) —

    The enumerable to get the enumerator for

  • n (Fixnum) —

    The size of each slice

Returns:

  • (Enumerator) —

    The consed enumerator



726
727
728
 
# File 'lib/sass/util.rb', line 726

def enum_slice(enum, n)
  ruby1_8? ? enum.enum_slice(n) : enum.each_slice(n)
end

#enum_with_index(enum) ⇒ Enumerator

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

Parameters:

  • enum (Enumerable) —

    The enumerable to get the enumerator for

Returns:

  • (Enumerator) —

    The with-index enumerator



708
709
710
 
# File 'lib/sass/util.rb', line 708

def enum_with_index(enum)
  ruby1_8? ? enum.enum_with_index : enum.each_with_index
end

#extract!(array) {|el| ... } ⇒ Array

Destructively removes all elements from an array that match a block, and returns the removed elements.

Parameters:

  • array (Array) —

    The array from which to remove elements.

Yields:

  • (el) —

    Called for each element.

Yield Parameters:

  • el (*) —

    The element to test.

Yield Returns:

  • (Boolean) —

    Whether or not to extract the element.

Returns:

  • (Array) —

    The extracted elements.



738
739
740
741
742
743
744
745
746
 
# File 'lib/sass/util.rb', line 738

def extract!(array)
  out = []
  array.reject! do |e|
    next false unless yield e
    out << e
    true
  end
  out
end

#extract_values(arr) ⇒ (String, Array)

Extracts the non-string vlaues from an array containing both strings and non-strings. These values are replaced with escape sequences. This can be undone using #inject_values.

This is useful e.g. when we want to do string manipulation on an interpolated string.

The precise format of the resulting string is not guaranteed. However, it is guaranteed that newlines and whitespace won't be affected.

Parameters:

  • arr (Array) —

    The array from which values are extracted.

Returns:

  • ((String, Array)) —

    The resulting string, and an array of extracted values.



813
814
815
816
817
818
819
820
 
# File 'lib/sass/util.rb', line 813

def extract_values(arr)
  values = []
  return arr.map do |e|
    next e.gsub('{', '{{') if e.is_a?(String)
    values << e
    next "{#{values.count - 1}}"
  end.join, values
end

#flatten(arr, n) ⇒ Array

Flattens the first n nested arrays in a cross-version manner.

Parameters:

  • arr (Array) —

    The array to flatten

  • n (Fixnum) —

    The number of levels to flatten

Returns:

  • (Array) —

    The flattened array



761
762
763
764
765
 
# File 'lib/sass/util.rb', line 761

def flatten(arr, n)
  return arr.flatten(n) unless ruby1_8_6?
  return arr if n == 0
  arr.inject([]) {|res, e| e.is_a?(Array) ? res.concat(flatten(e, n - 1)) : res << e}
end

#glob(path, &block)

Like Dir.glob, but works with backslash-separated paths on Windows.

Parameters:

  • path (String) 


516
517
518
519
 
# File 'lib/sass/util.rb', line 516

def glob(path, &block)
  path = path.gsub('\\', '/') if windows?
  Dir.glob(path, &block)
end

#group_by_to_a(enum, &block) ⇒ Array<[Object, Array]>

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

Parameters:

  • enum (Enumerable)

Returns:

  • (Array<[Object, Array]>) —

    An array of pairs.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/sass/util.rb', line 243

def group_by_to_a(enum, &block)
  return enum.group_by(&block).to_a unless ruby1_8?
  order = {}
  arr = []
  enum.group_by do |e|
    res = block[e]
    unless order.include?(res)
      order[res] = order.size
    end
    res
  end.each do |key, vals|
    arr[order[key]] = [key, vals]
  end
  arr
end

#has?(attr, klass, method) ⇒ Boolean

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

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

Parameters:

  • attr (#to_s) —

    The (singular) name of the method-collection method (e.g. :instance_methods, :private_methods)

  • klass (Module) —

    The class to check the methods of which to check

  • method (String, Symbol) —

    The name of the method do check for

Returns:

  • (Boolean) —

    Whether or not the given collection has the given method



700
701
702
 
# File 'lib/sass/util.rb', line 700

def has?(attr, klass, method)
  klass.send("#{attr}s").include?(ruby1_8? ? method.to_s : method.to_sym)
end

#hash_to_a(hash) ⇒ Array

Converts a Hash to an Array. This is usually identical to Hash#to_a, with the following exceptions:

  • In Ruby 1.8, Hash#to_a is not deterministically ordered, but this is.
  • In Ruby 1.9 when running tests, this is ordered in the same way it would be under Ruby 1.8 (sorted key order rather than insertion order).

Parameters:

  • hash (Hash)

Returns:

  • (Array) 


231
232
233
234
 
# File 'lib/sass/util.rb', line 231

def hash_to_a(hash)
  return hash.to_a unless ruby1_8? || defined?(Test::Unit)
  return hash.sort_by {|k, v| k}
end

#inject_values(str, values) ⇒ Array

Undoes #extract_values by transforming a string with escape sequences into an array of strings and non-string values.

Parameters:

  • str (String) —

    The string with escape sequences.

  • values (Array) —

    The array of values to inject.

Returns:

  • (Array) —

    The array of strings and values.



828
829
830
831
832
833
834
835
836
 
# File 'lib/sass/util.rb', line 828

def inject_values(str, values)
  return [str.gsub('{{', '{')] if values.empty?
  # Add an extra { so that we process the tail end of the string
  result = (str + '{{').scan(/(.*?)(?:(\{\{)|\{(\d+)\})/m).map do |(pre, esc, n)|
    [pre, esc ? '{' : '', n ? values[n.to_i] : '']
  end.flatten(1)
  result[-2] = '' # Get rid of the extra {
  merge_adjacent_strings(result).reject {|s| s == ''}
end

#inspect_obj(obj) ⇒ String

Like Object#inspect, but preserves non-ASCII characters rather than escaping them under Ruby 1.9.2. This is necessary so that the precompiled Haml template can be #encoded into @options[:encoding] before being evaluated.

Parameters:

  • obj (Object)

Returns:

  • (String) 


794
795
796
797
798
799
 
# File 'lib/sass/util.rb', line 794

def inspect_obj(obj)
  return obj.inspect unless version_geq(::RUBY_VERSION, "1.9.2")
  return ':' + inspect_obj(obj.to_s) if obj.is_a?(Symbol)
  return obj.inspect unless obj.is_a?(String)
  '"' + obj.gsub(/[\x00-\x7F]+/) {|s| s.inspect[1...-1]} + '"'
end

#intersperse(enum, val) ⇒ Array

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

Parameters:

  • enum (Enumerable)
  • val

Returns:

  • (Array) 


154
155
156
 
# File 'lib/sass/util.rb', line 154

def intersperse(enum, val)
  enum.inject([]) {|a, e| a << e << val}[0...-1]
end

#ironruby? ⇒ Boolean

Whether or not this is running on IronRuby.

Returns:

  • (Boolean) 


488
489
490
 
# File 'lib/sass/util.rb', line 488

def ironruby?
  RUBY_ENGINE == "ironruby"
end

#jruby1_6? ⇒ Boolean

Wehter or not this is running under JRuby 1.6 or lower.

Returns:

  • (Boolean) 


564
565
566
 
# File 'lib/sass/util.rb', line 564

def jruby1_6?
  jruby? && jruby_version[0] == 1 && jruby_version[1] < 7
end

#jruby? ⇒ Boolean

Whether or not this is running on JRuby.

Returns:

  • (Boolean) 


502
503
504
 
# File 'lib/sass/util.rb', line 502

def jruby?
  RUBY_PLATFORM =~ /java/
end

#jruby_version ⇒ Array<Fixnum>

Returns an array of ints representing the JRuby version number.

Returns:

  • (Array<Fixnum>) 


509
510
511
 
# File 'lib/sass/util.rb', line 509

def jruby_version
  $jruby_version ||= ::JRUBY_VERSION.split(".").map {|s| s.to_i}
end

#lcs(x, y) {|a, b| ... } ⇒ 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.

Parameters:

  • x (Array)
  • y (Array)

Yields:

  • (a, b) —

    An optional block to use in place of a check for equality between elements of x and y.

Yield Returns:

  • (Object, nil) —

    If the two values register as equal, this will return the value to use in the LCS array.

Returns:

  • (Array) —

    The LCS



215
216
217
218
219
220
 
# File 'lib/sass/util.rb', line 215

def lcs(x, y, &block)
  x = [nil, *x]
  y = [nil, *y]
  block ||= proc {|a, b| a == b && a}
  lcs_backtrace(lcs_table(x, y, &block), x, y, x.size-1, y.size-1, &block)
end

#macruby? ⇒ Boolean

Whether or not this is running under MacRuby.

Returns:

  • (Boolean) 


571
572
573
 
# File 'lib/sass/util.rb', line 571

def macruby?
  RUBY_ENGINE == 'macruby'
end

#map_hash(hash) {|key, value| ... } ⇒ Hash

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

Examples:

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

Parameters:

  • hash (Hash) —

    The hash to map

Yields:

  • (key, value) —

    A block in which the key-value pairs are transformed

Yield Parameters:

  • The (key) —

    hash key

  • The (value) —

    hash value

Yield Returns:

  • ((Object, Object)) —

    The new value for the [key, value] pair

Returns:

  • (Hash) —

    The mapped hash

See Also:



88
89
90
91
 
# File 'lib/sass/util.rb', line 88

def map_hash(hash)
  # Using &block here completely hoses performance on 1.8.
  to_hash(hash.map {|k, v| yield k, v})
end

#map_keys(hash) {|key| ... } ⇒ Hash

Maps the keys in a hash according to a block.

Examples:

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

Parameters:

  • hash (Hash) —

    The hash to map

Yields:

  • (key) —

    A block in which the keys are transformed

Yield Parameters:

  • key (Object) —

    The key that should be mapped

Yield Returns:

  • (Object) —

    The new value for the key

Returns:

  • (Hash) —

    The mapped hash

See Also:



55
56
57
 
# File 'lib/sass/util.rb', line 55

def map_keys(hash)
  to_hash(hash.map {|k, v| [yield(k), v]})
end

#map_vals(hash) {|value| ... } ⇒ Hash

Maps the values in a hash according to a block.

Examples:

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

Parameters:

  • hash (Hash) —

    The hash to map

Yields:

  • (value) —

    A block in which the values are transformed

Yield Parameters:

  • value (Object) —

    The value that should be mapped

Yield Returns:

  • (Object) —

    The new value for the value

Returns:

  • (Hash) —

    The mapped hash

See Also:



71
72
73
 
# File 'lib/sass/util.rb', line 71

def map_vals(hash)
  to_hash(hash.map {|k, v| [k, yield(v)]})
end

#merge_adjacent_strings(arr) ⇒ Array

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

Examples:

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

Parameters:

  • arr (Array)

Returns:

  • (Array) —

    The enumerable with strings merged



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/sass/util.rb', line 131

def merge_adjacent_strings(arr)
  # Optimize for the common case of one element
  return arr if arr.size < 2
  arr.inject([]) do |a, e|
    if e.is_a?(String)
      if a.last.is_a?(String)
        a.last << e
      else
        a << e.dup
      end
    else
      a << e
    end
    a
  end
end

#ord(c) ⇒ Fixnum

Returns the ASCII code of the given character.

Parameters:

  • c (String) —

    All characters but the first are ignored.

Returns:

  • (Fixnum) —

    The ASCII code of c.



752
753
754
 
# File 'lib/sass/util.rb', line 752

def ord(c)
  ruby1_8? ? c[0] : c.ord
end

#paths(arrs) ⇒ Array<Arrays>

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

Examples:

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

Parameters:

  • arrs (Array<Array>)

Returns:

  • (Array<Arrays>) 


198
199
200
201
202
 
# File 'lib/sass/util.rb', line 198

def paths(arrs)
  arrs.inject([[]]) do |paths, arr|
    flatten(arr.map {|e| paths.map {|path| path + [e]}}, 1)
  end
end

#powerset(arr) ⇒ Set<Set>

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

Examples:

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

Parameters:

  • arr (Enumerable)

Returns:

  • (Set<Set>) —

    The subsets of arr



101
102
103
104
105
106
107
108
109
110
 
# File 'lib/sass/util.rb', line 101

def powerset(arr)
  arr.inject([Set.new].to_set) do |powerset, el|
    new_powerset = Set.new
    powerset.each do |subset|
      new_powerset << subset
      new_powerset << subset + [el]
    end
    new_powerset
  end
end

#rails_env ⇒ String?

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

Returns:

  • (String, nil) 


434
435
436
437
438
 
# File 'lib/sass/util.rb', line 434

def rails_env
  return ::Rails.env.to_s if defined?(::Rails.env)
  return RAILS_ENV.to_s if defined?(RAILS_ENV)
  return nil
end

#rails_root ⇒ String?

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

Returns:

  • (String, nil) 


420
421
422
423
424
425
426
427
 
# File 'lib/sass/util.rb', line 420

def rails_root
  if defined?(::Rails.root)
    return ::Rails.root.to_s if ::Rails.root
    raise "ERROR: Rails.root is nil!"
  end
  return RAILS_ROOT.to_s if defined?(RAILS_ROOT)
  return nil
end

#rbx? ⇒ Boolean

Whether or not this is running on Rubinius.

Returns:

  • (Boolean) 


495
496
497
 
# File 'lib/sass/util.rb', line 495

def rbx?
  RUBY_ENGINE == "rbx"
end

#restrict(value, range) ⇒ Numeric

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.

Parameters:

  • value (Numeric)
  • range (Range<Numeric>)

Returns:

  • (Numeric) 


119
120
121
 
# File 'lib/sass/util.rb', line 119

def restrict(value, range)
  [[value, range.first].max, range.last].min
end

#ruby1? ⇒ Boolean

Whether or not this is running under a Ruby version under 2.0.

Returns:

  • (Boolean) 


539
540
541
 
# File 'lib/sass/util.rb', line 539

def ruby1?
  Sass::Util::RUBY_VERSION[0] <= 1
end

#ruby1_8? ⇒ Boolean

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.

Returns:

  • (Boolean) 


549
550
551
552
553
 
# File 'lib/sass/util.rb', line 549

def ruby1_8?
  # IronRuby says its version is 1.9, but doesn't support any of the encoding APIs.
  # We have to fall back to 1.8 behavior.
  ironruby? || (Sass::Util::RUBY_VERSION[0] == 1 && Sass::Util::RUBY_VERSION[1] < 9)
end

#ruby1_8_6? ⇒ Boolean

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

Returns:

  • (Boolean) 


559
560
561
 
# File 'lib/sass/util.rb', line 559

def ruby1_8_6?
  ruby1_8? && Sass::Util::RUBY_VERSION[2] < 7
end

#sass_warn(msg)

The same as Kernel#warn, but is silenced by #silence_sass_warnings.

Parameters:

  • msg (String) 


408
409
410
411
 
# File 'lib/sass/util.rb', line 408

def sass_warn(msg)
  msg = msg + "\n" unless ruby1?
  Sass.logger.warn(msg)
end

#scope(file) ⇒ String

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

Parameters:

  • file (String) —

    The filename relative to the Sass root

Returns:

  • (String) —

    The filename relative to the the working directory



28
29
30
 
# File 'lib/sass/util.rb', line 28

def scope(file)
  File.join(Sass::ROOT_DIR, file)
end

#set_eql?(set1, set2) ⇒ Boolean

Tests the hash-equality of two sets in a cross-version manner. Aggravatingly, this is order-dependent in Ruby 1.8.6.

Parameters:

  • set1 (Set)
  • set2 (Set)

Returns:

  • (Boolean) —

    Whether or not the sets are hashcode equal



783
784
785
786
 
# File 'lib/sass/util.rb', line 783

def set_eql?(set1, set2)
  return set1.eql?(set2) unless ruby1_8_6?
  set1.to_a.uniq.sort_by {|e| e.hash}.eql?(set2.to_a.uniq.sort_by {|e| e.hash})
end

#set_hash(set) ⇒ Fixnum

Returns the hash code for a set in a cross-version manner. Aggravatingly, this is order-dependent in Ruby 1.8.6.

Parameters:

  • set (Set)

Returns:

  • (Fixnum) —

    The order-independent hashcode of set



772
773
774
775
 
# File 'lib/sass/util.rb', line 772

def set_hash(set)
  return set.hash unless ruby1_8_6?
  set.map {|e| e.hash}.uniq.sort.hash
end

#silence_sass_warnings { ... }

Silences all Sass warnings within a block.

Yields:

  • A block in which no Sass warnings will be printed



398
399
400
401
402
403
 
# File 'lib/sass/util.rb', line 398

def silence_sass_warnings
  old_level, Sass.logger.log_level = Sass.logger.log_level, :error
  yield
ensure
  Sass.logger.log_level = old_level
end

#silence_warnings { ... }

Silence all output to STDERR within a block.

Yields:

  • A block in which no output will be printed to STDERR



387
388
389
390
391
392
 
# File 'lib/sass/util.rb', line 387

def silence_warnings
  the_real_stderr, $stderr = $stderr, StringIO.new
  yield
ensure
  $stderr = the_real_stderr
end

#strip_string_array(arr) ⇒ Array

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

Parameters:

  • arr (Array)

Returns:

  • (Array) —

    arr



181
182
183
184
185
 
# File 'lib/sass/util.rb', line 181

def strip_string_array(arr)
  arr.first.lstrip! if arr.first.is_a?(String)
  arr.last.rstrip! if arr.last.is_a?(String)
  arr
end

#subsequence?(seq1, seq2) ⇒ Boolean

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

Parameters:

  • seq1 (Array)
  • seq2 (Array)

Returns:

  • (Boolean) 


313
314
315
316
317
318
319
320
321
 
# File 'lib/sass/util.rb', line 313

def subsequence?(seq1, seq2)
  i = j = 0
  loop do
    return true if i == seq1.size
    return false if j == seq2.size
    i += 1 if seq1[i] == seq2[j]
    j += 1
  end
end

#substitute(ary, from, to)

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

Parameters:

  • ary (Array) —

    The array in which to make the substitution

  • from (Array) —

    The sequence of elements to replace with to

  • to (Array) —

    The sequence of elements to replace from with



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/sass/util.rb', line 163

def substitute(ary, from, to)
  res = ary.dup
  i = 0
  while i < res.size
    if res[i...i+from.size] == from
      res[i...i+from.size] = to
    end
    i += 1
  end
  res
end

#to_hash(arr) ⇒ Hash

Converts an array of [key, value] pairs to a hash.

Examples:

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

Parameters:

  • arr (Array<(Object, Object)>) —

    An array of pairs

Returns:

  • (Hash) —

    A hash



39
40
41
 
# File 'lib/sass/util.rb', line 39

def to_hash(arr)
  Hash[arr.compact]
end

#undefined_conversion_error_char(e) ⇒ String

Returns a string description of the character that caused an Encoding::UndefinedConversionError.

Parameters:

  • (Encoding::UndefinedConversionError)

Returns:

  • (String) 


277
278
279
280
281
282
283
284
 
# File 'lib/sass/util.rb', line 277

def undefined_conversion_error_char(e)
  # Rubinius (as of 2.0.0.rc1) pre-quotes the error character.
  return e.error_char if rbx?
  # JRuby (as of 1.7.2) doesn't have an error_char field on
  # Encoding::UndefinedConversionError.
  return e.error_char.dump unless jruby?
  e.message[/^"[^"]+"/] #"
end

#version_geq(v1, v2) ⇒ Boolean

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

Parameters:

  • v1 (String) —

    A version string.

  • v2 (String) —

    Another version string.

Returns:

  • (Boolean) 


372
373
374
 
# File 'lib/sass/util.rb', line 372

def version_geq(v1, v2)
  version_gt(v1, v2) || !version_gt(v2, v1)
end

#version_gt(v1, v2) ⇒ Boolean

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

Parameters:

  • v1 (String) —

    A version string.

  • v2 (String) —

    Another version string.

Returns:

  • (Boolean) 


343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/sass/util.rb', line 343

def version_gt(v1, v2)
  # Construct an array to make sure the shorter version is padded with nil
  Array.new([v1.length, v2.length].max).zip(v1.split("."), v2.split(".")) do |_, p1, p2|
    p1 ||= "0"
    p2 ||= "0"
    release1 = p1 =~ /^[0-9]+$/
    release2 = p2 =~ /^[0-9]+$/
    if release1 && release2
      # Integer comparison if both are full releases
      p1, p2 = p1.to_i, p2.to_i
      next if p1 == p2
      return p1 > p2
    elsif !release1 && !release2
      # String comparison if both are prereleases
      next if p1 == p2
      return p1 > p2
    else
      # If only one is a release, that one is newer
      return release1
    end
  end
end

#windows? ⇒ Boolean

Whether or not this is running on Windows.

Returns:

  • (Boolean) 


481
482
483
 
# File 'lib/sass/util.rb', line 481

def windows?
  RbConfig::CONFIG['host_os'] =~ /mswin|windows|mingw/i
end

#with_extracted_values(arr) {|str| ... } ⇒ Array

Allows modifications to be performed on the string form of an array containing both strings and non-strings.

Parameters:

  • arr (Array) —

    The array from which values are extracted.

Yields:

  • (str) —

    A block in which string manipulation can be done to the array.

Yield Parameters:

  • str (String) —

    The string form of arr.

Yield Returns:

  • (String) —

    The modified string.

Returns:

  • (Array) —

    The modified, interpolated array.



846
847
848
849
850
 
# File 'lib/sass/util.rb', line 846

def with_extracted_values(arr)
  str, vals = extract_values(arr)
  str = yield str
  inject_values(str, vals)
end