Module: Sass::Util

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

Overview

A module containing various useful functions.

Defined Under Namespace

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

Constant Summary collapse

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 =
/\[email protected] "([^"]+)"/
UTF_8_BOM =
"\xEF\xBB\xBF".force_encoding('BINARY')
UTF_16BE_BOM =
"\xFE\xFF".force_encoding('BINARY')
UTF_16LE_BOM =
"\xFF\xFE".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 = {}
  Sass::Util.enum_with_index(BASE64_DIGITS).map do |digit, i|
    map[digit] = i
  end
  map
end

Instance Method Summary collapse

Instance Method Details

#absolute_path(path, dir_string = nil) ⇒ String

A cross-platform implementation of File.absolute_path.


1206
1207
1208
1209
1210
1211
1212
1213
# File 'lib/sass/util.rb', line 1206

def absolute_path(path, dir_string = nil)
  # Ruby 1.8 doesn't support File.absolute_path.
  return File.absolute_path(path, dir_string) unless ruby1_8?

  # File.expand_path expands "~", which we don't want.
  return File.expand_path(path, dir_string) unless path[0] == ?~
  File.expand_path(File.join(".", path), dir_string)
end

#abstract(obj)

Throws a NotImplementedError for an abstract method.

Raises:

  • (NotImplementedError)

462
463
464
# File 'lib/sass/util.rb', line 462

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.


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

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.


536
537
538
# File 'lib/sass/util.rb', line 536

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


335
336
337
338
339
# File 'lib/sass/util.rb', line 335

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

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.

Yield Parameters:

  • tmpfile (Tempfile)

    The temp file that can be written to.


1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
# File 'lib/sass/util.rb', line 1249

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)

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.


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

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, Fixnum, (String, nil)]

Returns information about the caller of the previous method.


410
411
412
413
414
415
416
417
418
# File 'lib/sass/util.rb', line 410

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.

Raises:

  • (ArgumentError)

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

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.

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.


854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
# File 'lib/sass/util.rb', line 854

def check_sass_encoding(str)
  # On Ruby 1.8 we can't do anything complicated with encodings.
  # Instead, we just strip out a UTF-8 BOM if it exists and
  # sanitize according to Section 3.3 of CSS Syntax Level 3. We
  # don't sanitize null characters since they might be components
  # of other characters.
  if ruby1_8?
    return str.gsub(/\A\xEF\xBB\xBF/, '').gsub(/\r\n?|\f/, "\n"), nil
  end

  # 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')
    # Ruby 1.9.2 doesn't recognize a UTF-16 encoding without an endian marker.
    if ruby1_9_2? && charset.downcase == 'utf-16'
      encoding = Encoding.find('UTF-8')
    else
      encoding = Encoding.find(charset)
      if encoding.name == 'UTF-16' || encoding.name == 'UTF-16BE'
        encoding = Encoding.find('UTF-8')
      end
    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.


659
660
661
662
# File 'lib/sass/util.rb', line 659

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

#deprecated(obj, message = nil)

Prints a deprecation warning for the caller method.


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

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.


744
745
746
# File 'lib/sass/util.rb', line 744

def destructure(val)
  val || []
end

#encode_vlq(value) ⇒ String

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


1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
# File 'lib/sass/util.rb', line 1167

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

#enum_cons(enum, n) ⇒ Enumerator

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


937
938
939
# File 'lib/sass/util.rb', line 937

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.


946
947
948
# File 'lib/sass/util.rb', line 946

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.


928
929
930
# File 'lib/sass/util.rb', line 928

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

#escape_uri(string) ⇒ String

URI-escape string.


1197
1198
1199
# File 'lib/sass/util.rb', line 1197

def escape_uri(string)
  URI_ESCAPE.escape string
end

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

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

Yields:

  • (el)

    Called for each element.

Yield Parameters:

  • el (*)

    The element to test.

Yield Returns:

  • (Boolean)

    Whether or not to extract the element.


958
959
960
961
962
963
964
965
966
# File 'lib/sass/util.rb', line 958

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.


1052
1053
1054
1055
1056
1057
1058
1059
1060
# File 'lib/sass/util.rb', line 1052

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.


710
711
712
713
714
715
716
717
718
# File 'lib/sass/util.rb', line 710

def file_uri_from_path(path)
  path = path.to_s if path.is_a?(Pathname)
  path = path.tr('\\', '/') if windows?
  path = Sass::Util.escape_uri(path)
  return path.start_with?('/') ? "file://" + path : path unless windows?
  return "file:///" + path.tr("\\", "/") if path =~ /^[a-zA-Z]:[\/\\]/
  return "file:" + path.tr("\\", "/") if path =~ /\\\\[^\\]+\\[^\\\/]+/
  path.tr("\\", "/")
end

#flatten(arr, n) ⇒ Array

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


981
982
983
984
985
# File 'lib/sass/util.rb', line 981

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

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


993
994
995
996
997
998
999
1000
1001
1002
1003
# File 'lib/sass/util.rb', line 993

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)

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


630
631
632
633
634
635
636
637
# File 'lib/sass/util.rb', line 630

def glob(path)
  path = path.gsub('\\', '/') if windows?
  if block_given?
    Dir.glob(path) {|f| yield(f)}
  else
    Dir.glob(path)
  end
end

#group_by_to_a(enum) ⇒ 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).


311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
# File 'lib/sass/util.rb', line 311

def group_by_to_a(enum)
  return enum.group_by {|e| yield(e)}.to_a unless ruby1_8?
  order = {}
  arr = []
  groups = enum.group_by do |e|
    res = yield(e)
    unless order.include?(res)
      order[res] = order.size
    end
    res
  end
  groups.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.


920
921
922
# File 'lib/sass/util.rb', line 920

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

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

def hash_to_a(hash)
  return hash.to_a unless ruby1_8? || defined?(Test::Unit)
  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.


1068
1069
1070
1071
1072
1073
1074
1075
1076
# File 'lib/sass/util.rb', line 1068

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.


1033
1034
1035
1036
1037
1038
# File 'lib/sass/util.rb', line 1033

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.


209
210
211
# File 'lib/sass/util.rb', line 209

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

#ironruby?Boolean

Whether or not this is running on IronRuby.


599
600
601
602
# File 'lib/sass/util.rb', line 599

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

#jruby1_6?Boolean

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


790
791
792
793
# File 'lib/sass/util.rb', line 790

def jruby1_6?
  return @jruby1_6 if defined?(@jruby1_6)
  @jruby1_6 = jruby? && jruby_version[0] == 1 && jruby_version[1] < 7
end

#jruby?Boolean

Whether or not this is running on JRuby.


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

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

#jruby_versionArray<Fixnum>

Returns an array of ints representing the JRuby version number.


623
624
625
# File 'lib/sass/util.rb', line 623

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.


1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
# File 'lib/sass/util.rb', line 1106

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.


1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
# File 'lib/sass/util.rb', line 1130

def json_value_of(v)
  case v
  when Fixnum
    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.

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.


283
284
285
286
287
288
# File 'lib/sass/util.rb', line 283

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

#listen_geq_2?Boolean

Returns whether this environment is using Listen version 2.0.0 or greater.


559
560
561
562
563
564
565
566
567
568
# File 'lib/sass/util.rb', line 559

def listen_geq_2?
  return @listen_geq_2 unless @listen_geq_2.nil?
  @listen_geq_2 =
    begin
      require 'listen/version'
      version_geq(::Listen::VERSION, '2.0.0')
    rescue LoadError
      false
    end
end

#load_listen!


1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
# File 'lib/sass/util.rb', line 1272

def load_listen!
  if defined?(gem)
    begin
      gem 'listen', '>= 1.1.0', '< 3.0.0'
      require 'listen'
    rescue Gem::LoadError
      dir = scope("vendor/listen/lib")
      $LOAD_PATH.unshift dir
      begin
        require 'listen'
      rescue LoadError => e
        if version_geq(RUBY_VERSION, "1.9.3")
          version_constraint = "~> 2.7"
        else
          version_constraint = "~> 1.1"
        end
        e.message << "\n" <<
          "Run \"gem install listen --version '#{version_constraint}'\" to get it."
        raise e
      end
    end
  else
    begin
      require 'listen'
    rescue LoadError => e
      dir = scope("vendor/listen/lib")
      if $LOAD_PATH.include?(dir)
        raise e unless File.exist?(scope(".git"))
        e.message << "\n" <<
          'Run "git submodule update --init" to get the bundled version.'
      else
        $LOAD_PATH.unshift dir
        retry
      end
    end
  end
end

#macruby?Boolean

Whether or not this is running under MacRuby.


798
799
800
801
# File 'lib/sass/util.rb', line 798

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

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

See Also:


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

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"}

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

See Also:


59
60
61
# File 'lib/sass/util.rb', line 59

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}

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

See Also:


75
76
77
78
79
80
81
82
83
84
# File 'lib/sass/util.rb', line 75

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)

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


343
344
345
# File 'lib/sass/util.rb', line 343

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

149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
# File 'lib/sass/util.rb', line 149

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)

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


349
350
351
# File 'lib/sass/util.rb', line 349

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

#ord(c) ⇒ Fixnum

Returns the ASCII code of the given character.


972
973
974
# File 'lib/sass/util.rb', line 972

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

#ordered_hash(hash) ⇒ Hash #ordered_hash(*pairs) ⇒ Hash

Converts a hash or a list of pairs into an order-preserving hash.

On Ruby 1.8.7, this uses the orderedhash gem to simulate an order-preserving hash. On Ruby 1.9 and up, it just uses the native Hash class, since that preserves the order itself.

Overloads:

  • #ordered_hash(*pairs) ⇒ Hash

    Examples:

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

822
823
824
825
826
827
828
829
830
831
# File 'lib/sass/util.rb', line 822

def ordered_hash(*pairs_or_hash)
  if pairs_or_hash.length == 1 && pairs_or_hash.first.is_a?(Hash)
    hash = pairs_or_hash.first
    return hash unless ruby1_8?
    return OrderedHash.new.merge hash
  end

  return Hash[pairs_or_hash] unless ruby1_8?
  (pairs_or_hash.is_a?(NormalizedMap) ? NormalizedMap : OrderedHash)[*flatten(pairs_or_hash, 1)]
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.


647
648
649
650
# File 'lib/sass/util.rb', line 647

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

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

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

119
120
121
122
123
124
125
126
127
128
# File 'lib/sass/util.rb', line 119

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_envString?

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


526
527
528
529
530
# File 'lib/sass/util.rb', line 526

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

#rails_rootString?

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


512
513
514
515
516
517
518
519
# File 'lib/sass/util.rb', line 512

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.


607
608
609
610
# File 'lib/sass/util.rb', line 607

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

#realpath(path) ⇒ Pathname

Returns path with all symlinks resolved.


668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
# File 'lib/sass/util.rb', line 668

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 (https://github.com/ruby/ruby/pull/713).


694
695
696
697
698
699
700
701
702
703
704
# File 'lib/sass/util.rb', line 694

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]

177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# File 'lib/sass/util.rb', line 177

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.


137
138
139
# File 'lib/sass/util.rb', line 137

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

#retry_on_windows { ... }

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.


724
725
726
727
728
729
730
731
732
733
# File 'lib/sass/util.rb', line 724

def retry_on_windows
  return yield unless windows?

  begin
    yield
  rescue SystemCallError
    sleep 0.1
    yield
  end
end

#ruby1?Boolean

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


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

def ruby1?
  return @ruby1 if defined?(@ruby1)
  @ruby1 = RUBY_VERSION_COMPONENTS[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.


764
765
766
767
768
769
770
# File 'lib/sass/util.rb', line 764

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.
  return @ruby1_8 if defined?(@ruby1_8)
  @ruby1_8 = ironruby? ||
               (RUBY_VERSION_COMPONENTS[0] == 1 && RUBY_VERSION_COMPONENTS[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.


776
777
778
779
# File 'lib/sass/util.rb', line 776

def ruby1_8_6?
  return @ruby1_8_6 if defined?(@ruby1_8_6)
  @ruby1_8_6 = ruby1_8? && RUBY_VERSION_COMPONENTS[2] < 7
end

#ruby1_9_2?Boolean

Whether or not this is running under Ruby 1.9.2 exactly.


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

def ruby1_9_2?
  return @ruby1_9_2 if defined?(@ruby1_9_2)
  @ruby1_9_2 = RUBY_VERSION_COMPONENTS == [1, 9, 2]
end

#sass_warn(msg)

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


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

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.


32
33
34
# File 'lib/sass/util.rb', line 32

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.


1021
1022
1023
1024
# File 'lib/sass/util.rb', line 1021

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.


1010
1011
1012
1013
# File 'lib/sass/util.rb', line 1010

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


490
491
492
493
494
495
# File 'lib/sass/util.rb', line 490

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


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

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

#slice_by(enum)


213
214
215
216
217
218
219
220
221
222
223
224
# File 'lib/sass/util.rb', line 213

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.


1096
1097
1098
# File 'lib/sass/util.rb', line 1096

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


249
250
251
252
253
# File 'lib/sass/util.rb', line 249

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


394
395
396
397
398
399
400
401
402
# File 'lib/sass/util.rb', line 394

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.


231
232
233
234
235
236
237
238
239
240
241
# File 'lib/sass/util.rb', line 231

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"}

43
44
45
# File 'lib/sass/util.rb', line 43

def to_hash(arr)
  ordered_hash(*arr.compact)
end

#undefined_conversion_error_char(e) ⇒ String

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


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

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.


454
455
456
# File 'lib/sass/util.rb', line 454

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.


425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
# File 'lib/sass/util.rb', line 425

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.


591
592
593
594
# File 'lib/sass/util.rb', line 591

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.

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.


1086
1087
1088
1089
1090
# File 'lib/sass/util.rb', line 1086

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