sass 3.7.4 → 4.0.0.alpha.1

data/lib/sass/util.rb

@@ -33,6 +33,17 @@ module Sass
       File.join(Sass::ROOT_DIR, file)
     end
 
+    # Converts an array of `[key, value]` pairs to a hash.
+    #
+    # @example
+    #   to_hash([[:foo, "bar"], [:baz, "bang"]])
+    #     #=> {:foo => "bar", :baz => "bang"}
+    # @param arr [Array<(Object, Object)>] An array of pairs
+    # @return [Hash] A hash
+    def to_hash(arr)
+      ordered_hash(*arr.compact)
+    end
+
     # Maps the keys in a hash according to a block.
     #
     # @example
@@ -135,13 +146,8 @@ module Sass
     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
+      return value.round if (value % 1) - 0.5 <= -1 * Script::Value::Number.epsilon
+      value > 0 ? value.ceil : value.floor
     end
 
     # Concatenates all strings that are adjacent in an array,
@@ -246,67 +252,18 @@ module Sass
       res
     end
 
-    # Destructively strips whitespace from the beginning and end of the first
-    # and last elements, respectively, in the array (if those elements are
-    # strings). Preserves CSS escapes at the end of the array.
+    # Destructively strips whitespace from the beginning and end
+    # of the first and last elements, respectively,
+    # in the array (if those elements are strings).
     #
     # @param arr [Array]
     # @return [Array] `arr`
     def strip_string_array(arr)
       arr.first.lstrip! if arr.first.is_a?(String)
-      arr[-1] = Sass::Util.rstrip_except_escapes(arr[-1]) if arr.last.is_a?(String)
+      arr.last.rstrip! if arr.last.is_a?(String)
       arr
     end
 
-    # Normalizes identifier escapes.
-    #
-    # See https://github.com/sass/language/blob/master/accepted/identifier-escapes.md.
-    #
-    # @param ident [String]
-    # @return [String]
-    def normalize_ident_escapes(ident, start: true)
-      ident.gsub(/(^)?(#{Sass::SCSS::RX::ESCAPE})/) do |s|
-        at_start = start && $1
-        char = escaped_char(s)
-        next char if char =~ (at_start ? Sass::SCSS::RX::NMSTART : Sass::SCSS::RX::NMCHAR)
-        if char =~ (at_start ? /[\x0-\x1F\x7F0-9]/ : /[\x0-\x1F\x7F]/)
-          "\\#{char.ord.to_s(16)} "
-        else
-          "\\#{char}"
-        end
-      end
-    end
-
-    # Returns the character encoded by the given escape sequence.
-    #
-    # @param escape [String]
-    # @return [String]
-    def escaped_char(escape)
-      if escape =~ /^\\([0-9a-fA-F]{1,6})[ \t\r\n\f]?/
-        $1.to_i(16).chr(Encoding::UTF_8)
-      else
-        escape[1]
-      end
-    end
-
-    # Like [String#strip], but preserves escaped whitespace at the end of the
-    # string.
-    #
-    # @param string [String]
-    # @return [String]
-    def strip_except_escapes(string)
-      rstrip_except_escapes(string.lstrip)
-    end
-
-    # Like [String#rstrip], but preserves escaped whitespace at the end of the
-    # string.
-    #
-    # @param string [String]
-    # @return [String]
-    def rstrip_except_escapes(string)
-      string.sub(/(?<!\\)\s+$/, '')
-    end
-
     # Return an array of all possible paths through the given arrays.
     #
     # @param arrs [Array<Array>]
@@ -342,16 +299,42 @@ module Sass
       lcs_backtrace(lcs_table(x, y, &block), x, y, x.size - 1, y.size - 1, &block)
     end
 
-    # Like `String.upcase`, but only ever upcases ASCII letters.
-    def upcase(string)
-      return string.upcase unless ruby2_4?
-      string.upcase(:ascii)
+    # 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).
+    #
+    # @param hash [Hash]
+    # @return [Array]
+    def hash_to_a(hash)
+      return hash.to_a unless ruby1_8? || defined?(Test::Unit)
+      hash.sort_by {|k, v| k}
     end
 
-    # Like `String.downcase`, but only ever downcases ASCII letters.
-    def downcase(string)
-      return string.downcase unless ruby2_4?
-      string.downcase(:ascii)
+    # Performs the equivalent of `enum.group_by.to_a`, but with a guaranteed
+    # order. Unlike {Util#hash_to_a}, the resulting order isn't sorted key order;
+    # instead, it's the same order as `#group_by` has under Ruby 1.9 (key
+    # appearance order).
+    #
+    # @param enum [Enumerable]
+    # @return [Array<[Object, Array]>] An array of pairs.
+    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
 
     # Returns a sub-array of `minuend` containing only elements that are also in
@@ -433,7 +416,7 @@ module Sass
     # Returns information about the caller of the previous method.
     #
     # @param entry [String] An entry in the `#caller` list, or a similarly formatted string
-    # @return [[String, Integer, (String, nil)]]
+    # @return [[String, Fixnum, (String, nil)]]
     #   An array containing the filename, line, and method name of the caller.
     #   The method name may be nil
     def caller_info(entry = nil)
@@ -503,6 +486,16 @@ module Sass
       Sass::Util.sass_warn full_message
     end
 
+    # Silence all output to STDERR within a block.
+    #
+    # @yield A block in which no output will be printed to STDERR
+    def silence_warnings
+      the_real_stderr, $stderr = $stderr, StringIO.new
+      yield
+    ensure
+      $stderr = the_real_stderr
+    end
+
     # Silences all Sass warnings within a block.
     #
     # @yield A block in which no Sass warnings will be printed
@@ -517,7 +510,8 @@ module Sass
     #
     # @param msg [String]
     def sass_warn(msg)
-      Sass.logger.warn("#{msg}\n")
+      msg = msg + "\n" unless ruby1?
+      Sass.logger.warn(msg)
     end
 
     ## Cross Rails Version Compatibility
@@ -570,6 +564,24 @@ module Sass
       version_geq(ActionPack::VERSION::STRING, version)
     end
 
+    # Returns whether this environment is using Listen
+    # version 2.0.0 or greater.
+    #
+    # @return [Boolean]
+    def listen_geq_2?
+      return @listen_geq_2 unless @listen_geq_2.nil?
+      @listen_geq_2 =
+        begin
+          # Make sure we're loading listen/version from the same place that
+          # we're loading listen itself.
+          load_listen!
+          require 'listen/version'
+          version_geq(::Listen::VERSION, '2.0.0')
+        rescue LoadError
+          false
+        end
+    end
+
     # Returns an ActionView::Template* class.
     # In pre-3.0 versions of Rails, most of these classes
     # were of the form `ActionView::TemplateFoo`,
@@ -622,7 +634,7 @@ module Sass
 
     # Returns an array of ints representing the JRuby version number.
     #
-    # @return [Array<Integer>]
+    # @return [Array<Fixnum>]
     def jruby_version
       @jruby_version ||= ::JRUBY_VERSION.split(".").map {|s| s.to_i}
     end
@@ -631,7 +643,7 @@ module Sass
     #
     # @param path [String]
     def glob(path)
-      path = path.tr('\\', '/') if windows?
+      path = path.gsub('\\', '/') if windows?
       if block_given?
         Dir.glob(path) {|f| yield(f)}
       else
@@ -713,10 +725,10 @@ module Sass
     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)
+      path = Sass::Util.escape_uri(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{\\\\[^\\]+\\[^\\/]+}
+      return "file:///" + path.tr("\\", "/") if path =~ /^[a-zA-Z]:[\/\\]/
+      return "file:" + path.tr("\\", "/") if path =~ /\\\\[^\\]+\\[^\\\/]+/
       path.tr("\\", "/")
     end
 
@@ -748,25 +760,87 @@ module Sass
       val || []
     end
 
-    CHARSET_REGEXP = /\A@charset "([^"]+)"/
-    bom = "\uFEFF"
-    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')
-
     ## Cross-Ruby-Version Compatibility
 
-    # Whether or not this is running under Ruby 2.4 or higher.
+    # Whether or not this is running under a Ruby version under 2.0.
     #
     # @return [Boolean]
-    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
+    def ruby1?
+      return @ruby1 if defined?(@ruby1)
+      @ruby1 = RUBY_VERSION_COMPONENTS[0] <= 1
+    end
+
+    # Whether or not this is running under Ruby 1.8 or lower.
+    #
+    # Note that IronRuby counts as Ruby 1.8,
+    # because it doesn't support the Ruby 1.9 encoding API.
+    #
+    # @return [Boolean]
+    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
+
+    # Whether or not this is running under Ruby 1.9.2 exactly.
+    #
+    # @return [Boolean]
+    def ruby1_9_2?
+      return @ruby1_9_2 if defined?(@ruby1_9_2)
+      @ruby1_9_2 = RUBY_VERSION_COMPONENTS == [1, 9, 2]
+    end
+
+    # Wehter or not this is running under JRuby 1.6 or lower.
+    def jruby1_6?
+      return @jruby1_6 if defined?(@jruby1_6)
+      @jruby1_6 = jruby? && jruby_version[0] == 1 && jruby_version[1] < 7
+    end
+
+    # Whether or not this is running under MacRuby.
+    #
+    # @return [Boolean]
+    def macruby?
+      return @macruby if defined?(@macruby)
+      @macruby = RUBY_ENGINE == 'macruby'
+    end
+
+    require 'sass/util/ordered_hash' if ruby1_8?
+
+    # 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.
+    #
+    # @overload ordered_hash(hash)
+    #   @param hash [Hash] a normal hash to convert to an ordered hash
+    #   @return [Hash]
+    # @overload ordered_hash(*pairs)
+    #   @example
+    #     ordered_hash([:foo, "bar"], [:baz, "bang"])
+    #       #=> {:foo => "bar", :baz => "bang"}
+    #     ordered_hash #=> {}
+    #   @param pairs [Array<(Object, Object)>] the list of key/value pairs for
+    #     the hash.
+    #   @return [Hash]
+    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)[*pairs_or_hash.flatten(1)]
+    end
+
+    unless ruby1_8?
+      CHARSET_REGEXP = /\A@charset "([^"]+)"/
+      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')
     end
 
     # Like {\#check\_encoding}, but also checks for a `@charset` declaration
@@ -776,7 +850,7 @@ module Sass
     #
     # @param str [String] The string of which to check the encoding
     # @return [(String, Encoding)] The original string encoded as UTF-8,
-    #   and the source encoding of the string
+    #   and the source encoding of the string (or `nil` under Ruby 1.8)
     # @raise [Encoding::UndefinedConversionError] if the source encoding
     #   cannot be converted to UTF-8
     # @raise [ArgumentError] if the document uses an unknown encoding with `@charset`
@@ -784,6 +858,15 @@ module Sass
     #   doesn't match its contents, or it doesn't declare an encoding and its
     #   contents are invalid in the native encoding.
     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
@@ -799,9 +882,14 @@ module Sass
         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'
+        # 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"
@@ -821,6 +909,50 @@ module Sass
       end
     end
 
+    # 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.
+    #
+    # @param attr [#to_s] The (singular) name of the method-collection method
+    #   (e.g. `:instance_methods`, `:private_methods`)
+    # @param klass [Module] The class to check the methods of which to check
+    # @param method [String, Symbol] The name of the method do check for
+    # @return [Boolean] Whether or not the given collection has the given method
+    def has?(attr, klass, method)
+      klass.send("#{attr}s").include?(ruby1_8? ? method.to_s : method.to_sym)
+    end
+
+    # A version of `Enumerable#enum_with_index` that works in Ruby 1.8 and 1.9.
+    #
+    # @param enum [Enumerable] The enumerable to get the enumerator for
+    # @return [Enumerator] The with-index enumerator
+    def enum_with_index(enum)
+      ruby1_8? ? enum.enum_with_index : enum.each_with_index
+    end
+
+    # A version of `Enumerable#enum_cons` that works in Ruby 1.8 and 1.9.
+    #
+    # @param enum [Enumerable] The enumerable to get the enumerator for
+    # @param n [Fixnum] The size of each cons
+    # @return [Enumerator] The consed enumerator
+    def enum_cons(enum, n)
+      ruby1_8? ? enum.enum_cons(n) : enum.each_cons(n)
+    end
+
+    # A version of `Enumerable#enum_slice` that works in Ruby 1.8 and 1.9.
+    #
+    # @param enum [Enumerable] The enumerable to get the enumerator for
+    # @param n [Fixnum] The size of each slice
+    # @return [Enumerator] The consed enumerator
+    def enum_slice(enum, n)
+      ruby1_8? ? enum.enum_slice(n) : enum.each_slice(n)
+    end
+
     # Destructively removes all elements from an array that match a block, and
     # returns the removed elements.
     #
@@ -839,6 +971,14 @@ module Sass
       out
     end
 
+    # Returns the ASCII code of the given character.
+    #
+    # @param c [String] All characters but the first are ignored.
+    # @return [Fixnum] The ASCII code of `c`.
+    def ord(c)
+      ruby1_8? ? c[0] : c.ord
+    end
+
     # 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.
@@ -959,11 +1099,11 @@ module Sass
 
     # Converts the argument into a valid JSON value.
     #
-    # @param v [Integer, String, Array, Boolean, nil]
+    # @param v [Fixnum, String, Array, Boolean, nil]
     # @return [String]
     def json_value_of(v)
       case v
-      when Integer
+      when Fixnum
         v.to_s
       when String
         "\"" + json_escape_string(v) + "\""
@@ -985,10 +1125,10 @@ module Sass
     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_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|
+      Sass::Util.enum_with_index(BASE64_DIGITS).map do |digit, i|
         map[digit] = i
       end
       map
@@ -996,7 +1136,7 @@ module Sass
 
     # Encodes `value` as VLQ (http://en.wikipedia.org/wiki/VLQ).
     #
-    # @param value [Integer]
+    # @param value [Fixnum]
     # @return [String] The encoded value
     def encode_vlq(value)
       if value < 0
@@ -1017,6 +1157,35 @@ module Sass
       result
     end
 
+    # This is a hack around the fact that you can't instantiate a URI parser on
+    # 1.8, so we have to have this hacky stuff to work around it. When 1.8
+    # support is dropped, we can remove this method.
+    #
+    # @private
+    URI_ESCAPE = URI.const_defined?("DEFAULT_PARSER") ? URI::DEFAULT_PARSER : URI
+
+    # URI-escape `string`.
+    #
+    # @param string [String]
+    # @return [String]
+    def escape_uri(string)
+      URI_ESCAPE.escape string
+    end
+
+    # A cross-platform implementation of `File.absolute_path`.
+    #
+    # @param path [String]
+    # @param dir_string [String] The directory to consider [path] relative to.
+    # @return [String] The absolute version of `path`.
+    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
+
     ## Static Method Stuff
 
     # The context in which the ERB for \{#def\_static\_method} will be run.
@@ -1074,6 +1243,44 @@ module Sass
       tmpfile.unlink if tmpfile
     end
 
+    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 = "~> 3.0"
+            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
+
     private
 
     def find_encoding_error(str)
@@ -1097,10 +1304,13 @@ module Sass
       return str, str.encoding
     end
 
+    # rubocop:disable LineLength
+
     # Calculates the memoization table for the Least Common Subsequence algorithm.
     # Algorithm from [Wikipedia](http://en.wikipedia.org/wiki/Longest_common_subsequence_problem#Computing_the_length_of_the_LCS)
     def lcs_table(x, y)
       # This method does not take a block as an explicit parameter for performance reasons.
+      # rubocop:enable LineLength
       c = Array.new(x.size) {[]}
       x.size.times {|i| c[i][0] = 0}
       y.size.times {|j| c[0][j] = 0}
@@ -1116,10 +1326,12 @@ module Sass
       end
       c
     end
+    # rubocop:disable ParameterLists, LineLength
 
     # Computes a single longest common subsequence for arrays x and y.
     # Algorithm from [Wikipedia](http://en.wikipedia.org/wiki/Longest_common_subsequence_problem#Reading_out_an_LCS)
     def lcs_backtrace(c, x, y, i, j, &block)
+      # rubocop:enable ParameterList, LineLengths
       return [] if i == 0 || j == 0
       if (v = yield(x[i], y[j]))
         return lcs_backtrace(c, x, y, i - 1, j - 1, &block) << v
@@ -1135,3 +1347,4 @@ end
 
 require 'sass/util/multibyte_string_scanner'
 require 'sass/util/normalized_map'
+require 'sass/util/cross_platform_random'