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 =
/\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')
- 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
-
#absolute_path(path, dir_string = nil) ⇒ String
A cross-platform implementation of
File.absolute_path
. -
#abstract(obj)
Throws a NotImplementedError for an abstract method.
-
#ap_geq?(version) ⇒ Boolean
Returns whether this environment is using ActionPack of a version greater than or equal to that specified.
-
#ap_geq_3? ⇒ Boolean
Returns whether this environment is using ActionPack version 3.0.0 or greater.
-
#array_minus(minuend, subtrahend) ⇒ Array
Returns a sub-array of
minuend
containing only elements that are also insubtrahend
. -
#atomic_create_and_write_file(filename, perms = 0666) {|tmpfile| ... }
This creates a temp file and yields it for writing.
-
#av_template_class(name)
Returns an ActionView::Template* class.
-
#caller_info(entry = nil) ⇒ [String, Fixnum, (String, nil)]
Returns information about the caller of the previous method.
-
#check_range(name, range, value, unit = '') ⇒ Numeric
Asserts that
value
falls withinrange
(inclusive), leaving room for slight floating-point errors. -
#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. -
#cleanpath(path) ⇒ Pathname
Like
Pathname#cleanpath
, but normalizes Windows paths to always use backslash separators. -
#deprecated(obj, message = nil)
Prints a deprecation warning for the caller method.
-
#destructure(val) ⇒ Object
Prepare a value for a destructuring assignment (e.g.
a, b = val
). -
#encode_vlq(value) ⇒ String
Encodes
value
as VLQ (http://en.wikipedia.org/wiki/VLQ). -
#enum_cons(enum, n) ⇒ Enumerator
A version of
Enumerable#enum_cons
that works in Ruby 1.8 and 1.9. -
#enum_slice(enum, n) ⇒ Enumerator
A version of
Enumerable#enum_slice
that works in Ruby 1.8 and 1.9. -
#enum_with_index(enum) ⇒ Enumerator
A version of
Enumerable#enum_with_index
that works in Ruby 1.8 and 1.9. -
#escape_uri(string) ⇒ String
URI-escape
string
. -
#extract!(array) {|el| ... } ⇒ Array
Destructively removes all elements from an array that match a block, and returns the removed elements.
-
#extract_values(arr) ⇒ (String, Array)
Extracts the non-string vlaues from an array containing both strings and non-strings.
-
#file_uri_from_path(path) ⇒ String
Converts
path
to a "file:" URI. -
#flatten(arr, n) ⇒ Array
Flattens the first
n
nested arrays in a cross-version manner. -
#flatten_vertically(arrs) ⇒ Array
Flattens the first level of nested arrays in
arrs
. -
#glob(path)
Like
Dir.glob
, but works with backslash-separated paths on Windows. -
#group_by_to_a(enum) ⇒ Array<[Object, Array]>
Performs the equivalent of
enum.group_by.to_a
, but with a guaranteed order. -
#has?(attr, klass, method) ⇒ Boolean
Checks to see if a class has a given method.
-
#hash_to_a(hash) ⇒ Array
Converts a Hash to an Array.
-
#inject_values(str, values) ⇒ Array
Undoes #extract_values by transforming a string with escape sequences into an array of strings and non-string values.
-
#inspect_obj(obj) ⇒ String
Like
Object#inspect
, but preserves non-ASCII characters rather than escaping them under Ruby 1.9.2. -
#intersperse(enum, val) ⇒ Array
Intersperses a value in an enumerable, as would be done with
Array#join
but without concatenating the array together afterwards. -
#ironruby? ⇒ Boolean
Whether or not this is running on IronRuby.
-
#jruby1_6? ⇒ Boolean
Wehter or not this is running under JRuby 1.6 or lower.
-
#jruby? ⇒ Boolean
Whether or not this is running on JRuby.
-
#jruby_version ⇒ Array<Fixnum>
Returns an array of ints representing the JRuby version number.
-
#json_escape_string(s) ⇒ String
Escapes certain characters so that the result can be used as the JSON string value.
-
#json_value_of(v) ⇒ String
Converts the argument into a valid JSON value.
-
#lcs(x, y) {|a, b| ... } ⇒ Array
Computes a single longest common subsequence for
x
andy
. -
#listen_geq_2? ⇒ Boolean
Returns whether this environment is using Listen version 2.0.0 or greater.
- #load_listen!
-
#macruby? ⇒ Boolean
Whether or not this is running under MacRuby.
-
#map_hash(hash) {|key, value| ... } ⇒ Hash
Maps the key-value pairs of a hash according to a block.
-
#map_keys(hash) {|key| ... } ⇒ Hash
Maps the keys in a hash according to a block.
-
#map_vals(hash) {|value| ... } ⇒ Hash
Maps the values in a hash according to a block.
-
#max(val1, val2)
Returns the maximum of
val1
andval2
. -
#merge_adjacent_strings(arr) ⇒ Array
Concatenates all strings that are adjacent in an array, while leaving other elements as they are.
-
#min(val1, val2)
Returns the minimum of
val1
andval2
. -
#ord(c) ⇒ Fixnum
Returns the ASCII code of the given character.
-
#ordered_hash(*pairs_or_hash)
Converts a hash or a list of pairs into an order-preserving hash.
-
#pathname(path) ⇒ Pathname
Like
Pathname.new
, but normalizes Windows paths to always use backslash separators. -
#paths(arrs) ⇒ Array<Arrays>
Return an array of all possible paths through the given arrays.
-
#powerset(arr) ⇒ Set<Set>
Computes the powerset of the given array.
-
#rails_env ⇒ String?
Returns the environment of the Rails application, if this is running in a Rails context.
-
#rails_root ⇒ String?
Returns the root of the Rails application, if this is running in a Rails context.
-
#rbx? ⇒ Boolean
Whether or not this is running on Rubinius.
-
#realpath(path) ⇒ Pathanme
Returns
path
with all symlinks resolved. -
#replace_subseq(arr, subseq, replacement) ⇒ Array
Non-destructively replaces all occurrences of a subsequence in an array with another subsequence.
-
#restrict(value, range) ⇒ Numeric
Restricts a number to falling within a given range.
-
#ruby1? ⇒ Boolean
Whether or not this is running under a Ruby version under 2.0.
-
#ruby1_8? ⇒ Boolean
Whether or not this is running under Ruby 1.8 or lower.
-
#ruby1_8_6? ⇒ Boolean
Whether or not this is running under Ruby 1.8.6 or lower.
-
#ruby1_9_2? ⇒ Boolean
Whether or not this is running under Ruby 1.9.2 exactly.
-
#sass_warn(msg)
The same as
Kernel#warn
, but is silenced by #silence_sass_warnings. -
#scope(file) ⇒ String
Returns the path of a file relative to the Sass root directory.
-
#set_eql?(set1, set2) ⇒ Boolean
Tests the hash-equality of two sets in a cross-version manner.
-
#set_hash(set) ⇒ Fixnum
Returns the hash code for a set in a cross-version manner.
-
#silence_sass_warnings { ... }
Silences all Sass warnings within a block.
-
#silence_warnings { ... }
Silence all output to STDERR within a block.
- #slice_by(enum)
-
#sourcemap_name(css) ⇒ String
Builds a sourcemap file name given the generated CSS file name.
-
#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).
-
#subsequence?(seq1, seq2) ⇒ Boolean
Returns whether or not
seq1
is a subsequence ofseq2
. -
#substitute(ary, from, to)
Substitutes a sub-array of one array with another sub-array.
-
#to_hash(arr) ⇒ Hash
Converts an array of
[key, value]
pairs to a hash. -
#undefined_conversion_error_char(e) ⇒ String
Returns a string description of the character that caused an
Encoding::UndefinedConversionError
. -
#version_geq(v1, v2) ⇒ Boolean
Returns whether one version string represents the same or a more recent version than another.
-
#version_gt(v1, v2) ⇒ Boolean
Returns whether one version string represents a more recent version than another.
-
#windows? ⇒ Boolean
Whether or not this is running on Windows.
-
#with_extracted_values(arr) {|str| ... } ⇒ Array
Allows modifications to be performed on the string form of an array containing both strings and non-strings.
Instance Method Details
#absolute_path(path, dir_string = nil) ⇒ String
A cross-platform implementation of File.absolute_path
.
1157 1158 1159 1160 1161 1162 1163 1164 |
# File 'lib/sass/util.rb', line 1157
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.
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.
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 |
# File 'lib/sass/util.rb', line 1200
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(/^(.*?):(-?.*?)(?::.*`(.+)')?$/).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.
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.
805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 |
# File 'lib/sass/util.rb', line 805
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.
695 696 697 |
# File 'lib/sass/util.rb', line 695
def destructure(val)
val || []
end
|
#encode_vlq(value) ⇒ String
Encodes value
as VLQ (http://en.wikipedia.org/wiki/VLQ).
1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 |
# File 'lib/sass/util.rb', line 1118
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.
888 889 890 |
# File 'lib/sass/util.rb', line 888
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.
897 898 899 |
# File 'lib/sass/util.rb', line 897
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.
879 880 881 |
# File 'lib/sass/util.rb', line 879
def enum_with_index(enum)
ruby1_8? ? enum.enum_with_index : enum.each_with_index
end
|
#escape_uri(string) ⇒ String
URI-escape string
.
1148 1149 1150 |
# File 'lib/sass/util.rb', line 1148
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.
909 910 911 912 913 914 915 916 917 |
# File 'lib/sass/util.rb', line 909
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.
1003 1004 1005 1006 1007 1008 1009 1010 1011 |
# File 'lib/sass/util.rb', line 1003
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.
677 678 679 680 681 682 683 684 |
# File 'lib/sass/util.rb', line 677
def file_uri_from_path(path)
path = path.to_s if path.is_a?(Pathname)
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.
932 933 934 935 936 |
# File 'lib/sass/util.rb', line 932
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.
944 945 946 947 948 949 950 951 952 953 954 |
# File 'lib/sass/util.rb', line 944
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.
871 872 873 |
# File 'lib/sass/util.rb', line 871
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.
1019 1020 1021 1022 1023 1024 1025 1026 1027 |
# File 'lib/sass/util.rb', line 1019
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[:encoding]
before being evaluated.
984 985 986 987 988 989 |
# File 'lib/sass/util.rb', line 984
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.
741 742 743 744 |
# File 'lib/sass/util.rb', line 741
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_version ⇒ Array<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.
1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 |
# File 'lib/sass/util.rb', line 1057
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.
1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 |
# File 'lib/sass/util.rb', line 1081
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
.
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!
1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 |
# File 'lib/sass/util.rb', line 1223
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.
749 750 751 752 |
# File 'lib/sass/util.rb', line 749
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.
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.
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.
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.
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.
923 924 925 |
# File 'lib/sass/util.rb', line 923
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.
773 774 775 776 777 778 779 780 781 782 |
# File 'lib/sass/util.rb', line 773
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.
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.
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_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.
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_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.
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) ⇒ Pathanme
Returns path
with all symlinks resolved.
668 669 670 671 |
# File 'lib/sass/util.rb', line 668
def realpath(path)
path = Pathname.new(path) unless path.is_a?(Pathname)
pathname(path.realpath.to_s)
end
|
#replace_subseq(arr, subseq, replacement) ⇒ Array
Non-destructively replaces all occurrences of a subsequence in an array with another subsequence.
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
|
#ruby1? ⇒ Boolean
Whether or not this is running under a Ruby version under 2.0.
704 705 706 707 |
# File 'lib/sass/util.rb', line 704
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.
715 716 717 718 719 720 721 |
# File 'lib/sass/util.rb', line 715
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.
727 728 729 730 |
# File 'lib/sass/util.rb', line 727
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.
735 736 737 738 |
# File 'lib/sass/util.rb', line 735
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.
972 973 974 975 |
# File 'lib/sass/util.rb', line 972
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.
961 962 963 964 |
# File 'lib/sass/util.rb', line 961
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.
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.
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.
1047 1048 1049 |
# File 'lib/sass/util.rb', line 1047
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.
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.
1037 1038 1039 1040 1041 |
# File 'lib/sass/util.rb', line 1037
def with_extracted_values(arr)
str, vals = extract_values(arr)
str = yield str
inject_values(str, vals)
end
|