Module: Sass::Script::Functions
- Included in:
- EvaluationContext
- Defined in:
- lib/sass/script/functions.rb
Overview
Methods in this module are accessible from the SassScript context. For example, you can write
$color: hsl(120deg, 100%, 50%)
and it will call #hsl.
The following functions are provided:
Note: These functions are described in more detail below.
RGB Functions
rgb($red, $green, $blue) : Creates a Color from red, green, and blue values.
rgba($red, $green, $blue, $alpha) : Creates a Color from red, green, blue, and alpha values.
red($color) : Gets the red component of a color.
green($color) : Gets the green component of a color.
blue($color) : Gets the blue component of a color.
mix($color1, $color2, [$weight]) : Mixes two colors together.
HSL Functions
hsl($hue, $saturation, $lightness) : Creates a Color from hue, saturation, and lightness values.
hsla($hue, $saturation, $lightness, $alpha) : Creates a Color from hue, saturation, lightness, and alpha values.
hue($color) : Gets the hue component of a color.
saturation($color) : Gets the saturation component of a color.
lightness($color) : Gets the lightness component of a color.
adjust-hue($color, $degrees) : Changes the hue of a color.
lighten($color, $amount) : Makes a color lighter.
darken($color, $amount) : Makes a color darker.
saturate($color, $amount) : Makes a color more saturated.
desaturate($color, $amount) : Makes a color less saturated.
grayscale($color) : Converts a color to grayscale.
complement($color) : Returns the complement of a color.
invert($color) : Returns the inverse of a color.
Opacity Functions
alpha($color) / opacity($color) : Gets the alpha component (opacity) of a color.
rgba($color, $alpha) : Changes the alpha component for a color.
opacify($color, $amount) / fade-in($color, $amount) : Makes a color more opaque.
transparentize($color, $amount) / fade-out($color, $amount) : Makes a color more transparent.
Other Color Functions
adjust-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) : Increases or decreases one or more components of a color.
scale-color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]) : Fluidly scales one or more properties of a color.
change-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) : Changes one or more properties of a color.
ie-hex-str($color) : Converts a color into the format understood by IE filters.
String Functions
unquote($string) : Removes quotes from a string.
quote($string) : Adds quotes to a string.
str-length($string) : Returns the number of characters in a string.
str-insert($string, $insert, $index)
: Inserts $insert
into $string
at $index
.
str-index($string, $substring)
: Returns the index of the first occurance of $substring
in $string
.
str-slice($string, $start-at, [$end-at])
: Extracts a substring from $string
.
to-upper-case($string) : Converts a string to upper case.
to-lower-case($string) : Converts a string to lower case.
Number Functions
percentage($number) : Converts a unitless number to a percentage.
round($number) : Rounds a number to the nearest whole number.
ceil($number) : Rounds a number up to the next whole number.
floor($number) : Rounds a number down to the previous whole number.
abs($number) : Returns the absolute value of a number.
min($numbers...) : Finds the minimum of several numbers.
max($numbers...) : Finds the maximum of several numbers.
random([$limit]) : Returns a random number.
List Functions #list-functions
All list functions work for maps as well, treating them as lists of pairs.
length($list) : Returns the length of a list.
nth($list, $n) : Returns a specific item in a list.
set-nth($list, $n, $value) : Replaces the nth item in a list.
join($list1, $list2, [$separator]) : Joins together two lists into one.
append($list1, $val, [$separator]) : Appends a single value onto the end of a list.
zip($lists...) : Combines several lists into a single multidimensional list.
index($list, $value) : Returns the position of a value within a list.
list-separator(#list) : Returns the separator of a list.
Map Functions #map-functions
map-get($map, $key) : Returns the value in a map associated with a given key.
map-merge($map1, $map2) : Merges two maps together into a new map.
map-remove($map, $keys...) : Returns a new map with keys removed.
map-keys($map) : Returns a list of all keys in a map.
map-values($map) : Returns a list of all values in a map.
map-has-key($map, $key) : Returns whether a map has a value associated with a given key.
keywords($args) : Returns the keywords passed to a function that takes variable arguments.
Selector Functions
Selector functions are very liberal in the formats they support
for selector arguments. They can take a plain string, a list of
lists as returned by &
or anything in between:
- A plain sring, such as
".foo .bar, .baz .bang"
. - A space-separated list of strings such as
(".foo" ".bar")
. - A comma-separated list of strings such as
(".foo .bar", ".baz .bang")
. - A comma-separated list of space-separated lists of strings such
as
((".foo" ".bar"), (".baz" ".bang"))
.
In general, selector functions allow placeholder selectors
(%foo
) but disallow parent-reference selectors (&
).
selector-nest($selectors...) : Nests selector beneath one another like they would be nested in the stylesheet.
selector-append($selectors...) : Appends selectors to one another without spaces in between.
selector-extend($selector, $extendee, $extender)
: Extends $extendee
with $extender
within $selector
.
selector-replace($selector, $original, $replacement)
: Replaces $original
with $replacement
within $selector
.
selector-unify($selector1, $selector2) : Unifies two selectors to produce a selector that matches elements matched by both.
is-superselector($super, $sub)
: Returns whether $super
matches all the elements $sub
does, and
possibly more.
simple-selectors($selector) : Returns the simple selectors that comprise a compound selector.
selector-parse($selector)
: Parses a selector into the format returned by &
.
Introspection Functions
feature-exists($feature) : Returns whether a feature exists in the current Sass runtime.
variable-exists($name) : Returns whether a variable with the given name exists in the current scope.
global-variable-exists($name) : Returns whether a variable with the given name exists in the global scope.
function-exists($name) : Returns whether a function with the given name exists.
mixin-exists($name) : Returns whether a mixin with the given name exists.
inspect($value) : Returns the string representation of a value as it would be represented in Sass.
type-of($value) : Returns the type of a value.
unit($number) : Returns the unit(s) associated with a number.
unitless($number) : Returns whether a number has units.
comparable($number1, $number2) : Returns whether two numbers can be added, subtracted, or compared.
call($name, $args...) : Dynamically calls a Sass function.
Miscellaneous Functions
if($condition, $if-true, $if-false)
: Returns one of two values, depending on whether or not $condition
is
true.
unique-id() : Returns a unique CSS identifier.
Adding Custom Functions
New Sass functions can be added by adding Ruby methods to this module. For example:
module Sass::Script::Functions
def reverse(string)
assert_type string, :String
Sass::Script::Value::String.new(string.value.reverse)
end
declare :reverse, [:string]
end
Calling Functions.declare tells Sass the argument names for your function. If omitted, the function will still work, but will not be able to accept keyword arguments. Functions.declare can also allow your function to take arbitrary keyword arguments.
There are a few things to keep in mind when modifying this module. First of all, the arguments passed are Value objects. Value objects are also expected to be returned. This means that Ruby values must be unwrapped and wrapped.
Most Value objects support the value accessor for getting their Ruby values. Color objects, though, must be accessed using rgb, red, green, or blue.
Second, making Ruby functions accessible from Sass introduces the temptation to do things like database access within stylesheets. This is generally a bad idea; since Sass files are by default only compiled once, dynamic code is not a great fit.
If you really, really need to compile Sass on each request,
first make sure you have adequate caching set up.
Then you can use Engine to render the code,
using the options
parameter
to pass in data that can be accessed
from your Sass functions.
Within one of the functions in this module, methods of EvaluationContext can be used.
Caveats
When creating new Value objects within functions, be aware that it's not safe to call #to_s (or other methods that use the string representation) on those objects without first setting the #options attribute.
Defined Under Namespace
Classes: EvaluationContext, Signature
Class Method Summary collapse
-
.declare(method_name, args, options = {})
Declare a Sass signature for a Ruby-defined function.
-
.random_number_generator ⇒ Random
Get Sass's internal random number generator.
-
.random_seed=(seed) ⇒ Integer
Sets the random seed used by Sass's internal random number generator.
-
.signature(method_name, arg_arity, kwarg_arity) ⇒ {Symbol => Object}?
Determine the correct signature for the number of arguments passed in for a given function.
Instance Method Summary collapse
-
#abs($number) ⇒ Sass::Script::Value::Number
Returns the absolute value of a number.
-
#adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Increases or decreases one or more properties of a color.
-
#adjust_hue($color, $degrees) ⇒ Sass::Script::Value::Color
Changes the hue of a color.
-
#alpha($color) ⇒ Sass::Script::Value::Number
Returns the alpha component (opacity) of a color.
-
#append($list, $val, $separator: auto) ⇒ Sass::Script::Value::List
Appends a single value onto the end of a list.
-
#blue($color) ⇒ Sass::Script::Value::Number
Gets the blue component of a color.
-
#call($name, $args...)
Dynamically calls a function.
-
#ceil($number) ⇒ Sass::Script::Value::Number
Rounds a number up to the next whole number.
-
#change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Changes one or more properties of a color.
-
#comparable($number1, $number2) ⇒ Sass::Script::Value::Bool
Returns whether two numbers can added, subtracted, or compared.
-
#complement($color) ⇒ Sass::Script::Value::Color
Returns the complement of a color.
-
#counter($args...) ⇒ Sass::Script::Value::String
This function only exists as a workaround for IE7's
content: counter
bug. -
#counters($args...) ⇒ Sass::Script::Value::String
This function only exists as a workaround for IE7's
content: counter
bug. -
#darken($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color darker.
-
#desaturate($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color less saturated.
-
#feature_exists($feature) ⇒ Sass::Script::Value::Bool
Returns whether a feature exists in the current Sass runtime.
-
#floor($number) ⇒ Sass::Script::Value::Number
Rounds a number down to the previous whole number.
-
#function_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a function with the given name exists.
-
#global_variable_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a variable with the given name exists in the global scope (at the top level of the file).
-
#grayscale($color) ⇒ Sass::Script::Value::Color
Converts a color to grayscale.
-
#green($color) ⇒ Sass::Script::Value::Number
Gets the green component of a color.
-
#hsl($hue, $saturation, $lightness) ⇒ Sass::Script::Value::Color
Creates a Color from hue, saturation, and lightness values.
-
#hsla($hue, $saturation, $lightness, $alpha) ⇒ Sass::Script::Value::Color
Creates a Color from hue, saturation, lightness, and alpha values.
-
#hue($color) ⇒ Sass::Script::Value::Number
Returns the hue component of a color.
-
#ie_hex_str($color) ⇒ Sass::Script::Value::String
Converts a color into the format understood by IE filters.
-
#if($condition, $if-true, $if-false) ⇒ Sass::Script::Value::Base
Returns one of two values, depending on whether or not
$condition
is true. -
#index($list, $value) ⇒ Sass::Script::Value::Number, Sass::Script::Value::Null
Returns the position of a value within a list.
-
#inspect($value) ⇒ Sass::Script::Value::String
Return a string containing the value as its Sass representation.
-
#invert($color) ⇒ Sass::Script::Value::Color
Returns the inverse (negative) of a color.
-
#is_superselector($super, $sub) ⇒ Sass::Script::Value::Bool
Returns whether
$super
is a superselector of$sub
. -
#join($list1, $list2, $separator: auto) ⇒ Sass::Script::Value::List
Joins together two lists into one.
-
#keywords($args) ⇒ Sass::Script::Value::Map
Returns the map of named arguments passed to a function or mixin that takes a variable argument list.
-
#length($list) ⇒ Sass::Script::Value::Number
Return the length of a list.
-
#lighten($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color lighter.
-
#lightness($color) ⇒ Sass::Script::Value::Number
Returns the lightness component of a color.
-
#list_separator($list) ⇒ Sass::Script::Value::String
Returns the separator of a list.
-
#map_get($map, $key) ⇒ Sass::Script::Value::Base
Returns the value in a map associated with the given key.
-
#map_has_key($map, $key) ⇒ Sass::Script::Value::Bool
Returns whether a map has a value associated with a given key.
-
#map_keys($map) ⇒ List
Returns a list of all keys in a map.
-
#map_merge($map1, $map2) ⇒ Sass::Script::Value::Map
Merges two maps together into a new map.
-
#map_remove($map, $keys...) ⇒ Sass::Script::Value::Map
Returns a new map with keys removed.
-
#map_values($map) ⇒ List
Returns a list of all values in a map.
-
#max($numbers...) ⇒ Sass::Script::Value::Number
Finds the maximum of several numbers.
-
#min($numbers...) ⇒ Sass::Script::Value::Number
Finds the minimum of several numbers.
-
#mix($color1, $color2, $weight: 50%) ⇒ Sass::Script::Value::Color
Mixes two colors together.
-
#mixin_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a mixin with the given name exists.
-
#nth($list, $n) ⇒ Sass::Script::Value::Base
Gets the nth item in a list.
-
#opacify($color, $amount) ⇒ Sass::Script::Value::Color
(also: #fade_in)
Makes a color more opaque.
-
#opacity($color) ⇒ Sass::Script::Value::Number
Returns the alpha component (opacity) of a color.
-
#percentage($number) ⇒ Sass::Script::Value::Number
Converts a unitless number to a percentage.
-
#quote($string) ⇒ Sass::Script::Value::String
Add quotes to a string if the string isn't quoted, or returns the same string if it is.
- #random(limit = nil)
-
#red($color) ⇒ Sass::Script::Value::Number
Gets the red component of a color.
-
#rgb($red, $green, $blue) ⇒ Sass::Script::Value::Color
Creates a Color object from red, green, and blue values.
-
#rgba(*args)
Creates a Color from red, green, blue, and alpha values.
-
#round($number) ⇒ Sass::Script::Value::Number
Rounds a number to the nearest whole number.
-
#saturate($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color more saturated.
-
#saturation($color) ⇒ Sass::Script::Value::Number
Returns the saturation component of a color.
-
#scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Fluidly scales one or more properties of a color.
-
#selector_append($selectors...) ⇒ Sass::Script::Value::List
Return a new selector with all selectors in
$selectors
appended one another as though they had been nested in the stylesheet as$selector1 { &$selector2 { ... } }
. -
#selector_extend($selector, $extendee, $extender) ⇒ Sass::Script::Value::List
Returns a new version of
$selector
with$extendee
extended with$extender
. -
#selector_nest($selectors...) ⇒ Sass::Script::Value::List
Return a new selector with all selectors in
$selectors
nested beneath one another as though they had been nested in the stylesheet as$selector1 { $selector2 { ... } }
. -
#selector_parse($selector) ⇒ Sass::Script::Value::List
Parses a user-provided selector into a list of lists of strings as returned by
&
. -
#selector_replace($selector, $original, $replacement) ⇒ Sass::Script::Value::List
Replaces all instances of
$original
with$replacement
in$selector
. -
#selector_unify($selector1, $selector2) ⇒ Sass::Script::Value::List, Sass::Script::Value::Null
Unifies two selectors into a single selector that matches only elements matched by both input selectors.
-
#set ⇒ Sass::Script::Value::List
Return a new list, based on the list provided, but with the nth element changed to the value given.
-
#simple_selectors($selector) ⇒ Sass::Script::Value::List
Returns the simple selectors that comprise the compound selector
$selector
. -
#str_index($string, $substring) ⇒ Sass::Script::Value::Number, Sass::Script::Value::Null
Returns the index of the first occurrence of
$substring
in$string
. -
#str_insert($string, $insert, $index) ⇒ Sass::Script::Value::String
Inserts
$insert
into$string
at$index
. -
#str_length($string) ⇒ Sass::Script::Value::Number
Returns the number of characters in a string.
-
#str_slice($string, $start-at, $end-at: -1) ⇒ Sass::Script::Value::String
Extracts a substring from
$string
. -
#to_lower_case($string) ⇒ Sass::Script::Value::String
Convert a string to lower case,.
-
#to_upper_case($string) ⇒ Sass::Script::Value::String
Converts a string to upper case.
-
#transparentize($color, $amount) ⇒ Sass::Script::Value::Color
(also: #fade_out)
Makes a color more transparent.
-
#type_of($value) ⇒ Sass::Script::Value::String
Returns the type of a value.
-
#unique_id ⇒ Sass::Script::Value::String
Returns a unique CSS identifier.
-
#unit($number) ⇒ Sass::Script::Value::String
Returns the unit(s) associated with a number.
-
#unitless($number) ⇒ Sass::Script::Value::Bool
Returns whether a number has units.
-
#unquote($string) ⇒ Sass::Script::Value::String
Removes quotes from a string.
-
#variable_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a variable with the given name exists in the current scope or in the global scope.
-
#zip($lists...) ⇒ Sass::Script::Value::List
Combines several lists into a single multidimensional list.
Class Method Details
.declare(method_name, args, options = {})
Declare a Sass signature for a Ruby-defined function. This includes the names of the arguments, whether the function takes a variable number of arguments, and whether the function takes an arbitrary set of keyword arguments.
It's not necessary to declare a signature for a function. However, without a signature it won't support keyword arguments.
A single function can have multiple signatures declared as long as each one takes a different number of arguments. It's also possible to declare multiple signatures that all take the same number of arguments, but none of them but the first will be used unless the user uses keyword arguments.
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 |
# File 'lib/sass/script/functions.rb', line 399
def self.declare(method_name, args, options = {})
delayed_args = []
args = args.map do |a|
a = a.to_s
if a[0] == ?&
a = a[1..-1]
delayed_args << a
end
a
end
# We don't expose this functionality except to certain builtin methods.
if delayed_args.any? && method_name != :if
raise ArgumentError.new("Delayed arguments are not allowed for method #{method_name}")
end
@signatures[method_name] ||= []
@signatures[method_name] << Signature.new(
args,
delayed_args,
options[:var_args],
options[:var_kwargs],
options[:deprecated] && options[:deprecated].map {|a| a.to_s})
end
|
.random_number_generator ⇒ Random
Get Sass's internal random number generator.
473 474 475 |
# File 'lib/sass/script/functions.rb', line 473
def self.random_number_generator
@random_number_generator ||= Sass::Util::CrossPlatformRandom.new
end
|
.random_seed=(seed) ⇒ Integer
Sets the random seed used by Sass's internal random number generator.
This can be used to ensure consistent random number sequences which allows for consistent results when testing, etc.
466 467 468 |
# File 'lib/sass/script/functions.rb', line 466
def self.random_seed=(seed)
@random_number_generator = Sass::Util::CrossPlatformRandom.new(seed)
end
|
.signature(method_name, arg_arity, kwarg_arity) ⇒ {Symbol => Object}?
Determine the correct signature for the number of arguments passed in for a given function. If no signatures match, the first signature is returned for error messaging.
433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 |
# File 'lib/sass/script/functions.rb', line 433
def self.signature(method_name, arg_arity, kwarg_arity)
return unless @signatures[method_name]
@signatures[method_name].each do |signature|
sig_arity = signature.args.size
return signature if sig_arity == arg_arity + kwarg_arity
next unless sig_arity < arg_arity + kwarg_arity
# We have enough args.
# Now we need to figure out which args are varargs
# and if the signature allows them.
t_arg_arity, t_kwarg_arity = arg_arity, kwarg_arity
if sig_arity > t_arg_arity
# we transfer some kwargs arity to args arity
# if it does not have enough args -- assuming the names will work out.
t_kwarg_arity -= (sig_arity - t_arg_arity)
t_arg_arity = sig_arity
end
if (t_arg_arity == sig_arity || t_arg_arity > sig_arity && signature.var_args) &&
(t_kwarg_arity == 0 || t_kwarg_arity > 0 && signature.var_kwargs)
return signature
end
end
@signatures[method_name].first
end
|
Instance Method Details
#abs($number) ⇒ Sass::Script::Value::Number
Returns the absolute value of a number.
1745 1746 1747 |
# File 'lib/sass/script/functions.rb', line 1745
def abs(number)
numeric_transformation(number) {|n| n.abs}
end
|
#adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Increases or decreases one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and are added to or subtracted from the color's current value for that property.
All properties are optional. You can't specify both RGB properties
($red
, $green
, $blue
) and HSL properties ($hue
, $saturation
,
$value
) at the same time.
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 |
# File 'lib/sass/script/functions.rb', line 1102
def adjust_color(color, kwargs)
assert_type color, :Color, :color
with = Sass::Util.map_hash(
"red" => [-255..255, ""],
"green" => [-255..255, ""],
"blue" => [-255..255, ""],
"hue" => nil,
"saturation" => [-100..100, "%"],
"lightness" => [-100..100, "%"],
"alpha" => [-1..1, ""]
) do |name, (range, units)|
val = kwargs.delete(name)
next unless val
assert_type val, :Number, name
Sass::Util.check_range("$#{name}: Amount", range, val, units) if range
adjusted = color.send(name) + val.value
adjusted = [0, Sass::Util.restrict(adjusted, range)].max if range
[name.to_sym, adjusted]
end
unless kwargs.empty?
name, val = kwargs.to_a.first
raise ArgumentError.new("Unknown argument $#{name} (#{val})")
end
color.with(with)
end
|
#adjust_hue($color, $degrees) ⇒ Sass::Script::Value::Color
Changes the hue of a color. Takes a color and a number of degrees (usually
between -360deg
and 360deg
), and returns a color with the hue rotated
along the color wheel by that amount.
1040 1041 1042 1043 1044 |
# File 'lib/sass/script/functions.rb', line 1040
def adjust_hue(color, degrees)
assert_type color, :Color, :color
assert_type degrees, :Number, :degrees
color.with(:hue => color.hue + degrees.value)
end
|
#alpha($color) ⇒ Sass::Script::Value::Number
Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.
This function also supports the proprietary Microsoft alpha(opacity=20)
syntax as a special case.
870 871 872 873 874 875 876 877 878 879 880 881 882 883 |
# File 'lib/sass/script/functions.rb', line 870
def alpha(*args)
if args.all? do |a|
a.is_a?(Sass::Script::Value::String) && a.type == :identifier &&
a.value =~ /^[a-zA-Z]+\s*=/
end
# Support the proprietary MS alpha() function
return identifier("alpha(#{args.map {|a| a.to_s}.join(", ")})")
end
raise ArgumentError.new("wrong number of arguments (#{args.size} for 1)") if args.size != 1
assert_type args.first, :Color, :color
number(args.first.alpha)
end
|
#append($list, $val, $separator: auto) ⇒ Sass::Script::Value::List
Appends a single value onto the end of a list.
Unless the $separator
argument is passed, if the list had only one item,
the resulting list will be space-separated.
1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 |
# File 'lib/sass/script/functions.rb', line 1913
def append(list, val, separator = identifier("auto"))
assert_type separator, :String, :separator
unless %w[auto space comma].include?(separator.value)
raise ArgumentError.new("Separator name must be space, comma, or auto")
end
sep = if separator.value == 'auto'
list.separator || :space
else
separator.value.to_sym
end
list(list.to_a + [val], sep)
end
|
#blue($color) ⇒ Sass::Script::Value::Number
Gets the blue component of a color. Calculated from HSL where necessary via this algorithm.
800 801 802 803 |
# File 'lib/sass/script/functions.rb', line 800
def blue(color)
assert_type color, :Color, :color
number(color.blue)
end
|
#call($name, $args...)
Dynamically calls a function. This can call user-defined functions, built-in functions, or plain CSS functions. It will pass along all arguments, including keyword arguments, to the called function.
2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 |
# File 'lib/sass/script/functions.rb', line 2175
def call(name, *args)
assert_type name, :String, :name
kwargs = args.last.is_a?(Hash) ? args.pop : {}
funcall = Sass::Script::Tree::Funcall.new(
name.value,
args.map {|a| Sass::Script::Tree::Literal.new(a)},
Sass::Util.map_vals(kwargs) {|v| Sass::Script::Tree::Literal.new(v)},
nil,
nil)
funcall.options = options
perform(funcall)
end
|
#ceil($number) ⇒ Sass::Script::Value::Number
Rounds a number up to the next whole number.
1717 1718 1719 |
# File 'lib/sass/script/functions.rb', line 1717
def ceil(number)
numeric_transformation(number) {|n| n.ceil}
end
|
#change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Changes one or more properties of a color. This can change the red, green, blue, hue, saturation, value, and alpha properties. The properties are specified as keyword arguments, and replace the color's current value for that property.
All properties are optional. You can't specify both RGB properties
($red
, $green
, $blue
) and HSL properties ($hue
, $saturation
,
$value
) at the same time.
1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 |
# File 'lib/sass/script/functions.rb', line 1244
def change_color(color, kwargs)
assert_type color, :Color, :color
with = Sass::Util.map_hash(
'red' => ['Red value', 0..255],
'green' => ['Green value', 0..255],
'blue' => ['Blue value', 0..255],
'hue' => [],
'saturation' => ['Saturation', 0..100, '%'],
'lightness' => ['Lightness', 0..100, '%'],
'alpha' => ['Alpha channel', 0..1]
) do |name, (desc, range, unit)|
val = kwargs.delete(name)
next unless val
assert_type val, :Number, name
if range
val = Sass::Util.check_range(desc, range, val, unit)
else
val = val.value
end
[name.to_sym, val]
end
unless kwargs.empty?
name, val = kwargs.to_a.first
raise ArgumentError.new("Unknown argument $#{name} (#{val})")
end
color.with(with)
end
|
#comparable($number1, $number2) ⇒ Sass::Script::Value::Bool
Returns whether two numbers can added, subtracted, or compared.
1670 1671 1672 1673 1674 |
# File 'lib/sass/script/functions.rb', line 1670
def comparable(number1, number2)
assert_type number1, :Number, :number1
assert_type number2, :Number, :number2
bool(number1.comparable_to?(number2))
end
|
#complement($color) ⇒ Sass::Script::Value::Color
Returns the complement of a color. This is identical to adjust-hue(color,
180deg)
.
1363 1364 1365 |
# File 'lib/sass/script/functions.rb', line 1363
def complement(color)
adjust_hue color, number(180)
end
|
#counter($args...) ⇒ Sass::Script::Value::String
This function only exists as a workaround for IE7's content:
counter
bug.
It works identically to any other plain-CSS function, except it
avoids adding spaces between the argument commas.
2198 2199 2200 |
# File 'lib/sass/script/functions.rb', line 2198
def counter(*args)
identifier("counter(#{args.map {|a| a.to_s(options)}.join(',')})")
end
|
#counters($args...) ⇒ Sass::Script::Value::String
This function only exists as a workaround for IE7's content:
counter
bug.
It works identically to any other plain-CSS function, except it
avoids adding spaces between the argument commas.
2212 2213 2214 |
# File 'lib/sass/script/functions.rb', line 2212
def counters(*args)
identifier("counters(#{args.map {|a| a.to_s(options)}.join(',')})")
end
|
#darken($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color darker. Takes a color and a number between 0% and 100%, and returns a color with the lightness decreased by that amount.
979 980 981 |
# File 'lib/sass/script/functions.rb', line 979
def darken(color, amount)
_adjust(color, amount, :lightness, 0..100, :-, "%")
end
|
#desaturate($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color less saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation decreased by that value.
1021 1022 1023 |
# File 'lib/sass/script/functions.rb', line 1021
def desaturate(color, amount)
_adjust(color, amount, :saturation, 0..100, :-, "%")
end
|
#feature_exists($feature) ⇒ Sass::Script::Value::Bool
Returns whether a feature exists in the current Sass runtime.
The following features are supported:
global-variable-shadowing
indicates that a local variable will shadow a global variable unless!global
is used.extend-selector-pseudoclass
indicates that@extend
will reach into selector pseudoclasses like:not
.units-level-3
indicates full support for unit arithmetic using units defined in the Values and Units Level 3 spec.at-error
indicates that the Sass@error
directive is supported.
1618 1619 1620 1621 |
# File 'lib/sass/script/functions.rb', line 1618
def feature_exists(feature)
assert_type feature, :String, :feature
bool(Sass.has_feature?(feature.value))
end
|
#floor($number) ⇒ Sass::Script::Value::Number
Rounds a number down to the previous whole number.
1731 1732 1733 |
# File 'lib/sass/script/functions.rb', line 1731
def floor(number)
numeric_transformation(number) {|n| n.floor}
end
|
#function_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a function with the given name exists.
2272 2273 2274 2275 2276 2277 |
# File 'lib/sass/script/functions.rb', line 2272
def function_exists(name)
assert_type name, :String, :name
exists = Sass::Script::Functions.callable?(name.value.tr("-", "_"))
exists ||= environment.function(name.value)
bool(exists)
end
|
#global_variable_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a variable with the given name exists in the global scope (at the top level of the file).
2254 2255 2256 2257 |
# File 'lib/sass/script/functions.rb', line 2254
def global_variable_exists(name)
assert_type name, :String, :name
bool(environment.global_env.var(name.value))
end
|
#grayscale($color) ⇒ Sass::Script::Value::Color
Converts a color to grayscale. This is identical to desaturate(color,
100%)
.
1347 1348 1349 1350 1351 1352 |
# File 'lib/sass/script/functions.rb', line 1347
def grayscale(color)
if color.is_a?(Sass::Script::Value::Number)
return identifier("grayscale(#{color})")
end
desaturate color, number(100)
end
|
#green($color) ⇒ Sass::Script::Value::Number
Gets the green component of a color. Calculated from HSL where necessary via this algorithm.
784 785 786 787 |
# File 'lib/sass/script/functions.rb', line 784
def green(color)
assert_type color, :Color, :color
number(color.green)
end
|
#hsl($hue, $saturation, $lightness) ⇒ Sass::Script::Value::Color
715 716 717 |
# File 'lib/sass/script/functions.rb', line 715
def hsl(hue, saturation, lightness)
hsla(hue, saturation, lightness, number(1))
end
|
#hsla($hue, $saturation, $lightness, $alpha) ⇒ Sass::Script::Value::Color
739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 |
# File 'lib/sass/script/functions.rb', line 739
def hsla(hue, saturation, lightness, alpha)
assert_type hue, :Number, :hue
assert_type saturation, :Number, :saturation
assert_type lightness, :Number, :lightness
assert_type alpha, :Number, :alpha
check_alpha_unit alpha, 'hsla'
h = hue.value
s = saturation.value
l = lightness.value
# Don't store the string representation for function-created colors, both
# because it's not very useful and because some functions aren't supported
# on older browsers.
Sass::Script::Value::Color.new(
:hue => h, :saturation => s, :lightness => l, :alpha => alpha.value)
end
|
#hue($color) ⇒ Sass::Script::Value::Number
Returns the hue component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
818 819 820 821 |
# File 'lib/sass/script/functions.rb', line 818
def hue(color)
assert_type color, :Color, :color
number(color.hue, "deg")
end
|
#ie_hex_str($color) ⇒ Sass::Script::Value::String
Converts a color into the format understood by IE filters.
1058 1059 1060 1061 1062 |
# File 'lib/sass/script/functions.rb', line 1058
def ie_hex_str(color)
assert_type color, :Color, :color
alpha = (color.alpha * 255).round.to_s(16).rjust(2, '0')
identifier("##{alpha}#{color.send(:hex_str)[1..-1]}".upcase)
end
|
#if($condition, $if-true, $if-false) ⇒ Sass::Script::Value::Base
Returns one of two values, depending on whether or not $condition
is
true. Just like in @if
, all values other than false
and null
are
considered to be true.
2136 2137 2138 2139 2140 2141 2142 |
# File 'lib/sass/script/functions.rb', line 2136
def if(condition, if_true, if_false)
if condition.to_bool
perform(if_true)
else
perform(if_false)
end
end
|
#index($list, $value) ⇒ Sass::Script::Value::Number, Sass::Script::Value::Null
Returns the position of a value within a list. If the value isn't found,
returns null
instead.
Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.
This can return the position of a pair in a map as well.
1974 1975 1976 1977 |
# File 'lib/sass/script/functions.rb', line 1974
def index(list, value)
index = list.to_a.index {|e| e.eq(value).to_bool}
index ? number(index + 1) : null
end
|
#inspect($value) ⇒ Sass::Script::Value::String
Return a string containing the value as its Sass representation.
2304 2305 2306 |
# File 'lib/sass/script/functions.rb', line 2304
def inspect(value)
unquoted_string(value.to_sass)
end
|
#invert($color) ⇒ Sass::Script::Value::Color
Returns the inverse (negative) of a color. The red, green, and blue values are inverted, while the opacity is left alone.
1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 |
# File 'lib/sass/script/functions.rb', line 1375
def invert(color)
if color.is_a?(Sass::Script::Value::Number)
return identifier("invert(#{color})")
end
assert_type color, :Color, :color
color.with(
:red => (255 - color.red),
:green => (255 - color.green),
:blue => (255 - color.blue))
end
|
#is_superselector($super, $sub) ⇒ Sass::Script::Value::Bool
Returns whether $super
is a superselector of $sub
. This means that
$super
matches all the elements that $sub
matches, as well as possibly
additional elements. In general, simpler selectors tend to be
superselectors of more complex oned.
2601 2602 2603 2604 2605 |
# File 'lib/sass/script/functions.rb', line 2601
def is_superselector(sup, sub)
sup = parse_selector(sup, :super)
sub = parse_selector(sub, :sub)
bool(sup.superselector?(sub))
end
|
#join($list1, $list2, $separator: auto) ⇒ Sass::Script::Value::List
Joins together two lists into one.
Unless $separator
is passed, if one list is comma-separated and one is
space-separated, the first parameter's separator is used for the resulting
list. If both lists have fewer than two items, spaces are used for the
resulting list.
1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 |
# File 'lib/sass/script/functions.rb', line 1880
def join(list1, list2, separator = identifier("auto"))
assert_type separator, :String, :separator
unless %w[auto space comma].include?(separator.value)
raise ArgumentError.new("Separator name must be space, comma, or auto")
end
sep = if separator.value == 'auto'
list1.separator || list2.separator || :space
else
separator.value.to_sym
end
list(list1.to_a + list2.to_a, sep)
end
|
#keywords($args) ⇒ Sass::Script::Value::Map
Returns the map of named arguments passed to a function or mixin that
takes a variable argument list. The argument names are strings, and they
do not contain the leading $
.
2117 2118 2119 2120 |
# File 'lib/sass/script/functions.rb', line 2117
def keywords(args)
assert_type args, :ArgList, :args
map(Sass::Util.map_keys(args.keywords.as_stored) {|k| Sass::Script::Value::String.new(k)})
end
|
#length($list) ⇒ Sass::Script::Value::Number
Return the length of a list.
This can return the number of pairs in a map as well.
1795 1796 1797 |
# File 'lib/sass/script/functions.rb', line 1795
def length(list)
number(list.to_a.size)
end
|
#lighten($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color lighter. Takes a color and a number between 0%
and 100%
,
and returns a color with the lightness increased by that amount.
960 961 962 |
# File 'lib/sass/script/functions.rb', line 960
def lighten(color, amount)
_adjust(color, amount, :lightness, 0..100, :+, "%")
end
|
#lightness($color) ⇒ Sass::Script::Value::Number
Returns the lightness component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
854 855 856 857 |
# File 'lib/sass/script/functions.rb', line 854
def lightness(color)
assert_type color, :Color, :color
number(color.lightness, "%")
end
|
#list_separator($list) ⇒ Sass::Script::Value::String
Returns the separator of a list. If the list doesn't have a separator due
to having fewer than two elements, returns space
.
1990 1991 1992 |
# File 'lib/sass/script/functions.rb', line 1990
def list_separator(list)
identifier((list.separator || :space).to_s)
end
|
#map_get($map, $key) ⇒ Sass::Script::Value::Base
Returns the value in a map associated with the given key. If the map
doesn't have such a key, returns null
.
2008 2009 2010 2011 |
# File 'lib/sass/script/functions.rb', line 2008
def map_get(map, key)
assert_type map, :Map, :map
map.to_h[key] || null
end
|
#map_has_key($map, $key) ⇒ Sass::Script::Value::Bool
Returns whether a map has a value associated with a given key.
2097 2098 2099 2100 |
# File 'lib/sass/script/functions.rb', line 2097
def map_has_key(map, key)
assert_type map, :Map, :map
bool(map.to_h.has_key?(key))
end
|
#map_keys($map) ⇒ List
Returns a list of all keys in a map.
2065 2066 2067 2068 |
# File 'lib/sass/script/functions.rb', line 2065
def map_keys(map)
assert_type map, :Map, :map
list(map.to_h.keys, :comma)
end
|
#map_merge($map1, $map2) ⇒ Sass::Script::Value::Map
Merges two maps together into a new map. Keys in $map2
will take
precedence over keys in $map1
.
This is the best way to add new values to a map.
All keys in the returned map that also appear in $map1
will have the
same order as in $map1
. New keys from $map2
will be placed at the end
of the map.
2031 2032 2033 2034 2035 |
# File 'lib/sass/script/functions.rb', line 2031
def map_merge(map1, map2)
assert_type map1, :Map, :map1
assert_type map2, :Map, :map2
map(map1.to_h.merge(map2.to_h))
end
|
#map_remove($map, $keys...) ⇒ Sass::Script::Value::Map
Returns a new map with keys removed.
2049 2050 2051 2052 2053 2054 |
# File 'lib/sass/script/functions.rb', line 2049
def map_remove(map, *keys)
assert_type map, :Map, :map
hash = map.to_h.dup
hash.delete_if {|key, _| keys.include?(key)}
map(hash)
end
|
#map_values($map) ⇒ List
Returns a list of all values in a map. This list may include duplicate values, if multiple keys have the same value.
2081 2082 2083 2084 |
# File 'lib/sass/script/functions.rb', line 2081
def map_values(map)
assert_type map, :Map, :map
list(map.to_h.values, :comma)
end
|
#max($numbers...) ⇒ Sass::Script::Value::Number
Finds the maximum of several numbers. This function takes any number of arguments.
1778 1779 1780 1781 |
# File 'lib/sass/script/functions.rb', line 1778
def max(*values)
values.each {|v| assert_type v, :Number}
values.inject {|max, val| max.gt(val).to_bool ? max : val}
end
|
#min($numbers...) ⇒ Sass::Script::Value::Number
Finds the minimum of several numbers. This function takes any number of arguments.
1761 1762 1763 1764 |
# File 'lib/sass/script/functions.rb', line 1761
def min(*numbers)
numbers.each {|n| assert_type n, :Number}
numbers.inject {|min, num| min.lt(num).to_bool ? min : num}
end
|
#mix($color1, $color2, $weight: 50%) ⇒ Sass::Script::Value::Color
Mixes two colors together. Specifically, takes the average of each of the RGB components, optionally weighted by the given percentage. The opacity of the colors is also considered when weighting the components.
The weight specifies the amount of the first color that should be included
in the returned color. The default, 50%
, means that half the first color
and half the second color should be used. 25%
means that a quarter of
the first color and three quarters of the second color should be used.
1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 |
# File 'lib/sass/script/functions.rb', line 1299
def mix(color1, color2, weight = number(50))
assert_type color1, :Color, :color1
assert_type color2, :Color, :color2
assert_type weight, :Number, :weight
Sass::Util.check_range("Weight", 0..100, weight, '%')
# This algorithm factors in both the user-provided weight (w) and the
# difference between the alpha values of the two colors (a) to decide how
# to perform the weighted average of the two RGB values.
#
# It works by first normalizing both parameters to be within [-1, 1],
# where 1 indicates "only use color1", -1 indicates "only use color2", and
# all values in between indicated a proportionately weighted average.
#
# Once we have the normalized variables w and a, we apply the formula
# (w + a)/(1 + w*a) to get the combined weight (in [-1, 1]) of color1.
# This formula has two especially nice properties:
#
# * When either w or a are -1 or 1, the combined weight is also that number
# (cases where w * a == -1 are undefined, and handled as a special case).
#
# * When a is 0, the combined weight is w, and vice versa.
#
# Finally, the weight of color1 is renormalized to be within [0, 1]
# and the weight of color2 is given by 1 minus the weight of color1.
p = (weight.value / 100.0).to_f
w = p * 2 - 1
a = color1.alpha - color2.alpha
w1 = ((w * a == -1 ? w : (w + a) / (1 + w * a)) + 1) / 2.0
w2 = 1 - w1
rgba = color1.rgb.zip(color2.rgb).map {|v1, v2| v1 * w1 + v2 * w2}
rgba << color1.alpha * p + color2.alpha * (1 - p)
rgb_color(*rgba)
end
|
#mixin_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a mixin with the given name exists.
2292 2293 2294 2295 |
# File 'lib/sass/script/functions.rb', line 2292
def mixin_exists(name)
assert_type name, :String, :name
bool(environment.mixin(name.value))
end
|
#nth($list, $n) ⇒ Sass::Script::Value::Base
Gets the nth item in a list.
Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.
This can return the nth pair in a map as well.
Negative index values address elements in reverse order, starting with the last element in the list.
1851 1852 1853 1854 1855 1856 1857 |
# File 'lib/sass/script/functions.rb', line 1851
def nth(list, n)
assert_type n, :Number, :n
Sass::Script::Value::List.assert_valid_index(list, n)
index = n.to_i > 0 ? n.to_i - 1 : n.to_i
list.to_a[index]
end
|
#opacify($color, $amount) ⇒ Sass::Script::Value::Color Also known as: fade_in
Makes a color more opaque. Takes a color and a number between 0 and 1, and returns a color with the opacity increased by that amount.
916 917 918 |
# File 'lib/sass/script/functions.rb', line 916
def opacify(color, amount)
_adjust(color, amount, :alpha, 0..1, :+)
end
|
#opacity($color) ⇒ Sass::Script::Value::Number
Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.
893 894 895 896 897 898 899 |
# File 'lib/sass/script/functions.rb', line 893
def opacity(color)
if color.is_a?(Sass::Script::Value::Number)
return identifier("opacity(#{color})")
end
assert_type color, :Color, :color
number(color.alpha)
end
|
#percentage($number) ⇒ Sass::Script::Value::Number
Converts a unitless number to a percentage.
1686 1687 1688 1689 1690 1691 |
# File 'lib/sass/script/functions.rb', line 1686
def percentage(number)
unless number.is_a?(Sass::Script::Value::Number) && number.unitless?
raise ArgumentError.new("$number: #{number.inspect} is not a unitless number")
end
number(number.value * 100, '%')
end
|
#quote($string) ⇒ Sass::Script::Value::String
Add quotes to a string if the string isn't quoted, or returns the same string if it is.
1419 1420 1421 1422 1423 1424 1425 1426 |
# File 'lib/sass/script/functions.rb', line 1419
def quote(string)
assert_type string, :String, :string
if string.type != :string
quoted_string(string.value)
else
string
end
end
|
#random ⇒ Sass::Script::Value::Number #random($limit) ⇒ Sass::Script::Value::Number
2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 |
# File 'lib/sass/script/functions.rb', line 2318
def random(limit = nil)
generator = Sass::Script::Functions.random_number_generator
if limit
assert_integer limit, "limit"
if limit.value < 1
raise ArgumentError.new("$limit #{limit} must be greater than or equal to 1")
end
number(1 + generator.rand(limit.value))
else
number(generator.rand)
end
end
|
#red($color) ⇒ Sass::Script::Value::Number
Gets the red component of a color. Calculated from HSL where necessary via this algorithm.
768 769 770 771 |
# File 'lib/sass/script/functions.rb', line 768
def red(color)
assert_type color, :Color, :color
number(color.red)
end
|
#rgb($red, $green, $blue) ⇒ Sass::Script::Value::Color
Creates a Color object from red, green, and blue values.
626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 |
# File 'lib/sass/script/functions.rb', line 626
def rgb(red, green, blue)
assert_type red, :Number, :red
assert_type green, :Number, :green
assert_type blue, :Number, :blue
color_attrs = [[red, :red], [green, :green], [blue, :blue]].map do |(c, name)|
if c.is_unit?("%")
c.value * 255 / 100.0
elsif c.unitless?
c.value
else
raise ArgumentError.new("Expected #{c} to be unitless or have a unit of % but got #{c}")
end
end
# Don't store the string representation for function-created colors, both
# because it's not very useful and because some functions aren't supported
# on older browsers.
Sass::Script::Value::Color.new(color_attrs)
end
|
#rgba($red, $green, $blue, $alpha) ⇒ Sass::Script::Value::Color #rgba($color, $alpha) ⇒ Sass::Script::Value::Color
Creates a Color from red, green, blue, and alpha values.
679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 |
# File 'lib/sass/script/functions.rb', line 679
def rgba(*args)
case args.size
when 2
color, alpha = args
assert_type color, :Color, :color
assert_type alpha, :Number, :alpha
check_alpha_unit alpha, 'rgba'
color.with(:alpha => alpha.value)
when 4
red, green, blue, alpha = args
rgba(rgb(red, green, blue), alpha)
else
raise ArgumentError.new("wrong number of arguments (#{args.size} for 4)")
end
end
|
#round($number) ⇒ Sass::Script::Value::Number
Rounds a number to the nearest whole number.
1703 1704 1705 |
# File 'lib/sass/script/functions.rb', line 1703
def round(number)
numeric_transformation(number) {|n| n.round}
end
|
#saturate($color, $amount) ⇒ Sass::Script::Value::Color
Makes a color more saturated. Takes a color and a number between 0% and 100%, and returns a color with the saturation increased by that amount.
998 999 1000 1001 1002 1003 |
# File 'lib/sass/script/functions.rb', line 998
def saturate(color, amount = nil)
# Support the filter effects definition of saturate.
# https://dvcs.w3.org/hg/FXTF/raw-file/tip/filters/index.html
return identifier("saturate(#{color})") if amount.nil?
_adjust(color, amount, :saturation, 0..100, :+, "%")
end
|
#saturation($color) ⇒ Sass::Script::Value::Number
Returns the saturation component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
836 837 838 839 |
# File 'lib/sass/script/functions.rb', line 836
def saturation(color)
assert_type color, :Color, :color
number(color.saturation, "%")
end
|
#scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]) ⇒ Sass::Script::Value::Color
Fluidly scales one or more properties of a color. Unlike
adjust-color, which changes a color's properties by fixed
amounts, scale-color fluidly changes them based on how
high or low they already are. That means that lightening an already-light
color with scale-color won't change the lightness much,
but lightening a dark color by the same amount will change it more
dramatically. This has the benefit of making scale-color($color, ...)
have a similar effect regardless of what $color
is.
For example, the lightness of a color can be anywhere between 0%
and
100%
. If scale-color($color, $lightness: 40%)
is called, the resulting
color's lightness will be 40% of the way between its original lightness
and 100. If scale-color($color, $lightness: -40%)
is called instead, the
lightness will be 40% of the way between the original and 0.
This can change the red, green, blue, saturation, value, and alpha
properties. The properties are specified as keyword arguments. All
arguments should be percentages between 0%
and 100%
.
All properties are optional. You can't specify both RGB properties
($red
, $green
, $blue
) and HSL properties ($saturation
, $value
)
at the same time.
1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 |
# File 'lib/sass/script/functions.rb', line 1175
def scale_color(color, kwargs)
assert_type color, :Color, :color
with = Sass::Util.map_hash(
"red" => 255,
"green" => 255,
"blue" => 255,
"saturation" => 100,
"lightness" => 100,
"alpha" => 1
) do |name, max|
val = kwargs.delete(name)
next unless val
assert_type val, :Number, name
assert_unit val, '%', name
Sass::Util.check_range("$#{name}: Amount", -100..100, val, '%')
current = color.send(name)
scale = val.value / 100.0
diff = scale > 0 ? max - current : current
[name.to_sym, current + diff * scale]
end
unless kwargs.empty?
name, val = kwargs.to_a.first
raise ArgumentError.new("Unknown argument $#{name} (#{val})")
end
color.with(with)
end
|
#selector_append($selectors...) ⇒ Sass::Script::Value::List
Return a new selector with all selectors in $selectors
appended one
another as though they had been nested in the stylesheet as $selector1 {
&$selector2 { ... } }
.
2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 |
# File 'lib/sass/script/functions.rb', line 2402
def selector_append(*selectors)
if selectors.empty?
raise ArgumentError.new("$selectors: At least one selector must be passed")
end
selectors.map {|sel| parse_selector(sel, :selectors)}.inject do |parent, child|
child.members.each do |seq|
sseq = seq.members.first
unless sseq.is_a?(Sass::Selector::SimpleSequence)
raise ArgumentError.new("Can't append \"#{seq}\" to \"#{parent}\"")
end
base = sseq.base
case base
when Sass::Selector::Universal
raise ArgumentError.new("Can't append \"#{seq}\" to \"#{parent}\"")
when Sass::Selector::Element
unless base.namespace.nil?
raise ArgumentError.new("Can't append \"#{seq}\" to \"#{parent}\"")
end
sseq.members[0] = Sass::Selector::Parent.new(base.name)
else
sseq.members.unshift Sass::Selector::Parent.new
end
end
child.resolve_parent_refs(parent)
end.to_sass_script
end
|
#selector_extend($selector, $extendee, $extender) ⇒ Sass::Script::Value::List
Returns a new version of $selector
with $extendee
extended
with $extender
. This works just like the result of
$selector { ... }
$extender { @extend $extendee }
2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 |
# File 'lib/sass/script/functions.rb', line 2459
def selector_extend(selector, extendee, extender)
selector = parse_selector(selector, :selector)
extendee = parse_selector(extendee, :extendee)
extender = parse_selector(extender, :extender)
extends = Sass::Util::SubsetMap.new
begin
extender.populate_extends(extends, extendee)
selector.do_extend(extends).to_sass_script
rescue Sass::SyntaxError => e
raise ArgumentError.new(e.to_s)
end
end
|
#selector_nest($selectors...) ⇒ Sass::Script::Value::List
Return a new selector with all selectors in $selectors
nested beneath
one another as though they had been nested in the stylesheet as
$selector1 { $selector2 { ... } }
.
Unlike most selector functions, selector-nest
allows the
parent selector &
to be used in any selector but the first.
2372 2373 2374 2375 2376 2377 2378 2379 2380 |
# File 'lib/sass/script/functions.rb', line 2372
def selector_nest(*selectors)
if selectors.empty?
raise ArgumentError.new("$selectors: At least one selector must be passed")
end
parsed = [parse_selector(selectors.first, :selectors)]
parsed += selectors[1..-1].map {|sel| parse_selector(sel, :selectors, !!:parse_parent_ref)}
parsed.inject {|result, child| child.resolve_parent_refs(result)}.to_sass_script
end
|
#selector_parse($selector) ⇒ Sass::Script::Value::List
Parses a user-provided selector into a list of lists of strings
as returned by &
.
2346 2347 2348 |
# File 'lib/sass/script/functions.rb', line 2346
def selector_parse(selector)
parse_selector(selector, :selector).to_sass_script
end
|
#selector_replace($selector, $original, $replacement) ⇒ Sass::Script::Value::List
Replaces all instances of $original
with $replacement
in $selector
This works by using @extend
and throwing away the original
selector. This means that it can be used to do very advanced
replacements; see the examples below.
2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 |
# File 'lib/sass/script/functions.rb', line 2502
def selector_replace(selector, original, replacement)
selector = parse_selector(selector, :selector)
original = parse_selector(original, :original)
replacement = parse_selector(replacement, :replacement)
extends = Sass::Util::SubsetMap.new
begin
replacement.populate_extends(extends, original)
selector.do_extend(extends, [], !!:replace).to_sass_script
rescue Sass::SyntaxError => e
raise ArgumentError.new(e.to_s)
end
end
|
#selector_unify($selector1, $selector2) ⇒ Sass::Script::Value::List, Sass::Script::Value::Null
Unifies two selectors into a single selector that matches only
elements matched by both input selectors. Returns null
if
there is no such selector.
Like the selector unification done for @extend
, this doesn't
guarantee that the output selector will match all elements
matched by both input selectors. For example, if .a .b
is
unified with .x .y
, .a .x .b.y, .x .a .b.y
will be returned,
but .a.x .b.y
will not. This avoids exponential output size
while matching all elements that are likely to exist in
practice.
2548 2549 2550 2551 2552 2553 |
# File 'lib/sass/script/functions.rb', line 2548
def selector_unify(selector1, selector2)
selector1 = parse_selector(selector1, :selector1)
selector2 = parse_selector(selector2, :selector2)
return null unless (unified = selector1.unify(selector2))
unified.to_sass_script
end
|
#set ⇒ Sass::Script::Value::List
Return a new list, based on the list provided, but with the nth element changed to the value given.
Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.
Negative index values address elements in reverse order, starting with the last element in the list.
1820 1821 1822 1823 1824 1825 1826 1827 |
# File 'lib/sass/script/functions.rb', line 1820
def set_nth(list, n, value)
assert_type n, :Number, :n
Sass::Script::Value::List.assert_valid_index(list, n)
index = n.to_i > 0 ? n.to_i - 1 : n.to_i
new_list = list.to_a.dup
new_list[index] = value
Sass::Script::Value::List.new(new_list, list.separator)
end
|
#simple_selectors($selector) ⇒ Sass::Script::Value::List
Returns the simple
selectors that
comprise the compound selector $selector
.
Note that $selector
must be a compound
selector. That
means it cannot contain commas or spaces. It also means that
unlike other selector functions, this takes only strings, not
lists.
2575 2576 2577 2578 |
# File 'lib/sass/script/functions.rb', line 2575
def simple_selectors(selector)
selector = parse_compound_selector(selector, :selector)
list(selector.members.map {|simple| unquoted_string(simple.to_s)}, :comma)
end
|
#str_index($string, $substring) ⇒ Sass::Script::Value::Number, Sass::Script::Value::Null
Returns the index of the first occurrence of $substring
in $string
. If
there is no such occurrence, returns null
.
Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.
1495 1496 1497 1498 1499 1500 |
# File 'lib/sass/script/functions.rb', line 1495
def str_index(string, substring)
assert_type string, :String, :string
assert_type substring, :String, :substring
index = string.value.index(substring.value)
index ? number(index + 1) : null
end
|
#str_insert($string, $insert, $index) ⇒ Sass::Script::Value::String
Inserts $insert
into $string
at $index
.
Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.
1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 |
# File 'lib/sass/script/functions.rb', line 1463
def str_insert(original, insert, index)
assert_type original, :String, :string
assert_type insert, :String, :insert
assert_integer index, :index
assert_unit index, nil, :index
insertion_point = if index.value > 0
[index.value - 1, original.value.size].min
else
[index.value, -original.value.size - 1].max
end
result = original.value.dup.insert(insertion_point, insert.value)
Sass::Script::Value::String.new(result, original.type)
end
|
#str_length($string) ⇒ Sass::Script::Value::Number
Returns the number of characters in a string.
1437 1438 1439 1440 |
# File 'lib/sass/script/functions.rb', line 1437
def str_length(string)
assert_type string, :String, :string
number(string.value.size)
end
|
#str_slice($string, $start-at, $end-at: -1) ⇒ Sass::Script::Value::String
Extracts a substring from $string
. The substring will begin at index
$start-at
and ends at index $end-at
.
Note that unlike some languages, the first character in a Sass string is number 1, the second number 2, and so forth.
1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 |
# File 'lib/sass/script/functions.rb', line 1525
def str_slice(string, start_at, end_at = nil)
assert_type string, :String, :string
assert_unit start_at, nil, "start-at"
end_at = number(-1) if end_at.nil?
assert_unit end_at, nil, "end-at"
return Sass::Script::Value::String.new("", string.type) if end_at.value == 0
s = start_at.value > 0 ? start_at.value - 1 : start_at.value
e = end_at.value > 0 ? end_at.value - 1 : end_at.value
s = string.value.length + s if s < 0
s = 0 if s < 0
e = string.value.length + e if e < 0
e = 0 if s < 0
extracted = string.value.slice(s..e)
Sass::Script::Value::String.new(extracted || "", string.type)
end
|
#to_lower_case($string) ⇒ Sass::Script::Value::String
Convert a string to lower case,
1569 1570 1571 1572 |
# File 'lib/sass/script/functions.rb', line 1569
def to_lower_case(string)
assert_type string, :String, :string
Sass::Script::Value::String.new(string.value.downcase, string.type)
end
|
#to_upper_case($string) ⇒ Sass::Script::Value::String
Converts a string to upper case.
1554 1555 1556 1557 |
# File 'lib/sass/script/functions.rb', line 1554
def to_upper_case(string)
assert_type string, :String, :string
Sass::Script::Value::String.new(string.value.upcase, string.type)
end
|
#transparentize($color, $amount) ⇒ Sass::Script::Value::Color Also known as: fade_out
Makes a color more transparent. Takes a color and a number between 0 and 1, and returns a color with the opacity decreased by that amount.
938 939 940 |
# File 'lib/sass/script/functions.rb', line 938
def transparentize(color, amount)
_adjust(color, amount, :alpha, 0..1, :-)
end
|
#type_of($value) ⇒ Sass::Script::Value::String
Returns the type of a value.
1588 1589 1590 |
# File 'lib/sass/script/functions.rb', line 1588
def type_of(value)
identifier(value.class.name.gsub(/Sass::Script::Value::/, '').downcase)
end
|
#unique_id ⇒ Sass::Script::Value::String
Returns a unique CSS identifier. The identifier is returned as an unquoted string. The identifier returned is only guaranteed to be unique within the scope of a single Sass run.
2151 2152 2153 2154 2155 2156 2157 2158 |
# File 'lib/sass/script/functions.rb', line 2151
def unique_id
generator = Sass::Script::Functions.random_number_generator
Thread.current[:sass_last_unique_id] ||= generator.rand(36**8)
# avoid the temptation of trying to guess the next unique value.
value = (Thread.current[:sass_last_unique_id] += (generator.rand(10) + 1))
# the u makes this a legal identifier if it would otherwise start with a number.
identifier("u" + value.to_s(36).rjust(8, '0'))
end
|
#unit($number) ⇒ Sass::Script::Value::String
Returns the unit(s) associated with a number. Complex units are sorted in alphabetical order by numerator and denominator.
1638 1639 1640 1641 |
# File 'lib/sass/script/functions.rb', line 1638
def unit(number)
assert_type number, :Number, :number
quoted_string(number.unit_str)
end
|
#unitless($number) ⇒ Sass::Script::Value::Bool
Returns whether a number has units.
1653 1654 1655 1656 |
# File 'lib/sass/script/functions.rb', line 1653
def unitless(number)
assert_type number, :Number, :number
bool(number.unitless?)
end
|
#unquote($string) ⇒ Sass::Script::Value::String
Removes quotes from a string. If the string is already unquoted, this will return it unmodified.
1399 1400 1401 1402 1403 1404 1405 |
# File 'lib/sass/script/functions.rb', line 1399
def unquote(string)
if string.is_a?(Sass::Script::Value::String) && string.type != :identifier
identifier(string.value)
else
string
end
end
|
#variable_exists($name) ⇒ Sass::Script::Value::Bool
Check whether a variable with the given name exists in the current scope or in the global scope.
2231 2232 2233 2234 |
# File 'lib/sass/script/functions.rb', line 2231
def variable_exists(name)
assert_type name, :String, :name
bool(environment.caller.var(name.value))
end
|
#zip($lists...) ⇒ Sass::Script::Value::List
Combines several lists into a single multidimensional list. The nth value of the resulting list is a space separated list of the source lists' nth values.
The length of the resulting list is the length of the shortest list.
1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 |
# File 'lib/sass/script/functions.rb', line 1941
def zip(*lists)
length = nil
values = []
lists.each do |list|
array = list.to_a
values << array.dup
length = length.nil? ? array.length : [length, array.length].min
end
values.each do |value|
value.slice!(length)
end
new_list_value = values.first.zip(*values[1..-1])
list(new_list_value.map {|list| list(list, :space)}, :comma)
end
|