Module: Sass::Script::Functions
-
Included in:
- EvaluationContext Defined in:
- /Users/hcatlin/dev/sass/site/.sass/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
Lists in Sass are immutable; all list functions return a new list rather than updating the existing list in-place.
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
Maps in Sass are immutable; all map functions return a new map rather than updating the existing map in-place.
-
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 string, 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) random_number_generator
Get Sass’s internal random number generator.
- + (Integer) random_seed=(seed)
Sets the random seed used by Sass’s internal random number generator.
- + ({Symbol => Object}?) signature(method_name, arg_arity, kwarg_arity)
Determine the correct signature for the number of arguments passed in for a given function.
Instance Method Summary(collapse)
- - (Sass::Script::Value::Number) abs($number)
Returns the absolute value of a number.
- - (Sass::Script::Value::Color) adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
Increases or decreases one or more properties of a color.
- - (Sass::Script::Value::Color) adjust_hue($color, $degrees)
Changes the hue of a color.
- - (Sass::Script::Value::Number) alpha($color)
Returns the alpha component (opacity) of a color.
- - (Sass::Script::Value::List) append($list, $val, $separator:auto)
Appends a single value onto the end of a list.
- - (Sass::Script::Value::Number) blue($color)
Gets the blue component of a color.
- - call($name, $args...)
Dynamically calls a function.
- - (Sass::Script::Value::Number) ceil($number)
Rounds a number up to the next whole number.
- - (Sass::Script::Value::Color) change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
Changes one or more properties of a color.
- - (Sass::Script::Value::Bool) comparable($number1, $number2)
Returns whether two numbers can added, subtracted, or compared.
- - (Sass::Script::Value::Color) complement($color)
Returns the complement of a color.
- - (Sass::Script::Value::String) counter($args...)
This function only exists as a workaround for IE7’s
content: counter
bug. - - (Sass::Script::Value::String) counters($args...)
This function only exists as a workaround for IE7’s
content: counter
bug. - - (Sass::Script::Value::Color) darken($color, $amount)
Makes a color darker.
- - (Sass::Script::Value::Color) desaturate($color, $amount)
Makes a color less saturated.
- - (Sass::Script::Value::Bool) feature_exists($feature)
Returns whether a feature exists in the current Sass runtime.
- - (Sass::Script::Value::Number) floor($number)
Rounds a number down to the previous whole number.
- - (Sass::Script::Value::Bool) function_exists($name)
Check whether a function with the given name exists.
- - (Sass::Script::Value::Bool) global_variable_exists($name)
Check whether a variable with the given name exists in the global scope (at the top level of the file).
- - (Sass::Script::Value::Color) grayscale($color)
Converts a color to grayscale.
- - (Sass::Script::Value::Number) green($color)
Gets the green component of a color.
- - (Sass::Script::Value::Color) hsl($hue, $saturation, $lightness)
Creates a Color from hue, saturation, and lightness values.
- - (Sass::Script::Value::Color) hsla($hue, $saturation, $lightness, $alpha)
Creates a Color from hue, saturation, lightness, and alpha values.
- - (Sass::Script::Value::Number) hue($color)
Returns the hue component of a color.
- - (Sass::Script::Value::String) ie_hex_str($color)
Converts a color into the format understood by IE filters.
- - (Sass::Script::Value::Base) if($condition, $if-true, $if-false)
Returns one of two values, depending on whether or not
$condition
is true. - - (Sass::Script::Value::Number, Sass::Script::Value::Null) index($list, $value)
Returns the position of a value within a list.
- - (Sass::Script::Value::String) inspect($value)
Return a string containing the value as its Sass representation.
- - (Sass::Script::Value::Color) invert($color)
Returns the inverse (negative) of a color.
- - (Sass::Script::Value::Bool) is_superselector($super, $sub)
Returns whether
$super
is a superselector of$sub
. - - (Sass::Script::Value::List) join($list1, $list2, $separator:auto)
Joins together two lists into one.
- - (Sass::Script::Value::Map) keywords($args)
Returns the map of named arguments passed to a function or mixin that takes a variable argument list.
- - (Sass::Script::Value::Number) length($list)
Return the length of a list.
- - (Sass::Script::Value::Color) lighten($color, $amount)
Makes a color lighter.
- - (Sass::Script::Value::Number) lightness($color)
Returns the lightness component of a color.
- - (Sass::Script::Value::String) list_separator($list)
Returns the separator of a list.
- - (Sass::Script::Value::Base) map_get($map, $key)
Returns the value in a map associated with the given key.
- - (Sass::Script::Value::Bool) map_has_key($map, $key)
Returns whether a map has a value associated with a given key.
- - (List) map_keys($map)
Returns a list of all keys in a map.
- - (Sass::Script::Value::Map) map_merge($map1, $map2)
Merges two maps together into a new map.
- - (Sass::Script::Value::Map) map_remove($map, $keys...)
Returns a new map with keys removed.
- - (List) map_values($map)
Returns a list of all values in a map.
- - (Sass::Script::Value::Number) max($numbers...)
Finds the maximum of several numbers.
- - (Sass::Script::Value::Number) min($numbers...)
Finds the minimum of several numbers.
- - (Sass::Script::Value::Color) mix($color1, $color2, $weight:50%)
Mixes two colors together.
- - (Sass::Script::Value::Bool) mixin_exists($name)
Check whether a mixin with the given name exists.
- - (Sass::Script::Value::Base) nth($list, $n)
Gets the nth item in a list.
- - (Sass::Script::Value::Color) opacify($color, $amount) (also: #fade_in)
Makes a color more opaque.
- - (Sass::Script::Value::Number) opacity($color)
Returns the alpha component (opacity) of a color.
- - (Sass::Script::Value::Number) percentage($number)
Converts a unitless number to a percentage.
- - (Sass::Script::Value::String) quote($string)
Add quotes to a string if the string isn’t quoted, or returns the same string if it is.
- - random(limit = nil)
- - (Sass::Script::Value::Number) red($color)
Gets the red component of a color.
- - (Sass::Script::Value::Color) rgb($red, $green, $blue)
Creates a Color object from red, green, and blue values.
- - rgba(*args)
Creates a Color from red, green, blue, and alpha values.
- - (Sass::Script::Value::Number) round($number)
Rounds a number to the nearest whole number.
- - (Sass::Script::Value::Color) saturate($color, $amount)
Makes a color more saturated.
- - (Sass::Script::Value::Number) saturation($color)
Returns the saturation component of a color.
- - (Sass::Script::Value::Color) scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])
Fluidly scales one or more properties of a color.
- - (Sass::Script::Value::List) selector_append($selectors...)
Return a new selector with all selectors in
$selectors
appended one another as though they had been nested in the stylesheet as$selector1 { &$selector2 { ... } }
. - - (Sass::Script::Value::List) selector_extend($selector, $extendee, $extender)
Returns a new version of
$selector
with$extendee
extended with$extender
. - - (Sass::Script::Value::List) selector_nest($selectors...)
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 { ... } }
. - - (Sass::Script::Value::List) selector_parse($selector)
Parses a user-provided selector into a list of lists of strings as returned by
&
. - - (Sass::Script::Value::List) selector_replace($selector, $original, $replacement)
Replaces all instances of
$original
with$replacement
in$selector
. - - (Sass::Script::Value::List, Sass::Script::Value::Null) selector_unify($selector1, $selector2)
Unifies two selectors into a single selector that matches only elements matched by both input selectors.
- - (Sass::Script::Value::List) set
Return a new list, based on the list provided, but with the nth element changed to the value given.
- - (Sass::Script::Value::List) simple_selectors($selector)
Returns the simple selectors that comprise the compound selector
$selector
. - - (Sass::Script::Value::Number, Sass::Script::Value::Null) str_index($string, $substring)
Returns the index of the first occurrence of
$substring
in$string
. - - (Sass::Script::Value::String) str_insert($string, $insert, $index)
Inserts
$insert
into$string
at$index
. - - (Sass::Script::Value::Number) str_length($string)
Returns the number of characters in a string.
- - (Sass::Script::Value::String) str_slice($string, $start-at, $end-at:-1)
Extracts a substring from
$string
. - - (Sass::Script::Value::String) to_lower_case($string)
Convert a string to lower case,.
- - (Sass::Script::Value::String) to_upper_case($string)
Converts a string to upper case.
- - (Sass::Script::Value::Color) transparentize($color, $amount) (also: #fade_out)
Makes a color more transparent.
- - (Sass::Script::Value::String) type_of($value)
Returns the type of a value.
- - (Sass::Script::Value::String) unique_id
Returns a unique CSS identifier.
- - (Sass::Script::Value::String) unit($number)
Returns the unit(s) associated with a number.
- - (Sass::Script::Value::Bool) unitless($number)
Returns whether a number has units.
- - (Sass::Script::Value::String) unquote($string)
Removes quotes from a string.
- - (Sass::Script::Value::Bool) variable_exists($name)
Check whether a variable with the given name exists in the current scope or in the global scope.
- - (Sass::Script::Value::List) zip($lists...)
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.
+ (Integer) random_seed=(seed)
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.
+ ({Symbol => Object}?) signature(method_name, arg_arity, kwarg_arity)
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.
Instance Method Details
- (Sass::Script::Value::Color) adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
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.
- (Sass::Script::Value::Color) adjust_hue($color, $degrees)
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.
- (Sass::Script::Value::Number) alpha($color)
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.
- (Sass::Script::Value::List) append($list, $val, $separator:auto)
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.
Like all list functions, append()
returns a new list rather than modifying its argument in place.
- (Sass::Script::Value::Number) blue($color)
Gets the blue component of a color. Calculated from HSL where necessary via this algorithm.
- 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.
- (Sass::Script::Value::Number) ceil($number)
Rounds a number up to the next whole number.
- (Sass::Script::Value::Color) change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])
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.
- (Sass::Script::Value::Bool) comparable($number1, $number2)
Returns whether two numbers can added, subtracted, or compared.
- (Sass::Script::Value::Color) complement($color)
Returns the complement of a color. This is identical to adjust-hue(color, 180deg)
.
- (Sass::Script::Value::String) counter($args...)
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.
- (Sass::Script::Value::String) counters($args...)
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.
- (Sass::Script::Value::Color) darken($color, $amount)
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.
- (Sass::Script::Value::Color) desaturate($color, $amount)
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.
- (Sass::Script::Value::Bool) feature_exists($feature)
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.
- (Sass::Script::Value::Number) floor($number)
Rounds a number down to the previous whole number.
- (Sass::Script::Value::Bool) function_exists($name)
Check whether a function with the given name exists.
- (Sass::Script::Value::Bool) global_variable_exists($name)
Check whether a variable with the given name exists in the global scope (at the top level of the file).
- (Sass::Script::Value::Color) grayscale($color)
Converts a color to grayscale. This is identical to desaturate(color, 100%)
.
- (Sass::Script::Value::Number) green($color)
Gets the green component of a color. Calculated from HSL where necessary via this algorithm.
- (Sass::Script::Value::Color) hsl($hue, $saturation, $lightness)
[View source]- (Sass::Script::Value::Number) hue($color)
Returns the hue component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
- (Sass::Script::Value::String) ie_hex_str($color)
Converts a color into the format understood by IE filters.
- (Sass::Script::Value::Base) if($condition, $if-true, $if-false)
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.
- (Sass::Script::Value::Number, Sass::Script::Value::Null) index($list, $value)
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.
- (Sass::Script::Value::String) inspect($value)
Return a string containing the value as its Sass representation.
- (Sass::Script::Value::Color) invert($color)
Returns the inverse (negative) of a color. The red, green, and blue values are inverted, while the opacity is left alone.
- (Sass::Script::Value::Bool) is_superselector($super, $sub)
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.
- (Sass::Script::Value::List) join($list1, $list2, $separator:auto)
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.
Like all list functions, join()
returns a new list rather than modifying its arguments in place.
- (Sass::Script::Value::Map) keywords($args)
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 $
.
- (Sass::Script::Value::Number) length($list)
Return the length of a list.
This can return the number of pairs in a map as well.
- (Sass::Script::Value::Color) lighten($color, $amount)
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.
- (Sass::Script::Value::Number) lightness($color)
Returns the lightness component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
- (Sass::Script::Value::String) list_separator($list)
Returns the separator of a list. If the list doesn’t have a separator due to having fewer than two elements, returns space
.
- (Sass::Script::Value::Base) map_get($map, $key)
Returns the value in a map associated with the given key. If the map doesn’t have such a key, returns null
.
- (Sass::Script::Value::Bool) map_has_key($map, $key)
Returns whether a map has a value associated with a given key.
- (Sass::Script::Value::Map) map_merge($map1, $map2)
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.
Like all map functions, map-merge()
returns a new map rather than modifying its arguments in place.
- (Sass::Script::Value::Map) map_remove($map, $keys...)
Returns a new map with keys removed.
Like all map functions, map-merge()
returns a new map rather than modifying its arguments in place.
- (List) map_values($map)
Returns a list of all values in a map. This list may include duplicate values, if multiple keys have the same value.
- (Sass::Script::Value::Number) max($numbers...)
Finds the maximum of several numbers. This function takes any number of arguments.
- (Sass::Script::Value::Number) min($numbers...)
Finds the minimum of several numbers. This function takes any number of arguments.
- (Sass::Script::Value::Color) mix($color1, $color2, $weight:50%)
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.
- (Sass::Script::Value::Bool) mixin_exists($name)
Check whether a mixin with the given name exists.
- (Sass::Script::Value::Base) nth($list, $n)
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.
- (Sass::Script::Value::Color) opacify($color, $amount)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.
- (Sass::Script::Value::Number) opacity($color)
Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.
- (Sass::Script::Value::Number) percentage($number)
Converts a unitless number to a percentage.
- (Sass::Script::Value::String) quote($string)
Add quotes to a string if the string isn’t quoted, or returns the same string if it is.
- (Sass::Script::Value::Number) red($color)
Gets the red component of a color. Calculated from HSL where necessary via this algorithm.
- (Sass::Script::Value::Color) rgb($red, $green, $blue)
Creates a Color object from red, green, and blue values.
- (Sass::Script::Value::Color) rgba($red, $green, $blue, $alpha)- (Sass::Script::Value::Color) rgba($color, $alpha)
Creates a Color from red, green, blue, and alpha values.
- (Sass::Script::Value::Number) round($number)
Rounds a number to the nearest whole number.
- (Sass::Script::Value::Color) saturate($color, $amount)
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.
- (Sass::Script::Value::Number) saturation($color)
Returns the saturation component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.
- (Sass::Script::Value::Color) scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])
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.
- (Sass::Script::Value::List) selector_append($selectors...)
Return a new selector with all selectors in $selectors
appended one another as though they had been nested in the stylesheet as $selector1 { &$selector2 { ... } }
.
- (Sass::Script::Value::List) selector_extend($selector, $extendee, $extender)
Returns a new version of $selector
with $extendee
extended with $extender
. This works just like the result of
$selector { ... }
$extender { @extend $extendee }
- (Sass::Script::Value::List) selector_nest($selectors...)
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.
- (Sass::Script::Value::List) selector_parse($selector)
Parses a user-provided selector into a list of lists of strings as returned by &
.
- (Sass::Script::Value::List) selector_replace($selector, $original, $replacement)
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.
- (Sass::Script::Value::List, Sass::Script::Value::Null) selector_unify($selector1, $selector2)
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.
- (Sass::Script::Value::List) set
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.
- (Sass::Script::Value::List) simple_selectors($selector)
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.
- (Sass::Script::Value::Number, Sass::Script::Value::Null) str_index($string, $substring)
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.
- (Sass::Script::Value::String) str_insert($string, $insert, $index)
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.
- (Sass::Script::Value::Number) str_length($string)
Returns the number of characters in a string.
- (Sass::Script::Value::String) str_slice($string, $start-at, $end-at:-1)
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.
- (Sass::Script::Value::String) to_lower_case($string)
Convert a string to lower case,
- (Sass::Script::Value::String) to_upper_case($string)
Converts a string to upper case.
- (Sass::Script::Value::Color) transparentize($color, $amount)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.
- (Sass::Script::Value::String) unique_id
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.
- (Sass::Script::Value::String) unit($number)
Returns the unit(s) associated with a number. Complex units are sorted in alphabetical order by numerator and denominator.
- (Sass::Script::Value::String) unquote($string)
Removes quotes from a string. If the string is already unquoted, this will return it unmodified.
- (Sass::Script::Value::Bool) variable_exists($name)
Check whether a variable with the given name exists in the current scope or in the global scope.
- (Sass::Script::Value::List) zip($lists...)
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.