Module: Sass::Util

Extended by:
Util
Included in:
Util
Defined in:
.ruby-sass/lib/sass/util.rb,
.ruby-sass/lib/sass/util/normalized_map.rb,
.ruby-sass/lib/sass/util/subset_map.rb,
.ruby-sass/lib/sass/util/test.rb

Overview

A module containing various useful functions.

Defined Under Namespace

Modules: Test Classes: MultibyteStringScanner, NormalizedMap, StaticConditionalContext, SubsetMap

Constant Summary

RUBY_VERSION_COMPONENTS =

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"
CHARSET_REGEXP = 
/\A@charset "([^"]+)"/
UTF_8_BOM = 
bom.encode("UTF-8").force_encoding('BINARY')
UTF_16BE_BOM = 
bom.encode("UTF-16BE").force_encoding('BINARY')
UTF_16LE_BOM = 
bom.encode("UTF-16LE").force_encoding('BINARY')
VLQ_BASE_SHIFT = 
5
VLQ_BASE = 
1 << VLQ_BASE_SHIFT
VLQ_BASE_MASK = 
VLQ_BASE - 1
VLQ_CONTINUATION_BIT = 
VLQ_BASE
BASE64_DIGITS = 
('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a + ['+', '/']
BASE64_DIGIT_MAP = 
begin
  map = {}
  BASE64_DIGITS.each_with_index.map do |digit, i|
    map[digit] = i
  end
  map
end
ATOMIC_WRITE_MUTEX = 
Mutex.new

Instance Method Summary (collapse)

Instance Method Details

#abstract(obj) ⇒ Object

Throws a NotImplementedError for an abstract method.

Parameters:

  • obj (Object) —

    `self`

Raises:

  • (NotImplementedError) 


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

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) 


518
519
520
521
522
523
524
 
# File '.ruby-sass/lib/sass/util.rb', line 518

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) 


507
508
509
 
# File '.ruby-sass/lib/sass/util.rb', line 507

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) 


317
318
319
320
321
 
# File '.ruby-sass/lib/sass/util.rb', line 317

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

#atomic_create_and_write_file(filename, perms = 0666) {|tmpfile| ... } ⇒ Object

This creates a temp file and yields it for writing. When the write is complete, the file is moved into the desired location. The atomicity of this operation is provided by the filesystem's rename operation.

Parameters:

  • filename (String) —

    The file to write to.

  • perms (Integer) (defaults to: 0666) —

    The permissions used for creating this file. Will be masked by the process umask. Defaults to readable/writeable by all users however the umask usually changes this to only be writable by the process's user.

Yield Parameters:

  • tmpfile (Tempfile) —

    The temp file that can be written to.

Returns:

  • The value returned by the block.



1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
 
# File '.ruby-sass/lib/sass/util.rb', line 1007

def atomic_create_and_write_file(filename, perms = 0666)
  require 'tempfile'
  tmpfile = Tempfile.new(File.basename(filename), File.dirname(filename))
  tmpfile.binmode if tmpfile.respond_to?(:binmode)
  result = yield tmpfile
  tmpfile.close
  ATOMIC_WRITE_MUTEX.synchronize do
    begin
      File.chmod(perms & ~File.umask, tmpfile.path)
    rescue Errno::EPERM
      # If we don't have permissions to chmod the file, don't let that crash
      # the compilation. See issue 1215.
    end
    File.rename tmpfile.path, filename
  end
  result
ensure
  # close and remove the tempfile if it still exists,
  # presumably due to an error during write
  tmpfile.close if tmpfile
  tmpfile.unlink if tmpfile
end

#av_template_class(name) ⇒ 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`.

Parameters:

  • name (#to_s) —

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



534
535
536
537
 
# File '.ruby-sass/lib/sass/util.rb', line 534

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

#caller_info(entry = nil) ⇒ [String, Integer, (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, Integer, (String, nil)]) —

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



392
393
394
395
396
397
398
399
400
 
# File '.ruby-sass/lib/sass/util.rb', line 392

def caller_info(entry = nil)
  # JRuby evaluates `caller` incorrectly when it's in an actual default argument.
  entry ||= caller[1]
  info = entry.scan(/^((?:[A-Za-z]:)?.*?):(-?.*?)(?::.*`(.+)')?$/).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_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::Value::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) 


358
359
360
361
362
363
364
365
366
367
 
# File '.ruby-sass/lib/sass/util.rb', line 358

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::Value::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) ⇒ (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.

Sass follows CSS's decoding rules.

Parameters:

  • str (String) —

    The string of which to check the encoding

Returns:

  • ((String, Encoding)) —

    The original string encoded as UTF-8, and the source encoding of the string

Raises:

  • (Encoding::UndefinedConversionError) —

    if the source encoding cannot be converted to UTF-8

  • (ArgumentError) —

    if the document uses an unknown encoding with `@charset`

  • (Sass::SyntaxError) —

    If the document declares an encoding that doesn't match its contents, or it doesn't declare an encoding and its contents are invalid in the native encoding.



739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
 
# File '.ruby-sass/lib/sass/util.rb', line 739

def check_sass_encoding(str)
  # Determine the fallback encoding following section 3.2 of CSS Syntax Level 3 and Encodings:
  # http://www.w3.org/TR/2013/WD-css-syntax-3-20130919/#determine-the-fallback-encoding
  # http://encoding.spec.whatwg.org/#decode
  binary = str.dup.force_encoding("BINARY")
  if binary.start_with?(UTF_8_BOM)
    binary.slice! 0, UTF_8_BOM.length
    str = binary.force_encoding('UTF-8')
  elsif binary.start_with?(UTF_16BE_BOM)
    binary.slice! 0, UTF_16BE_BOM.length
    str = binary.force_encoding('UTF-16BE')
  elsif binary.start_with?(UTF_16LE_BOM)
    binary.slice! 0, UTF_16LE_BOM.length
    str = binary.force_encoding('UTF-16LE')
  elsif binary =~ CHARSET_REGEXP
    charset = $1.force_encoding('US-ASCII')
    encoding = Encoding.find(charset)
    if encoding.name == 'UTF-16' || encoding.name == 'UTF-16BE'
      encoding = Encoding.find('UTF-8')
    end
    str = binary.force_encoding(encoding)
  elsif str.encoding.name == "ASCII-8BIT"
    # Normally we want to fall back on believing the Ruby string
    # encoding, but if that's just binary we want to make sure
    # it's valid UTF-8.
    str = str.force_encoding('utf-8')
  end

  find_encoding_error(str) unless str.valid_encoding?

  begin
    # If the string is valid, preprocess it according to section 3.3 of CSS Syntax Level 3.
    return str.encode("UTF-8").gsub(/\r\n?|\f/, "\n").tr("\u0000", "�"), str.encoding
  rescue EncodingError
    find_encoding_error(str)
  end
end

#cleanpath(path) ⇒ Pathname

Like `Pathname#cleanpath`, but normalizes Windows paths to always use backslash separators. Normally, `Pathname#cleanpath` actually does the reverse – it will convert backslashes to forward slashes, which can break `Pathname#relative_path_from`.

Parameters:

  • path (String, Pathname)

Returns:

  • (Pathname) 


615
616
617
618
 
# File '.ruby-sass/lib/sass/util.rb', line 615

def cleanpath(path)
  path = Pathname.new(path) unless path.is_a?(Pathname)
  pathname(path.cleanpath.to_s)
end

#deprecated(obj, message = nil) ⇒ Object

Prints a deprecation warning for the caller method.

Parameters:

  • obj (Object) —

    `self`

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

    A message describing what to do instead.



452
453
454
455
456
457
 
# File '.ruby-sass/lib/sass/util.rb', line 452

def deprecated(obj, message = nil)
  obj_class = obj.is_a?(Class) ? "#{obj}." : "#{obj.class}#"
  full_message = "DEPRECATION WARNING: #{obj_class}#{caller_info[2]} " +
    "will be removed in a future version of Sass.#{("\n" + message) if message}"
  Sass::Util.sass_warn full_message
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](redmine.ruby-lang.org/issues/4917).

Parameters:

  • val (Object)

Returns:

  • (Object) 


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

def destructure(val)
  val || []
end

#downcase(string) ⇒ Object

Like `String.downcase`, but only ever downcases ASCII letters.



305
306
307
308
 
# File '.ruby-sass/lib/sass/util.rb', line 305

def downcase(string)
  return string.downcase unless ruby2_4?
  string.downcase(:ascii)
end

#encode_vlq(value) ⇒ String

Encodes `value` as VLQ (en.wikipedia.org/wiki/VLQ).

Parameters:

  • value (Integer)

Returns:

  • (String) —

    The encoded value



954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
 
# File '.ruby-sass/lib/sass/util.rb', line 954

def encode_vlq(value)
  if value < 0
    value = ((-value) << 1) | 1
  else
    value <<= 1
  end

  result = ''
  begin
    digit = value & VLQ_BASE_MASK
    value >>= VLQ_BASE_SHIFT
    if value > 0
      digit |= VLQ_CONTINUATION_BIT
    end
    result << BASE64_DIGITS[digit]
  end while value > 0
  result
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.



785
786
787
788
789
790
791
792
793
 
# File '.ruby-sass/lib/sass/util.rb', line 785

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.



839
840
841
842
843
844
845
846
847
 
# File '.ruby-sass/lib/sass/util.rb', line 839

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

#file_uri_from_path(path) ⇒ String

Converts `path` to a “file:” URI. This handles Windows paths correctly.

Parameters:

  • path (String, Pathname)

Returns:

  • (String) 


666
667
668
669
670
671
672
673
674
 
# File '.ruby-sass/lib/sass/util.rb', line 666

def file_uri_from_path(path)
  path = path.to_s if path.is_a?(Pathname)
  path = path.tr('\\', '/') if windows?
  path = URI::DEFAULT_PARSER.escape(path)
  return path.start_with?('/') ? "file://" + path : path unless windows?
  return "file:///" + path.tr("\\", "/") if path =~ %r{^[a-zA-Z]:[/\\]}
  return "file:" + path.tr("\\", "/") if path =~ %r{\\\\[^\\]+\\[^\\/]+}
  path.tr("\\", "/")
end

#flatten_vertically(arrs) ⇒ Array

Flattens the first level of nested arrays in `arrs`. Unlike `Array#flatten`, this orders the result by taking the first values from each array in order, then the second, and so on.

Parameters:

  • arrs (Array) —

    The array to flatten.

Returns:

  • (Array) —

    The flattened array.



801
802
803
804
805
806
807
808
809
810
811
 
# File '.ruby-sass/lib/sass/util.rb', line 801

def flatten_vertically(arrs)
  result = []
  arrs = arrs.map {|sub| sub.is_a?(Array) ? sub.dup : Array(sub)}
  until arrs.empty?
    arrs.reject! do |arr|
      result << arr.shift
      arr.empty?
    end
  end
  result
end

#glob(path) ⇒ Object

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

Parameters:

  • path (String) 


586
587
588
589
590
591
592
593
 
# File '.ruby-sass/lib/sass/util.rb', line 586

def glob(path)
  path = path.tr('\\', '/') if windows?
  if block_given?
    Dir.glob(path) {|f| yield(f)}
  else
    Dir.glob(path)
  end
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.



855
856
857
858
859
860
861
862
863
 
# File '.ruby-sass/lib/sass/util.rb', line 855

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 `#encode`d into `@options` before being evaluated.

Parameters:

  • obj (Object)

Returns:

  • (String) 


820
821
822
823
824
825
 
# File '.ruby-sass/lib/sass/util.rb', line 820

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) 


217
218
219
 
# File '.ruby-sass/lib/sass/util.rb', line 217

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) 


555
556
557
558
 
# File '.ruby-sass/lib/sass/util.rb', line 555

def ironruby?
  return @ironruby if defined?(@ironruby)
  @ironruby = RUBY_ENGINE == "ironruby"
end

#jruby? ⇒ Boolean

Whether or not this is running on JRuby.

Returns:

  • (Boolean) 


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

def jruby?
  return @jruby if defined?(@jruby)
  @jruby = RUBY_PLATFORM =~ /java/
end

#jruby_version ⇒ Array<Integer>

Returns an array of ints representing the JRuby version number.

Returns:

  • (Array<Integer>) 


579
580
581
 
# File '.ruby-sass/lib/sass/util.rb', line 579

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

#json_escape_string(s) ⇒ String

Escapes certain characters so that the result can be used as the JSON string value. Returns the original string if no escaping is necessary.

Parameters:

  • s (String) —

    The string to be escaped

Returns:

  • (String) —

    The escaped string



893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
 
# File '.ruby-sass/lib/sass/util.rb', line 893

def json_escape_string(s)
  return s if s !~ /["\\\b\f\n\r\t]/

  result = ""
  s.split("").each do |c|
    case c
    when '"', "\\"
      result << "\\" << c
    when "\n" then result << "\\n"
    when "\t" then result << "\\t"
    when "\r" then result << "\\r"
    when "\f" then result << "\\f"
    when "\b" then result << "\\b"
    else
      result << c
    end
  end
  result
end

#json_value_of(v) ⇒ String

Converts the argument into a valid JSON value.

Parameters:

  • v (Integer, String, Array, Boolean, nil)

Returns:

  • (String) 


917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
 
# File '.ruby-sass/lib/sass/util.rb', line 917

def json_value_of(v)
  case v
  when Integer
    v.to_s
  when String
    "\"" + json_escape_string(v) + "\""
  when Array
    "[" + v.map {|x| json_value_of(x)}.join(",") + "]"
  when NilClass
    "null"
  when TrueClass
    "true"
  when FalseClass
    "false"
  else
    raise ArgumentError.new("Unknown type: #{v.class.name}")
  end
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



291
292
293
294
295
296
 
# File '.ruby-sass/lib/sass/util.rb', line 291

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

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



90
91
92
93
94
95
96
97
98
99
100
 
# File '.ruby-sass/lib/sass/util.rb', line 90

def map_hash(hash)
  # Copy and modify is more performant than mapping to an array and using
  # to_hash on the result.
  rv = hash.class.new
  hash.each do |k, v|
    new_key, new_value = yield(k, v)
    new_key = hash.denormalize(new_key) if hash.is_a?(NormalizedMap) && new_key == k
    rv[new_key] = new_value
  end
  rv
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:



50
51
52
 
# File '.ruby-sass/lib/sass/util.rb', line 50

def map_keys(hash)
  map_hash(hash) {|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:



66
67
68
69
70
71
72
73
74
75
 
# File '.ruby-sass/lib/sass/util.rb', line 66

def map_vals(hash)
  # We don't delegate to map_hash for performance here
  # because map_hash does more than is necessary.
  rv = hash.class.new
  hash = hash.as_stored if hash.is_a?(NormalizedMap)
  hash.each do |k, v|
    rv[k] = yield(v)
  end
  rv
end

#max(val1, val2) ⇒ Object

Returns the maximum of `val1` and `val2`. We use this over Array.max to avoid unnecessary garbage collection.



325
326
327
 
# File '.ruby-sass/lib/sass/util.rb', line 325

def max(val1, val2)
  val1 > val2 ? val1 : val2
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



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File '.ruby-sass/lib/sass/util.rb', line 157

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

#min(val1, val2) ⇒ Object

Returns the minimum of `val1` and `val2`. We use this over Array.min to avoid unnecessary garbage collection.



331
332
333
 
# File '.ruby-sass/lib/sass/util.rb', line 331

def min(val1, val2)
  val1 <= val2 ? val1 : val2
end

#pathname(path) ⇒ Pathname

Like `Pathname.new`, but normalizes Windows paths to always use backslash separators.

`Pathname#relative_path_from` can break if the two pathnames aren't consistent in their slash style.

Parameters:

  • path (String)

Returns:

  • (Pathname) 


603
604
605
606
 
# File '.ruby-sass/lib/sass/util.rb', line 603

def pathname(path)
  path = path.tr("/", "\\") if windows?
  Pathname.new(path)
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>) 


274
275
276
277
278
 
# File '.ruby-sass/lib/sass/util.rb', line 274

def paths(arrs)
  arrs.inject([[]]) do |paths, arr|
    arr.map {|e| paths.map {|path| path + [e]}}.flatten(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`



110
111
112
113
114
115
116
117
118
119
 
# File '.ruby-sass/lib/sass/util.rb', line 110

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) 


497
498
499
500
501
 
# File '.ruby-sass/lib/sass/util.rb', line 497

def rails_env
  return ::Rails.env.to_s if defined?(::Rails.env)
  return RAILS_ENV.to_s if defined?(RAILS_ENV)
  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) 


483
484
485
486
487
488
489
490
 
# File '.ruby-sass/lib/sass/util.rb', line 483

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)
  nil
end

#rbx? ⇒ Boolean

Whether or not this is running on Rubinius.

Returns:

  • (Boolean) 


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

def rbx?
  return @rbx if defined?(@rbx)
  @rbx = RUBY_ENGINE == "rbx"
end

#realpath(path) ⇒ Pathname

Returns `path` with all symlinks resolved.

Parameters:

  • path (String, Pathname)

Returns:

  • (Pathname) 


624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File '.ruby-sass/lib/sass/util.rb', line 624

def realpath(path)
  path = Pathname.new(path) unless path.is_a?(Pathname)

  # Explicitly DON'T run #pathname here. We don't want to convert
  # to Windows directory separators because we're comparing these
  # against the paths returned by Listen, which use forward
  # slashes everywhere.
  begin
    path.realpath
  rescue SystemCallError
    # If [path] doesn't actually exist, don't bail, just
    # return the original.
    path
  end
end

#relative_path_from(path, from) ⇒ Pathname?

Returns `path` relative to `from`.

This is like `Pathname#relative_path_from` except it accepts both strings and pathnames, it handles Windows path separators correctly, and it throws an error rather than crashing if the paths use different encodings (github.com/ruby/ruby/pull/713).

Parameters:

  • path (String, Pathname)
  • from (String, Pathname)

Returns:

  • (Pathname?) 


650
651
652
653
654
655
656
657
658
659
660
 
# File '.ruby-sass/lib/sass/util.rb', line 650

def relative_path_from(path, from)
  pathname(path.to_s).relative_path_from(pathname(from.to_s))
rescue NoMethodError => e
  raise e unless e.name == :zero?

  # Work around https://github.com/ruby/ruby/pull/713.
  path = path.to_s
  from = from.to_s
  raise ArgumentError("Incompatible path encodings: #{path.inspect} is #{path.encoding}, " +
    "#{from.inspect} is #{from.encoding}")
end

#replace_subseq(arr, subseq, replacement) ⇒ Array

Non-destructively replaces all occurrences of a subsequence in an array with another subsequence.

Examples:

replace_subseq([1, 2, 3, 4, 5], [2, 3], [:a, :b])
  #=> [1, :a, :b, 4, 5]

Parameters:

  • arr (Array) —

    The array whose subsequences will be replaced.

  • subseq (Array) —

    The subsequence to find and replace.

  • replacement (Array) —

    The sequence that `subseq` will be replaced with.

Returns:

  • (Array) —

    `arr` with `subseq` replaced with `replacement`.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File '.ruby-sass/lib/sass/util.rb', line 185

def replace_subseq(arr, subseq, replacement)
  new = []
  matched = []
  i = 0
  arr.each do |elem|
    if elem != subseq[i]
      new.push(*matched)
      matched = []
      i = 0
      new << elem
      next
    end

    if i == subseq.length - 1
      matched = []
      i = 0
      new.push(*replacement)
    else
      matched << elem
      i += 1
    end
  end
  new.push(*matched)
  new
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) 


128
129
130
 
# File '.ruby-sass/lib/sass/util.rb', line 128

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

#retry_on_windows { ... } ⇒ Object

Retries a filesystem operation if it fails on Windows. Windows has weird and flaky locking rules that can cause operations to fail.

Yields:

  • The filesystem operation.



680
681
682
683
684
685
686
687
688
689
 
# File '.ruby-sass/lib/sass/util.rb', line 680

def retry_on_windows
  return yield unless windows?

  begin
    yield
  rescue SystemCallError
    sleep 0.1
    yield
  end
end

#round(value) ⇒ Numeric

Like [Fixnum.round], but leaves rooms for slight floating-point differences.

Parameters:

  • value (Numeric)

Returns:

  • (Numeric) 


137
138
139
140
141
142
143
144
145
146
147
 
# File '.ruby-sass/lib/sass/util.rb', line 137

def round(value)
  # If the number is within epsilon of X.5, round up (or down for negative
  # numbers).
  mod = value % 1
  mod_is_half = (mod - 0.5).abs < Script::Value::Number.epsilon
  if value > 0
    !mod_is_half && mod < 0.5 ? value.floor : value.ceil
  else
    mod_is_half || mod < 0.5 ? value.floor : value.ceil
  end
end

#ruby2_4? ⇒ Boolean

Whether or not this is running under Ruby 2.4 or higher.

Returns:

  • (Boolean) 


715
716
717
718
719
720
721
722
723
 
# File '.ruby-sass/lib/sass/util.rb', line 715

def ruby2_4?
  return @ruby2_4 if defined?(@ruby2_4)
  @ruby2_4 =
    if RUBY_VERSION_COMPONENTS[0] == 2
      RUBY_VERSION_COMPONENTS[1] >= 4
    else
      RUBY_VERSION_COMPONENTS[0] > 2
    end
end

#sass_warn(msg) ⇒ Object

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

Parameters:

  • msg (String) 


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

def sass_warn(msg)
  Sass.logger.warn("#{msg}\n")
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



34
35
36
 
# File '.ruby-sass/lib/sass/util.rb', line 34

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

#silence_sass_warnings { ... } ⇒ Object

Silences all Sass warnings within a block.

Yields:

  • A block in which no Sass warnings will be printed



462
463
464
465
466
467
 
# File '.ruby-sass/lib/sass/util.rb', line 462

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

#slice_by(enum) ⇒ Object 



221
222
223
224
225
226
227
228
229
230
231
232
 
# File '.ruby-sass/lib/sass/util.rb', line 221

def slice_by(enum)
  results = []
  enum.each do |value|
    key = yield(value)
    if !results.empty? && results.last.first == key
      results.last.last << value
    else
      results << [key, [value]]
    end
  end
  results
end

#sourcemap_name(css) ⇒ String

Builds a sourcemap file name given the generated CSS file name.

Parameters:

  • css (String) —

    The generated CSS file name.

Returns:

  • (String) —

    The source map file name.



883
884
885
 
# File '.ruby-sass/lib/sass/util.rb', line 883

def sourcemap_name(css)
  css + ".map"
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`



257
258
259
260
261
 
# File '.ruby-sass/lib/sass/util.rb', line 257

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) 


376
377
378
379
380
381
382
383
384
 
# File '.ruby-sass/lib/sass/util.rb', line 376

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) ⇒ Object

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



239
240
241
242
243
244
245
246
247
248
249
 
# File '.ruby-sass/lib/sass/util.rb', line 239

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

#undefined_conversion_error_char(e) ⇒ String

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

Parameters:

  • e (Encoding::UndefinedConversionError)

Returns:

  • (String) 


340
341
342
343
344
345
346
347
 
# File '.ruby-sass/lib/sass/util.rb', line 340

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

#upcase(string) ⇒ Object

Like `String.upcase`, but only ever upcases ASCII letters.



299
300
301
302
 
# File '.ruby-sass/lib/sass/util.rb', line 299

def upcase(string)
  return string.upcase unless ruby2_4?
  string.upcase(:ascii)
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) 


436
437
438
 
# File '.ruby-sass/lib/sass/util.rb', line 436

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) 


407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File '.ruby-sass/lib/sass/util.rb', line 407

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) 


547
548
549
550
 
# File '.ruby-sass/lib/sass/util.rb', line 547

def windows?
  return @windows if defined?(@windows)
  @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.



873
874
875
876
877
 
# File '.ruby-sass/lib/sass/util.rb', line 873

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