radiant 0.9.1 → 1.0.0.rc1

data/vendor/plugins/haml/lib/haml/util.rb

@@ -2,6 +2,11 @@ require 'erb'
 require 'set'
 require 'enumerator'
 require 'stringio'
+require 'strscan'
+require 'rbconfig'
+
+require 'haml/root'
+require 'haml/util/subset_map'
 
 module Haml
   # A module containing various useful functions.
@@ -9,6 +14,7 @@ module Haml
     extend self
 
     # An array of ints representing the Ruby version number.
+    # @api public
     RUBY_VERSION = ::RUBY_VERSION.split(".").map {|s| s.to_i}
 
     # Returns the path of a file relative to the Haml root directory.
@@ -16,7 +22,7 @@ module Haml
     # @param file [String] The filename relative to the Haml root
     # @return [String] The filename relative to the the working directory
     def scope(file)
-      File.join(File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__)))), file)
+      File.join(Haml::ROOT_DIR, file)
     end
 
     # Converts an array of `[key, value]` pairs to a hash.
@@ -103,6 +109,17 @@ module Haml
       end
     end
 
+    # Restricts a number to falling within a given range.
+    # Returns the number if it falls within the range,
+    # or the closest value in the range if it doesn't.
+    #
+    # @param value [Numeric]
+    # @param range [Range<Numeric>]
+    # @return [Numeric]
+    def restrict(value, range)
+      [[value, range.first].max, range.last].min
+    end
+
     # Concatenates all strings that are adjacent in an array,
     # while leaving other elements as they are.
     # For example:
@@ -113,9 +130,13 @@ module Haml
     # @param enum [Enumerable]
     # @return [Array] The enumerable with strings merged
     def merge_adjacent_strings(enum)
-      e = enum.inject([]) do |a, e|
-        if e.is_a?(String) && a.last.is_a?(String)
-          a.last << e
+      enum.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
@@ -123,6 +144,131 @@ module Haml
       end
     end
 
+    # Intersperses a value in an enumerable, as would be done with `Array#join`
+    # but without concatenating the array together afterwards.
+    #
+    # @param enum [Enumerable]
+    # @param val
+    # @return [Array]
+    def intersperse(enum, val)
+      enum.inject([]) {|a, e| a << e << val}[0...-1]
+    end
+
+    # Substitutes a sub-array of one array with another sub-array.
+    #
+    # @param ary [Array] The array in which to make the substitution
+    # @param from [Array] The sequence of elements to replace with `to`
+    # @param to [Array] The sequence of elements to replace `from` with
+    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
+
+    # 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.last.rstrip! if arr.last.is_a?(String)
+      arr
+    end
+
+    # Return an array of all possible paths through the given arrays.
+    #
+    # @param arrs [Array<Array>]
+    # @return [Array<Arrays>]
+    #
+    # @example
+    # paths([[1, 2], [3, 4], [5]]) #=>
+    #   # [[1, 3, 5],
+    #   #  [2, 3, 5],
+    #   #  [1, 4, 5],
+    #   #  [2, 4, 5]]
+    def paths(arrs)
+      arrs.inject([[]]) do |paths, arr|
+        flatten(arr.map {|e| paths.map {|path| path + [e]}}, 1)
+      end
+    end
+
+    # Computes a single longest common subsequence for `x` and `y`.
+    # If there are more than one longest common subsequences,
+    # the one returned is that which starts first in `x`.
+    #
+    # @param x [Array]
+    # @param y [Array]
+    # @yield [a, b] An optional block to use in place of a check for equality
+    #   between elements of `x` and `y`.
+    # @yieldreturn [Object, nil] If the two values register as equal,
+    #   this will return the value to use in the LCS array.
+    # @return [Array] The LCS
+    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
+
+    # Returns information about the caller of the previous method.
+    #
+    # @param entry [String] An entry in the `#caller` list, or a similarly formatted string
+    # @return [[String, Fixnum, (String, nil)]] An array containing the filename, line, and method name of the caller.
+    #   The method name may be nil
+    def caller_info(entry = caller[1])
+      info = entry.scan(/^(.*?):(-?.*?)(?::.*`(.+)')?$/).first
+      info[1] = info[1].to_i
+      # This is added by Rubinius to designate a block, but we don't care about it.
+      info[2].sub!(/ \{\}\Z/, '') if info[2]
+      info
+    end
+
+    # Returns whether one version string represents a more recent version than another.
+    #
+    # @param v1 [String] A version string.
+    # @param v2 [String] Another version string.
+    # @return [Boolean]
+    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
+
+    # Returns whether one version string represents the same or a more
+    # recent version than another.
+    #
+    # @param v1 [String] A version string.
+    # @param v2 [String] Another version string.
+    # @return [Boolean]
+    def version_geq(v1, v2)
+      version_gt(v1, v2) || !version_gt(v2, v1)
+    end
+
     # Silence all output to STDERR within a block.
     #
     # @yield A block in which no output will be printed to STDERR
@@ -133,6 +279,26 @@ module Haml
       $stderr = the_real_stderr
     end
 
+    @@silence_warnings = false
+    # Silences all Haml warnings within a block.
+    #
+    # @yield A block in which no Haml warnings will be printed
+    def silence_haml_warnings
+      old_silence_warnings = @@silence_warnings
+      @@silence_warnings = true
+      yield
+    ensure
+      @@silence_warnings = old_silence_warnings
+    end
+
+    # The same as `Kernel#warn`, but is silenced by \{#silence\_haml\_warnings}.
+    #
+    # @param msg [String]
+    def haml_warn(msg)
+      return if @@silence_warnings
+      warn(msg)
+    end
+
     ## Cross Rails Version Compatibility
 
     # Returns the root of the Rails application,
@@ -141,7 +307,10 @@ module Haml
     #
     # @return [String, nil]
     def rails_root
-      return Rails.root.to_s if defined?(Rails.root)
+      if defined?(::Rails.root)
+        return ::Rails.root.to_s if ::Rails.root
+        raise "ERROR: Rails.root is nil!"
+      end
       return RAILS_ROOT.to_s if defined?(RAILS_ROOT)
       return nil
     end
@@ -152,7 +321,7 @@ module Haml
     #
     # @return [String, nil]
     def rails_env
-      return Rails.env.to_s if defined?(Rails.root)
+      return ::Rails.env.to_s if defined?(::Rails.env)
       return RAILS_ENV.to_s if defined?(RAILS_ENV)
       return nil
     end
@@ -162,48 +331,22 @@ module Haml
     #
     # @return [Boolean]
     def ap_geq_3?
-      # The ActionPack module is always loaded automatically in Rails >= 3
-      return false unless defined?(ActionPack) && defined?(ActionPack::VERSION)
-
-      version =
-        if defined?(ActionPack::VERSION::MAJOR)
-          ActionPack::VERSION::MAJOR
-        else
-          # Rails 1.2
-          ActionPack::VERSION::Major
-        end
-
-      # 3.0.0.beta1 acts more like ActionPack 2
-      # for purposes of this method
-      # (checking whether block helpers require = or -).
-      # This extra check can be removed when beta2 is out.
-      version >= 3 &&
-        !(defined?(ActionPack::VERSION::TINY) &&
-          ActionPack::VERSION::TINY == "0.beta")
+      ap_geq?("3.0.0.beta1")
     end
 
     # Returns whether this environment is using ActionPack
-    # version 3.0.0.beta.3 or greater.
+    # of a version greater than or equal to that specified.
     #
+    # @param version [String] The string version number to check against.
+    #   Should be greater than or equal to Rails 3,
+    #   because otherwise ActionPack::VERSION isn't autoloaded
     # @return [Boolean]
-    def ap_geq_3_beta_3?
+    def ap_geq?(version)
       # The ActionPack module is always loaded automatically in Rails >= 3
-      return false unless defined?(ActionPack) && defined?(ActionPack::VERSION)
+      return false unless defined?(ActionPack) && defined?(ActionPack::VERSION) &&
+        defined?(ActionPack::VERSION::STRING)
 
-      version =
-        if defined?(ActionPack::VERSION::MAJOR)
-          ActionPack::VERSION::MAJOR
-        else
-          # Rails 1.2
-          ActionPack::VERSION::Major
-        end
-      version >= 3 &&
-        ((defined?(ActionPack::VERSION::TINY) &&
-          ActionPack::VERSION::TINY.is_a?(Fixnum) &&
-          ActionPack::VERSION::TINY >= 1) ||
-         (defined?(ActionPack::VERSION::BUILD) &&
-          ActionPack::VERSION::BUILD =~ /beta(\d+)/ &&
-          $1.to_i >= 3))
+      version_geq(ActionPack::VERSION::STRING, version)
     end
 
     # Returns an ActionView::Template* class.
@@ -256,8 +399,20 @@ module Haml
     #
     # @return [Class]
     def rails_safe_buffer_class
-      return ActionView::SafeBuffer if defined?(ActionView::SafeBuffer)
-      ActiveSupport::SafeBuffer
+      # It's important that we check ActiveSupport first,
+      # because in Rails 2.3.6 ActionView::SafeBuffer exists
+      # but is a deprecated proxy object.
+      return ActiveSupport::SafeBuffer if defined?(ActiveSupport::SafeBuffer)
+      return ActionView::SafeBuffer
+    end
+
+    ## Cross-OS Compatibility
+
+    # Whether or not this is running on Windows.
+    #
+    # @return [Boolean]
+    def windows?
+      RbConfig::CONFIG['host_os'] =~ /mswin|windows|mingw/i
     end
 
     ## Cross-Ruby-Version Compatibility
@@ -269,6 +424,154 @@ module Haml
       Haml::Util::RUBY_VERSION[0] == 1 && Haml::Util::RUBY_VERSION[1] < 9
     end
 
+    # Whether or not this is running under Ruby 1.8.6 or lower.
+    # Note that lower versions are not officially supported.
+    #
+    # @return [Boolean]
+    def ruby1_8_6?
+      ruby1_8? && Haml::Util::RUBY_VERSION[2] < 7
+    end
+
+    # Checks that the encoding of a string is valid in Ruby 1.9
+    # and cleans up potential encoding gotchas like the UTF-8 BOM.
+    # If it's not, yields an error string describing the invalid character
+    # and the line on which it occurrs.
+    #
+    # @param str [String] The string of which to check the encoding
+    # @yield [msg] A block in which an encoding error can be raised.
+    #   Only yields if there is an encoding error
+    # @yieldparam msg [String] The error message to be raised
+    # @return [String] `str`, potentially with encoding gotchas like BOMs removed
+    def check_encoding(str)
+      if ruby1_8?
+        return str.gsub(/\A\xEF\xBB\xBF/, '') # Get rid of the UTF-8 BOM
+      elsif str.valid_encoding?
+        # Get rid of the Unicode BOM if possible
+        if str.encoding.name =~ /^UTF-(8|16|32)(BE|LE)?$/
+          return str.gsub(Regexp.new("\\A\uFEFF".encode(str.encoding.name)), '')
+        else
+          return str
+        end
+      end
+
+      encoding = str.encoding
+      newlines = Regexp.new("\r\n|\r|\n".encode(encoding).force_encoding("binary"))
+      str.force_encoding("binary").split(newlines).each_with_index do |line, i|
+        begin
+          line.encode(encoding)
+        rescue Encoding::UndefinedConversionError => e
+          yield <<MSG.rstrip, i + 1
+Invalid #{encoding.name} character #{e.error_char.dump}
+MSG
+        end
+      end
+      return str
+    end
+
+    # Like {\#check\_encoding}, but also checks for a Ruby-style `-# coding:` comment
+    # at the beginning of the template and uses that encoding if it exists.
+    #
+    # The Sass encoding rules are simple.
+    # If a `-# coding:` comment exists,
+    # we assume that that's the original encoding of the document.
+    # Otherwise, we use whatever encoding Ruby has.
+    #
+    # Haml uses the same rules for parsing coding comments as Ruby.
+    # This means that it can understand Emacs-style comments
+    # (e.g. `-*- encoding: "utf-8" -*-`),
+    # and also that it cannot understand non-ASCII-compatible encodings
+    # such as `UTF-16` and `UTF-32`.
+    #
+    # @param str [String] The Haml template of which to check the encoding
+    # @yield [msg] A block in which an encoding error can be raised.
+    #   Only yields if there is an encoding error
+    # @yieldparam msg [String] The error message to be raised
+    # @return [String] The original string encoded properly
+    # @raise [ArgumentError] if the document declares an unknown encoding
+    def check_haml_encoding(str, &block)
+      return check_encoding(str, &block) if ruby1_8?
+      str = str.dup if str.frozen?
+
+      bom, encoding = parse_haml_magic_comment(str)
+      if encoding; str.force_encoding(encoding)
+      elsif bom; str.force_encoding("UTF-8")
+      end
+
+      return check_encoding(str, &block)
+    end
+
+    # Like {\#check\_encoding}, but also checks for a `@charset` declaration
+    # at the beginning of the file and uses that encoding if it exists.
+    #
+    # The Sass encoding rules are simple.
+    # If a `@charset` declaration exists,
+    # we assume that that's the original encoding of the document.
+    # Otherwise, we use whatever encoding Ruby has.
+    # Then we convert that to UTF-8 to process internally.
+    # The UTF-8 end result is what's returned by this method.
+    #
+    # @param str [String] The string of which to check the encoding
+    # @yield [msg] A block in which an encoding error can be raised.
+    #   Only yields if there is an encoding error
+    # @yieldparam msg [String] The error message to be raised
+    # @return [(String, Encoding)] The original string encoded as UTF-8,
+    #   and the source encoding of the string (or `nil` under Ruby 1.8)
+    # @raise [Encoding::UndefinedConversionError] if the source encoding
+    #   cannot be converted to UTF-8
+    # @raise [ArgumentError] if the document uses an unknown encoding with `@charset`
+    def check_sass_encoding(str, &block)
+      return check_encoding(str, &block), nil if ruby1_8?
+      # We allow any printable ASCII characters but double quotes in the charset decl
+      bin = str.dup.force_encoding("BINARY")
+      encoding = Haml::Util::ENCODINGS_TO_CHECK.find do |enc|
+        bin =~ Haml::Util::CHARSET_REGEXPS[enc]
+      end
+      charset, bom = $1, $2
+      if charset
+        charset = charset.force_encoding(encoding).encode("UTF-8")
+        if endianness = encoding[/[BL]E$/]
+          begin
+            Encoding.find(charset + endianness)
+            charset << endianness
+          rescue ArgumentError # Encoding charset + endianness doesn't exist
+          end
+        end
+        str.force_encoding(charset)
+      elsif bom
+        str.force_encoding(encoding)
+      end
+
+      str = check_encoding(str, &block)
+      return str.encode("UTF-8"), str.encoding
+    end
+
+    unless ruby1_8?
+      # @private
+      def _enc(string, encoding)
+        string.encode(encoding).force_encoding("BINARY")
+      end
+
+      # We could automatically add in any non-ASCII-compatible encodings here,
+      # but there's not really a good way to do that
+      # without manually checking that each encoding
+      # encodes all ASCII characters properly,
+      # which takes long enough to affect the startup time of the CLI.
+      ENCODINGS_TO_CHECK = %w[UTF-8 UTF-16BE UTF-16LE UTF-32BE UTF-32LE]
+
+      CHARSET_REGEXPS = Hash.new do |h, e|
+        h[e] =
+          begin
+            # /\A(?:\uFEFF)?@charset "(.*?)"|\A(\uFEFF)/
+            Regexp.new(/\A(?:#{_enc("\uFEFF", e)})?#{
+              _enc('@charset "', e)}(.*?)#{_enc('"', e)}|\A(#{
+              _enc("\uFEFF", e)})/)
+          rescue
+            # /\A@charset "(.*?)"/
+            Regexp.new(/\A#{_enc('@charset "', e)}(.*?)#{_enc('"', e)}/)
+          end
+      end
+    end
+
     # Checks to see if a class has a given method.
     # For example:
     #
@@ -295,6 +598,77 @@ module Haml
       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
+
+    # 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 `n` nested arrays in a cross-version manner.
+    #
+    # @param arr [Array] The array to flatten
+    # @param n [Fixnum] The number of levels to flatten
+    # @return [Array] The flattened array
+    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
+
+    # Returns the hash code for a set in a cross-version manner.
+    # Aggravatingly, this is order-dependent in Ruby 1.8.6.
+    #
+    # @param set [Set]
+    # @return [Fixnum] The order-independent hashcode of `set`
+    def set_hash(set)
+      return set.hash unless ruby1_8_6?
+      set.map {|e| e.hash}.uniq.sort.hash
+    end
+
+    # Tests the hash-equality of two sets in a cross-version manner.
+    # Aggravatingly, this is order-dependent in Ruby 1.8.6.
+    #
+    # @param set1 [Set]
+    # @param set2 [Set]
+    # @return [Boolean] Whether or not the sets are hashcode equal
+    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
+
+    # 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[:encoding]`
+    # before being evaluated.
+    #
+    # @param obj {Object}
+    # @return {String}
+    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
+
     ## Static Method Stuff
 
     # The context in which the ERB for \{#def\_static\_method} will be run.
@@ -348,9 +722,10 @@ module Haml
     # @param erb [String] The template for the method code
     def def_static_method(klass, name, args, *vars)
       erb = vars.pop
+      info = caller_info
       powerset(vars).each do |set|
         context = StaticConditionalContext.new(set).instance_eval {binding}
-        klass.class_eval(<<METHOD)
+        klass.class_eval(<<METHOD, info[0], info[1])
 def #{static_method_name(name, *vars.map {|v| set.include?(v)})}(#{args.join(', ')})
   #{ERB.new(erb).result(context)}
 end
@@ -366,5 +741,69 @@ METHOD
     def static_method_name(name, *vars)
       "#{name}_#{vars.map {|v| !!v}.join('_')}"
     end
+
+    private
+
+    # 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)
+      c = Array.new(x.size) {[]}
+      x.size.times {|i| c[i][0] = 0}
+      y.size.times {|j| c[0][j] = 0}
+      (1...x.size).each do |i|
+        (1...y.size).each do |j|
+          c[i][j] =
+            if yield x[i], y[j]
+              c[i-1][j-1] + 1
+            else
+              [c[i][j-1], c[i-1][j]].max
+            end
+        end
+      end
+      return c
+    end
+
+    # 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)
+      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
+      end
+
+      return lcs_backtrace(c, x, y, i, j-1, &block) if c[i][j-1] > c[i-1][j]
+      return lcs_backtrace(c, x, y, i-1, j, &block)
+    end
+
+    # Parses a magic comment at the beginning of a Haml file.
+    # The parsing rules are basically the same as Ruby's.
+    #
+    # @return [(Boolean, String or nil)]
+    #   Whether the document begins with a UTF-8 BOM,
+    #   and the declared encoding of the document (or nil if none is declared)
+    def parse_haml_magic_comment(str)
+      scanner = StringScanner.new(str.dup.force_encoding("BINARY"))
+      bom = scanner.scan(/\xEF\xBB\xBF/n)
+      return bom unless scanner.scan(/-\s*#\s*/n)
+      if coding = try_parse_haml_emacs_magic_comment(scanner)
+        return bom, coding
+      end
+
+      return bom unless scanner.scan(/.*?coding[=:]\s*([\w-]+)/in)
+      return bom, scanner[1]
+    end
+
+    def try_parse_haml_emacs_magic_comment(scanner)
+      pos = scanner.pos
+      return unless scanner.scan(/.*?-\*-\s*/n)
+      # From Ruby's parse.y
+      return unless scanner.scan(/([^\s'":;]+)\s*:\s*("(?:\\.|[^"])*"|[^"\s;]+?)[\s;]*-\*-/n)
+      name, val = scanner[1], scanner[2]
+      return unless name =~ /(en)?coding/in
+      val = $1 if val =~ /^"(.*)"$/n
+      return val
+    ensure
+      scanner.pos = pos
+    end
   end
 end