module Sass::Script::Functions

YARD can't handle some multiline tags, and we need really long tags for function declarations.

Methods in this module are accessible from the SassScript context. For example, you can write

$color: hsl(120deg, 100%, 50%)

and it will call {Functions#hsl}.

The following functions are provided:

*Note: These functions are described in more detail below.*

## RGB Functions

{#rgb rgb($red, $green, $blue)} : Creates a {Sass::Script::Value::Color Color} from red, green, and blue

values.

{#rgba rgba($red, $green, $blue, $alpha)} : Creates a {Sass::Script::Value::Color Color} from red, green, blue, and

alpha values.

{#red red($color)} : Gets the red component of a color.

{#green green($color)} : Gets the green component of a color.

{#blue blue($color)} : Gets the blue component of a color.

{#mix mix($color1, $color2, [$weight])} : Mixes two colors together.

## HSL Functions

{#hsl hsl($hue, $saturation, $lightness)} : Creates a {Sass::Script::Value::Color Color} from hue, saturation, and

lightness values.

{#hsla hsla($hue, $saturation, $lightness, $alpha)} : Creates a {Sass::Script::Value::Color Color} from hue, saturation,

lightness, and alpha values.

{#hue hue($color)} : Gets the hue component of a color.

{#saturation saturation($color)} : Gets the saturation component of a color.

{#lightness lightness($color)} : Gets the lightness component of a color.

{#adjust_hue adjust-hue($color, $degrees)} : Changes the hue of a color.

{#lighten lighten($color, $amount)} : Makes a color lighter.

{#darken darken($color, $amount)} : Makes a color darker.

{#saturate saturate($color, $amount)} : Makes a color more saturated.

{#desaturate desaturate($color, $amount)} : Makes a color less saturated.

{#grayscale grayscale($color)} : Converts a color to grayscale.

{#complement complement($color)} : Returns the complement of a color.

{#invert invert($color, [$weight])} : Returns the inverse of a color.

## Opacity Functions

{#alpha alpha($color)} / {#opacity opacity($color)} : Gets the alpha component (opacity) of a color.

{#rgba rgba($color, $alpha)} : Changes the alpha component for a color.

{#opacify opacify($color, $amount)} / {#fade_in fade-in($color, $amount)} : Makes a color more opaque.

{#transparentize transparentize($color, $amount)} / {#fade_out fade-out($color, $amount)} : Makes a color more transparent.

## Other Color Functions

{#adjust_color adjust-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])} : Increases or decreases one or more components of a color.

{#scale_color scale-color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha])} : Fluidly scales one or more properties of a color.

{#change_color change-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha])} : Changes one or more properties of a color.

{#ie_hex_str ie-hex-str($color)} : Converts a color into the format understood by IE filters.

## String Functions

{#unquote unquote($string)} : Removes quotes from a string.

{#quote quote($string)} : Adds quotes to a string.

{#str_length str-length($string)} : Returns the number of characters in a string.

{#str_insert str-insert($string, $insert, $index)} : Inserts ‘$insert` into `$string` at `$index`.

{#str_index str-index($string, $substring)} : Returns the index of the first occurrence of ‘$substring` in `$string`.

{#str_slice str-slice($string, $start-at, [$end-at])} : Extracts a substring from ‘$string`.

{#to_upper_case to-upper-case($string)} : Converts a string to upper case.

{#to_lower_case to-lower-case($string)} : Converts a string to lower case.

## Number Functions

{#percentage percentage($number)} : Converts a unitless number to a percentage.

{#round round($number)} : Rounds a number to the nearest whole number.

{#ceil ceil($number)} : Rounds a number up to the next whole number.

{#floor floor($number)} : Rounds a number down to the previous whole number.

{#abs abs($number)} : Returns the absolute value of a number.

{#min min($numbers…)} : Finds the minimum of several numbers.

{#max max($numbers…)} : Finds the maximum of several numbers.

{#random random()} : Returns a random number.

## List Functions {#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 length($list)} : Returns the length of a list.

{#nth nth($list, $n)} : Returns a specific item in a list.

{#set-nth set-nth($list, $n, $value)} : Replaces the nth item in a list.

{#join join($list1, $list2, [$separator, $bracketed])} : Joins together two lists into one.

{#append append($list1, $val, [$separator])} : Appends a single value onto the end of a list.

{#zip zip($lists…)} : Combines several lists into a single multidimensional list.

{#index index($list, $value)} : Returns the position of a value within a list.

{#list_separator list-separator($list)} : Returns the separator of a list.

{#is_bracketed is-bracketed($list)} : Returns whether a list has square brackets.

## Map Functions {#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-get($map, $key)} : Returns the value in a map associated with a given key.

{#map_merge map-merge($map1, $map2)} : Merges two maps together into a new map.

{#map_remove map-remove($map, $keys…)} : Returns a new map with keys removed.

{#map_keys map-keys($map)} : Returns a list of all keys in a map.

{#map_values map-values($map)} : Returns a list of all values in a map.

{#map_has_key map-has-key($map, $key)} : Returns whether a map has a value associated with a given key.

{#keywords 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:

In general, selector functions allow placeholder selectors (‘%foo`) but disallow parent-reference selectors (`&`).

{#selector_nest selector-nest($selectors…)} : Nests selector beneath one another like they would be nested in the

stylesheet.

{#selector_append selector-append($selectors…)} : Appends selectors to one another without spaces in between.

{#selector_extend selector-extend($selector, $extendee, $extender)} : Extends ‘$extendee` with `$extender` within `$selector`.

{#selector_replace selector-replace($selector, $original, $replacement)} : Replaces ‘$original` with `$replacement` within `$selector`.

{#selector_unify selector-unify($selector1, $selector2)} : Unifies two selectors to produce a selector that matches

elements matched by both.

{#is_superselector is-superselector($super, $sub)} : Returns whether ‘$super` matches all the elements `$sub` does, and

possibly more.

{#simple_selectors simple-selectors($selector)} : Returns the simple selectors that comprise a compound selector.

{#selector_parse selector-parse($selector)} : Parses a selector into the format returned by ‘&`.

## Introspection Functions

{#feature_exists feature-exists($feature)} : Returns whether a feature exists in the current Sass runtime.

{#variable_exists variable-exists($name)} : Returns whether a variable with the given name exists in the current scope.

{#global_variable_exists global-variable-exists($name)} : Returns whether a variable with the given name exists in the global scope.

{#function_exists function-exists($name)} : Returns whether a function with the given name exists.

{#mixin_exists mixin-exists($name)} : Returns whether a mixin with the given name exists.

{#content_exists content-exists()} : Returns whether the current mixin was passed a content block.

{#inspect inspect($value)} : Returns the string representation of a value as it would be represented in Sass.

{#type_of type-of($value)} : Returns the type of a value.

{#unit unit($number)} : Returns the unit(s) associated with a number.

{#unitless unitless($number)} : Returns whether a number has units.

{#comparable comparable($number1, $number2)} : Returns whether two numbers can be added, subtracted, or compared.

{#call call($function, $args…)} : Dynamically calls a Sass function reference returned by ‘get-function`.

{#get_function get-function($name, $css: false)} : Looks up a function with the given name in the current lexical scope

and returns a reference to it.

## Miscellaneous Functions

{#if if($condition, $if-true, $if-false)} : Returns one of two values, depending on whether or not ‘$condition` is

true.

{#unique_id 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 {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. {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::Base#value value} accessor for getting their Ruby values. Color objects, though, must be accessed using {Sass::Script::Value::Color#rgb rgb}, {Sass::Script::Value::Color#red red}, {Sass::Script::Value::Color#blue green}, or {Sass::Script::Value::Color#blue 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 {Sass::Engine} to render the code, using the {file:SASS_REFERENCE.md#custom-option ‘options` parameter} to pass in data that {EvaluationContext#options 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 {Value::Base#to_s to_s} (or other methods that use the string representation) on those objects without first setting {Tree::Node#options= the options attribute}.