Module: Sass::Script::Functions

Included in:
EvaluationContext
Defined in:
.ruby-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, [$weight]) : 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 occurrence 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() : 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($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, $bracketed]) : 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.

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, $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.

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

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($function, $args…) : Dynamically calls a Sass function reference returned by `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($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)

Instance Method Summary (collapse)

Class Method Details

.declare(method_name, args, options = {}) ⇒ Object

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.

Examples:

declare :rgba, [:hex, :alpha]
declare :rgba, [:red, :green, :blue, :alpha]
declare :accepts_anything, [], :var_args => true, :var_kwargs => true
declare :some_func, [:foo, :bar, :baz], :var_kwargs => true

Parameters:

  • method_name (Symbol) —

    The name of the method whose signature is being declared.

  • args (Array<Symbol>) —

    The names of the arguments for the function signature.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :var_args (Boolean) — default: false —

    Whether the function accepts a variable number of (unnamed) arguments in addition to the named arguments.

  • :var_kwargs (Boolean) — default: false —

    Whether the function accepts other keyword arguments in addition to those in `:args`. If this is true, the Ruby function will be passed a hash from strings to Values as the last argument. In addition, if this is true and `:var_args` is not, Sass will ensure that the last argument passed is a hash.



416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 416

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.

Returns:

  • (Random) 


490
491
492
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 490

def self.random_number_generator
  @random_number_generator ||= Random.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.

Parameters:

  • seed (Integer)

Returns:

  • (Integer) —

    The same seed.



483
484
485
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 483

def self.random_seed=(seed)
  @random_number_generator = Random.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.

Parameters:

  • method_name (Symbol) —

    The name of the Ruby function to be called.

  • arg_arity (Integer) —

    The number of unnamed arguments the function was passed.

  • kwarg_arity (Integer) —

    The number of keyword arguments the function was passed.

Returns:

  • ({Symbol => Object}, nil) —

    The signature options for the matching signature, or nil if no signatures are declared for this function. See declare.



450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 450

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.

Examples:

abs(10px) => 10px
abs(-10px) => 10px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1923
1924
1925
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1923

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.

Examples:

adjust-color(#102030, $blue: 5) => #102035
adjust-color(#102030, $red: -5, $blue: 5) => #0b2035
adjust-color(hsl(25, 100%, 80%), $lightness: -30%, $alpha: -0.4) => hsla(25, 100%, 50%, 0.6)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type or out-of bounds, or if RGB properties and HSL properties are adjusted at the same time



1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1205

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.

Examples:

adjust-hue(hsl(120, 30%, 90%), 60deg) => hsl(180, 30%, 90%)
adjust-hue(hsl(120, 30%, 90%), -60deg) => hsl(60, 30%, 90%)
adjust-hue(#811, 45deg) => #886a11

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if either parameter is the wrong type



1147
1148
1149
1150
1151
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1147

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.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



977
978
979
980
981
982
983
984
985
986
987
988
989
990
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 977

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.

Like all list functions, `append()` returns a new list rather than modifying its argument in place.

Examples:

append(10px 20px, 30px) => 10px 20px 30px
append((blue, red), green) => blue, red, green
append(10px 20px, 30px 40px) => 10px 20px (30px 40px)
append(10px, 20px, comma) => 10px, 20px
append((blue, red), green, space) => blue red green

Parameters:

Returns:



2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2146

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
  list.with_contents(list.to_a + [val],
    separator:
      if separator.value == 'auto'
        list.separator || :space
      else
        separator.value.to_sym
      end)
end

#blue($color) ⇒ Sass::Script::Value::Number

Gets the blue component of a color. Calculated from HSL where necessary via [this algorithm].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



907
908
909
910
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 907

def blue(color)
  assert_type color, :Color, :color
  number(color.blue)
end

#call($function, $args...) ⇒ Object

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.

Examples:

call(rgb, 10, 100, 255) => #0a64ff
call(scale-color, #0a64ff, $lightness: -10%) => #0058ef

$fn: nth;
call($fn, (a b c), 2) => b

Parameters:



2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2428

def call(name, *args)
  unless name.is_a?(Sass::Script::Value::String) ||
         name.is_a?(Sass::Script::Value::Function)
    assert_type name, :Function, :function
  end
  if name.is_a?(Sass::Script::Value::String)
    name = if function_exists(name).to_bool
             get_function(name)
           else
             get_function(name, "css" => bool(true))
           end
    Sass::Util.sass_warn(<<WARNING)
DEPRECATION WARNING: Passing a string to call() is deprecated and will be illegal
in Sass 4.0. Use call(#{name.to_sass}) instead.
WARNING
  end
  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.line = environment.stack.frames.last.line
  funcall.filename = environment.stack.frames.last.filename
  funcall.options = options
  perform(funcall)
end

#ceil($number) ⇒ Sass::Script::Value::Number

Rounds a number up to the next whole number.

Examples:

ceil(10.4px) => 11px
ceil(10.6px) => 11px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1895
1896
1897
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1895

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.

Examples:

change-color(#102030, $blue: 5) => #102005
change-color(#102030, $red: 120, $blue: 5) => #782005
change-color(hsl(25, 100%, 80%), $lightness: 40%, $alpha: 0.8) => hsla(25, 100%, 40%, 0.8)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type or out-of bounds, or if RGB properties and HSL properties are adjusted at the same time



1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1337

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.

Examples:

comparable(2px, 1px) => true
comparable(100px, 3em) => false
comparable(10cm, 3mm) => true

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if either parameter is the wrong type



1848
1849
1850
1851
1852
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1848

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)`.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color

See Also:



1456
1457
1458
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1456

def complement(color)
  adjust_hue color, number(180)
end

#content_exists ⇒ Sass::Script::Value::Bool

Check whether a mixin was passed a content block.

Unless `content-exists()` is called directly from a mixin, an error will be raised.

Examples:

@mixin needs-content {
  @if not content-exists() {
    @error "You must pass a content block!"
  }
  @content;
}

Returns:



2583
2584
2585
2586
2587
2588
2589
2590
2591
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2583

def content_exists
  # frames.last is the stack frame for this function,
  # so we use frames[-2] to get the frame before that.
  mixin_frame = environment.stack.frames[-2]
  unless mixin_frame && mixin_frame.type == :mixin
    raise Sass::SyntaxError.new("Cannot call content-exists() except within a mixin.")
  end
  bool(!environment.caller.content.nil?)
end

#counter($args...) ⇒ Sass::Script::Value::String

This function only exists as a workaround for IE7's [`content: counter` bug](jes.st/2013/ie7s-css-breaking-content-counter-bug/). It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

Examples:

counter(item, ".") => counter(item,".")

Returns:



2467
2468
2469
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2467

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](jes.st/2013/ie7s-css-breaking-content-counter-bug/). It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

Examples:

counters(item, ".") => counters(item,".")

Returns:



2481
2482
2483
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2481

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.

Examples:

darken(hsl(25, 100%, 80%), 30%) => hsl(25, 100%, 50%)
darken(#800, 20%) => #200

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1086
1087
1088
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1086

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.

Examples:

desaturate(hsl(120, 30%, 90%), 20%) => hsl(120, 10%, 90%)
desaturate(#855, 20%) => #726b6b

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1128
1129
1130
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1128

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.

[Values and Units Level 3]: www.w3.org/TR/css3-values/

  • `at-error` indicates that the Sass `@error` directive is supported.

  • `custom-property` indicates that the [Custom Properties Level 1][] spec is supported. This means that custom properties are parsed statically, with only interpolation treated as SassScript.

[Custom Properties Level 1]: www.w3.org/TR/css-variables-1/

Examples:

feature-exists(some-feature-that-exists) => true
feature-exists(what-is-this-i-dont-know) => false

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$feature` isn't a string



1747
1748
1749
1750
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1747

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.

Examples:

floor(10.4px) => 10px
floor(10.6px) => 10px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1909
1910
1911
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1909

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.

Examples:

function-exists(lighten) => true

@function myfunc { @return "something"; }
function-exists(myfunc) => true

Parameters:

Returns:



2543
2544
2545
2546
2547
2548
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2543

def function_exists(name)
  assert_type name, :String, :name
  exists = Sass::Script::Functions.callable?(name.value.tr("-", "_"))
  exists ||= environment.caller.function(name.value)
  bool(exists)
end

#get_function($name, $css: false) ⇒ Sass::Script::Value::Function

Returns a reference to a function for later invocation with the `call()` function.

If `$css` is `false`, the function reference may refer to a function defined in your stylesheet or built-in to the host environment. If it's `true` it will refer to a plain-CSS function.

Examples:

get-function("rgb")

@function myfunc { @return "something"; }
get-function("myfunc")

Parameters:

Returns:



1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1770

def get_function(name, kwargs = {})
  assert_type name, :String, :name

  css = if kwargs.has_key?("css")
          v = kwargs.delete("css")
          assert_type v, :Bool, :css
          v.value
        else
          false
        end

  if kwargs.any?
    raise ArgumentError.new("Illegal keyword argument '#{kwargs.keys.first}'")
  end

  if css
    return Sass::Script::Value::Function.new(
      Sass::Callable.new(name.value, nil, nil, nil, nil, nil, "function", :css))
  end

  callable = environment.caller.function(name.value) ||
    (Sass::Script::Functions.callable?(name.value.tr("-", "_")) &&
     Sass::Callable.new(name.value, nil, nil, nil, nil, nil, "function", :builtin))

  if callable
    Sass::Script::Value::Function.new(callable)
  else
    raise Sass::SyntaxError.new("Function not found: #{name}")
  end
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).

Examples:

$a-false-value: false;
global-variable-exists(a-false-value) => true
global-variable-exists(a-null-value) => true

.foo {
  $some-var: false;
  @if global-variable-exists(some-var) { /* false, doesn't run */ }
}

Parameters:

Returns:



2525
2526
2527
2528
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2525

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%)`.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color

See Also:



1440
1441
1442
1443
1444
1445
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1440

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].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



891
892
893
894
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 891

def green(color)
  assert_type color, :Color, :color
  number(color.green)
end

#hsl($hue, $saturation, $lightness) ⇒ Sass::Script::Value::Color

Creates a Color from hue, saturation, and lightness values. Uses the algorithm from the [CSS3 spec][].

[CSS3 spec]: www.w3.org/TR/css3-color/#hsl-color

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$saturation` or `$lightness` are out of bounds or any parameter is the wrong type

See Also:



787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 787

def hsl(hue, saturation = nil, lightness = nil)
  if saturation.nil?
    return unquoted_string("hsl(#{hue})") if var?(hue)
    raise ArgumentError.new("wrong number of arguments (1 for 3)")
  elsif lightness.nil?
    return unquoted_string("hsl(#{hue}, #{saturation})") if var?(hue) || var?(saturation)
    raise ArgumentError.new("wrong number of arguments (2 for 3)")
  end

  if special_number?(hue) || special_number?(saturation) || special_number?(lightness)
    unquoted_string("hsl(#{hue}, #{saturation}, #{lightness})")
  else
    hsla(hue, saturation, lightness, number(1))
  end
end

#hsla($hue, $saturation, $lightness, $alpha) ⇒ Sass::Script::Value::Color

Creates a Color from hue, saturation, lightness, and alpha values. Uses the algorithm from the [CSS3 spec][].

[CSS3 spec]: www.w3.org/TR/css3-color/#hsl-color

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$saturation`, `$lightness`, or `$alpha` are out of bounds or any parameter is the wrong type

See Also:



825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 825

def hsla(hue, saturation = nil, lightness = nil, alpha = nil)
  if saturation.nil?
    return unquoted_string("hsla(#{hue})") if var?(hue)
    raise ArgumentError.new("wrong number of arguments (1 for 4)")
  elsif lightness.nil?
    return unquoted_string("hsla(#{hue}, #{saturation})") if var?(hue) || var?(saturation)
    raise ArgumentError.new("wrong number of arguments (2 for 4)")
  elsif alpha.nil?
    if var?(hue) || var?(saturation) || var?(lightness)
      return unquoted_string("hsla(#{hue}, #{saturation}, #{lightness})")
    else
      raise ArgumentError.new("wrong number of arguments (2 for 4)")
    end
  end

  if special_number?(hue) || special_number?(saturation) ||
     special_number?(lightness) || special_number?(alpha)
    return unquoted_string("hsla(#{hue}, #{saturation}, #{lightness}, #{alpha})")
  end
  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].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



925
926
927
928
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 925

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.

Examples:

ie-hex-str(#abc) => #FFAABBCC
ie-hex-str(#3322BB) => #FF3322BB
ie-hex-str(rgba(0, 255, 0, 0.5)) => #8000FF00

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



1165
1166
1167
1168
1169
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1165

def ie_hex_str(color)
  assert_type color, :Color, :color
  alpha = Sass::Util.round(color.alpha * 255).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.

Examples:

if(true, 1px, 2px) => 1px
if(false, 1px, 2px) => 2px

Parameters:

Returns:



2389
2390
2391
2392
2393
2394
2395
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2389

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.

Examples:

index(1px solid red, solid) => 2
index(1px solid red, dashed) => null
index((width: 10px, height: 20px), (height 20px)) => 2

Parameters:

Returns:



2208
2209
2210
2211
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2208

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.

Parameters:

Returns:



2600
2601
2602
2603
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2600

def inspect(value)
  value.check_deprecated_interp if value.is_a?(Sass::Script::Value::String)
  unquoted_string(value.to_sass)
end

#invert($color) ⇒ Sass::Script::Value::Color #invert($color, $weight: 100%) ⇒ 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.

Overloads:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color or `$weight` isn't a percentage between 0% and 100%



1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1473

def invert(color, weight = number(100))
  if color.is_a?(Sass::Script::Value::Number)
    return identifier("invert(#{color})")
  end

  assert_type color, :Color, :color
  inv = color.with(
    :red => (255 - color.red),
    :green => (255 - color.green),
    :blue => (255 - color.blue))

  mix(inv, color, weight)
end

#is_bracketed($list) ⇒ Sass::Script::Value::Bool

Returns whether a list uses square brackets.

Examples:

is-bracketed(1px 2px 3px) => false
is-bracketed([1px, 2px, 3px]) => true

Parameters:

Returns:



2237
2238
2239
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2237

def is_bracketed(list)
  bool(list.bracketed)
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.

Examples:

is-superselector(".foo", ".foo.bar") => true
is-superselector(".foo.bar", ".foo") => false
is-superselector(".bar", ".foo .bar") => true
is-superselector(".foo .bar", ".bar") => false

Returns Whether `$selector1` is a superselector of `$selector2`.

Parameters:

Returns:



2898
2899
2900
2901
2902
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2898

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, $bracketed: 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.

Unless `$bracketed` is passed, the resulting list is bracketed if the first parameter is.

Like all list functions, `join()` returns a new list rather than modifying its arguments in place.

Examples:

join(10px 20px, 30px 40px) => 10px 20px 30px 40px
join((blue, red), (#abc, #def)) => blue, red, #abc, #def
join(10px, 20px) => 10px 20px
join(10px, 20px, comma) => 10px, 20px
join((blue, red), (#abc, #def), space) => blue red #abc #def
join([10px], 20px) => [10px 20px]

Parameters:

Returns:



2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2070

def join(list1, list2,
         separator = identifier("auto"), bracketed = identifier("auto"),
         kwargs = nil, *rest)
  # rubocop:enable ParameterLists
  if separator.is_a?(Hash)
    kwargs = separator
    separator = identifier("auto")
  elsif bracketed.is_a?(Hash)
    kwargs = bracketed
    bracketed = identifier("auto")
  elsif rest.last.is_a?(Hash)
    rest.unshift kwargs
    kwargs = rest.pop
  end

  unless rest.empty?
    # Add 4 to rest.length because we don't want to count the kwargs hash,
    # which is always passed.
    raise ArgumentError.new("wrong number of arguments (#{rest.length + 4} for 2..4)")
  end

  if kwargs
    separator = kwargs.delete("separator") || separator
    bracketed = kwargs.delete("bracketed") || bracketed

    unless kwargs.empty?
      name, val = kwargs.to_a.first
      raise ArgumentError.new("Unknown argument $#{name} (#{val})")
    end
  end

  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

  list(list1.to_a + list2.to_a,
    separator:
      if separator.value == 'auto'
        list1.separator || list2.separator || :space
      else
        separator.value.to_sym
      end,
    bracketed:
      if bracketed.is_a?(Sass::Script::Value::String) && bracketed.value == 'auto'
        list1.bracketed
      else
        bracketed.to_bool
      end)
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 `$`.

Examples:

@mixin foo($args...) {
  @debug keywords($args); //=> (arg1: val, arg2: val)
}

@include foo($arg1: val, $arg2: val);

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$args` isn't a variable argument list



2370
2371
2372
2373
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2370

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.

Examples:

length(10px) => 1
length(10px 20px 30px) => 3
length((width: 10px, height: 20px)) => 2

Parameters:

Returns:



1973
1974
1975
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1973

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.

Examples:

lighten(hsl(0, 0%, 0%), 30%) => hsl(0, 0, 30)
lighten(#800, 20%) => #e00

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1067
1068
1069
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1067

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].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



961
962
963
964
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 961

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`.

Examples:

list-separator(1px 2px 3px) => space
list-separator(1px, 2px, 3px) => comma
list-separator('foo') => space

Parameters:

Returns:



2224
2225
2226
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2224

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`.

Examples:

map-get(("foo": 1, "bar": 2), "foo") => 1
map-get(("foo": 1, "bar": 2), "bar") => 2
map-get(("foo": 1, "bar": 2), "baz") => null

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$map` is not a map



2255
2256
2257
2258
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2255

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.

Examples:

map-has-key(("foo": 1, "bar": 2), "foo") => true
map-has-key(("foo": 1, "bar": 2), "baz") => false

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$map` is not a map



2350
2351
2352
2353
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2350

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.

Examples:

map-keys(("foo": 1, "bar": 2)) => "foo", "bar"

Parameters:

  • $map (Map)

Returns:

  • (List) —

    the list of keys, comma-separated

Raises:

  • (ArgumentError) —

    if `$map` is not a map



2318
2319
2320
2321
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2318

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.

Like all map functions, `map-merge()` returns a new map rather than modifying its arguments in place.

Examples:

map-merge(("foo": 1), ("bar": 2)) => ("foo": 1, "bar": 2)
map-merge(("foo": 1, "bar": 2), ("bar": 3)) => ("foo": 1, "bar": 3)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if either parameter is not a map



2281
2282
2283
2284
2285
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2281

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.

Like all map functions, `map-merge()` returns a new map rather than modifying its arguments in place.

Examples:

map-remove(("foo": 1, "bar": 2), "bar") => ("foo": 1)
map-remove(("foo": 1, "bar": 2, "baz": 3), "bar", "baz") => ("foo": 1)
map-remove(("foo": 1, "bar": 2), "baz") => ("foo": 1, "bar": 2)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$map` is not a map



2302
2303
2304
2305
2306
2307
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2302

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.

Examples:

map-values(("foo": 1, "bar": 2)) => 1, 2
map-values(("foo": 1, "bar": 2, "baz": 1)) => 1, 2, 1

Parameters:

  • $map (Map)

Returns:

  • (List) —

    the list of values, comma-separated

Raises:

  • (ArgumentError) —

    if `$map` is not a map



2334
2335
2336
2337
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2334

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.

Examples:

max(1px, 4px) => 4px
max(5em, 3em, 4em) => 5em

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any argument isn't a number, or if not all of the arguments have comparable units



1956
1957
1958
1959
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1956

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.

Examples:

min(1px, 4px) => 1px
min(5em, 3em, 4em) => 3em

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any argument isn't a number, or if not all of the arguments have comparable units



1939
1940
1941
1942
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1939

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.

Examples:

mix(#f00, #00f) => #7f007f
mix(#f00, #00f, 25%) => #3f00bf
mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$weight` is out of bounds or any parameter is the wrong type



1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1392

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.

Examples:

mixin-exists(nonexistent) => false

@mixin red-text { color: red; }
mixin-exists(red-text) => true

Parameters:

Returns:



2563
2564
2565
2566
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2563

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.

Examples:

nth(10px 20px 30px, 1) => 10px
nth((Helvetica, Arial, sans-serif), 3) => sans-serif
nth((width: 10px, length: 20px), 2) => length, 20px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$n` isn't an integer between 1 and the length of `$list`



2029
2030
2031
2032
2033
2034
2035
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2029

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.

Examples:

opacify(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.6)
opacify(rgba(0, 0, 17, 0.8), 0.2) => #001

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1023
1024
1025
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1023

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.

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



1000
1001
1002
1003
1004
1005
1006
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1000

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.

Examples:

percentage(0.2) => 20%
percentage(100px / 50px) => 200%

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a unitless number



1864
1865
1866
1867
1868
1869
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1864

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.

Examples:

quote("foo") => "foo"
quote(foo) => "foo"

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$string` isn't a string

See Also:



1536
1537
1538
1539
1540
1541
1542
1543
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1536

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

Overloads:



2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2615

def random(limit = nil)
  generator = Sass::Script::Functions.random_number_generator
  if limit
    assert_integer limit, "limit"
    if limit.to_i < 1
      raise ArgumentError.new("$limit #{limit} must be greater than or equal to 1")
    end
    number(1 + generator.rand(limit.to_i))
  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].

[hsl-to-rgb]: www.w3.org/TR/css3-color/#hsl-color

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



875
876
877
878
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 875

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.

Parameters:

  • $red (Sass::Script::Value::Number) —

    The amount of red in the color. Must be between 0 and 255 inclusive, or between `0%` and `100%` inclusive

  • $green (Sass::Script::Value::Number) —

    The amount of green in the color. Must be between 0 and 255 inclusive, or between `0%` and `100%` inclusive

  • $blue (Sass::Script::Value::Number) —

    The amount of blue in the color. Must be between 0 and 255 inclusive, or between `0%` and `100%` inclusive

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type or out of bounds

See Also:



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 656

def rgb(red, green = nil, blue = nil)
  if green.nil?
    return unquoted_string("rgb(#{red})") if var?(red)
    raise ArgumentError.new("wrong number of arguments (1 for 3)")
  elsif blue.nil?
    return unquoted_string("rgb(#{red}, #{green})") if var?(red) || var?(green)
    raise ArgumentError.new("wrong number of arguments (2 for 3)")
  end

  if special_number?(red) || special_number?(green) || special_number?(blue)
    return unquoted_string("rgb(#{red}, #{green}, #{blue})")
  end
  assert_type red, :Number, :red
  assert_type green, :Number, :green
  assert_type blue, :Number, :blue

  color_attrs = [red, green, blue].map do |c|
    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.

Overloads:

See Also:



722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 722

def rgba(*args)
  case args.size
  when 1
    return unquoted_string("rgba(#{args.first})") if var?(args.first)
    raise ArgumentError.new("wrong number of arguments (1 for 4)")
  when 2
    color, alpha = args

    if var?(color)
      return unquoted_string("rgba(#{color}, #{alpha})")
    elsif var?(alpha)
      if color.is_a?(Sass::Script::Value::Color)
        return unquoted_string("rgba(#{color.red}, #{color.green}, #{color.blue}, #{alpha})")
      else
        return unquoted_string("rgba(#{color}, #{alpha})")
      end
    end

    assert_type color, :Color, :color
    if special_number?(alpha)
      unquoted_string("rgba(#{color.red}, #{color.green}, #{color.blue}, #{alpha})")
    else
      assert_type alpha, :Number, :alpha
      check_alpha_unit alpha, 'rgba'
      color.with(:alpha => alpha.value)
    end
  when 3
    if var?(args[0]) || var?(args[1]) || var?(args[2])
      unquoted_string("rgba(#{args.join(', ')})")
    else
      raise ArgumentError.new("wrong number of arguments (3 for 4)")
    end
  when 4
    red, green, blue, alpha = args
    if special_number?(red) || special_number?(green) ||
       special_number?(blue) || special_number?(alpha)
      unquoted_string("rgba(#{red}, #{green}, #{blue}, #{alpha})")
    else
      rgba(rgb(red, green, blue), alpha)
    end
  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.

Examples:

round(10.4px) => 10px
round(10.6px) => 11px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1881
1882
1883
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1881

def round(number)
  numeric_transformation(number) {|n| Sass::Util.round(n)}
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.

Examples:

saturate(hsl(120, 30%, 90%), 20%) => hsl(120, 50%, 90%)
saturate(#855, 20%) => #9e3f3f

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1105
1106
1107
1108
1109
1110
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1105

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].

[hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV [rgb-to-hsl]: en.wikipedia.org/wiki/HSL_and_HSV#Conversion_from_RGB_to_HSL_or_HSV

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$color` isn't a color



943
944
945
946
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 943

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.

Examples:

scale-color(hsl(120, 70%, 80%), $lightness: 50%) => hsl(120, 70%, 90%)
scale-color(rgb(200, 150%, 170%), $green: -40%, $blue: 70%) => rgb(200, 90, 229)
scale-color(hsl(200, 70%, 80%), $saturation: -90%, $alpha: -30%) => hsla(200, 7%, 80%, 0.7)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type or out-of bounds, or if RGB properties and HSL properties are adjusted at the same time



1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1273

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 { … } }`.

Examples:

selector-append(".foo", ".bar", ".baz") => .foo.bar.baz
selector-append(".a .foo", ".b .bar") => "a .foo.b .bar"
selector-append(".foo", "-suffix") => ".foo-suffix"

Returns A list of lists of strings representing the result of appending `$selectors`. This is in the same format as a selector returned by `&`.

Parameters:

Returns:

  • (Sass::Script::Value::List) —

    A list of lists of strings representing the result of appending `$selectors`. This is in the same format as a selector returned by `&`.

Raises:

  • (ArgumentError) —

    if a selector could not be appended.



2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2699

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 }

Examples:

selector-extend(".a .b", ".b", ".foo .bar") => .a .b, .a .foo .bar, .foo .a .bar

Returns A list of lists of strings representing the result of the extension. This is in the same format as a selector returned by `&`.

Parameters:

Returns:

  • (Sass::Script::Value::List) —

    A list of lists of strings representing the result of the extension. This is in the same format as a selector returned by `&`.

Raises:

  • (ArgumentError) —

    if the extension fails



2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2756

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, nil, [], true)
    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.

Examples:

selector-nest(".foo", ".bar", ".baz") => .foo .bar .baz
selector-nest(".a .foo", ".b .bar") => .a .foo .b .bar
selector-nest(".foo", "&.bar") => .foo.bar

Returns A list of lists of strings representing the result of nesting `$selectors`. This is in the same format as a selector returned by `&`.

Parameters:

Returns:

  • (Sass::Script::Value::List) —

    A list of lists of strings representing the result of nesting `$selectors`. This is in the same format as a selector returned by `&`.



2669
2670
2671
2672
2673
2674
2675
2676
2677
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2669

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, true)}
  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 `&`.

Examples:

selector-parse(".foo .bar, .baz .bang") => ('.foo' '.bar', '.baz' '.bang')

Returns A list of lists of strings representing `$selector`. This is in the same format as a selector returned by `&`.

Parameters:

Returns:

  • (Sass::Script::Value::List) —

    A list of lists of strings representing `$selector`. This is in the same format as a selector returned by `&`.



2643
2644
2645
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2643

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.

Examples:

selector-replace(".foo .bar", ".bar", ".baz") => ".foo .baz"
selector-replace(".foo.bar.baz", ".foo.baz", ".qux") => ".bar.qux"

Returns A list of lists of strings representing the result of the extension. This is in the same format as a selector returned by `&`.

Parameters:

Returns:

  • (Sass::Script::Value::List) —

    A list of lists of strings representing the result of the extension. This is in the same format as a selector returned by `&`.

Raises:

  • (ArgumentError) —

    if the replacement fails



2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2799

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, nil, [], true)
    selector.do_extend(extends, [], true).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.

Examples:

selector-unify(".a", ".b") => .a.b
selector-unify(".a .b", ".x .y") => .a .x .b.y, .x .a .b.y
selector-unify(".a.b", ".b.c") => .a.b.c
selector-unify("#a", "#b") => null

Returns A list of lists of strings representing the result of the unification, or null if no unification exists. This is in the same format as a selector returned by `&`.

Parameters:

Returns:



2845
2846
2847
2848
2849
2850
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2845

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.

Examples:

set-nth($list: 10px 20px 30px, $n: 2, $value: -20px) => 10px -20px 30px

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$n` isn't an integer between 1 and the length of `$list`



1998
1999
2000
2001
2002
2003
2004
2005
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1998

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
  list.with_contents(new_list)
end

#simple_selectors($selector) ⇒ Sass::Script::Value::List

Returns the [simple selectors](dev.w3.org/csswg/selectors4/#simple) that comprise the compound selector `$selector`.

Note that `$selector` **must be** a [compound selector](dev.w3.org/csswg/selectors4/#compound). That means it cannot contain commas or spaces. It also means that unlike other selector functions, this takes only strings, not lists.

Examples:

simple-selectors(".foo.bar") => ".foo", ".bar"
simple-selectors(".foo.bar.baz") => ".foo", ".bar", ".baz"

Returns A list of simple selectors in the compound selector.

Parameters:

Returns:



2872
2873
2874
2875
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2872

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.

Examples:

str-index(abcd, a)  => 1
str-index(abcd, ab) => 1
str-index(abcd, X)  => null
str-index(abcd, c)  => 3

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type



1612
1613
1614
1615
1616
1617
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1612

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.

Examples:

str-insert("abcd", "X", 1) => "Xabcd"
str-insert("abcd", "X", 4) => "abcXd"
str-insert("abcd", "X", 5) => "abcdX"

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type



1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1580

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.to_i > 0
                      [index.to_i - 1, original.value.size].min
                    else
                      [index.to_i, -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.

Examples:

str-length("foo") => 3

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$string` isn't a string



1554
1555
1556
1557
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1554

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.

Examples:

str-slice("abcd", 2, 3)   => "bc"
str-slice("abcd", 2)      => "bcd"
str-slice("abcd", -3, -2) => "bc"
str-slice("abcd", 2, -2)  => "bc"

Returns The substring. This will be quoted if and only if `$string` was quoted

Parameters:

  • $start-at (Sass::Script::Value::Number) —

    The index of the first character of the substring. If this is negative, it counts from the end of `$string`

  • $end-at (Sass::Script::Value::Number) —

    The index of the last character of the substring. If this is negative, it counts from the end of `$string`. Defaults to -1

Returns:

Raises:

  • (ArgumentError) —

    if any parameter is the wrong type



1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1642

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
  return Sass::Script::Value::String.new("", string.type) if e < 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,

Examples:

to-lower-case(ABCD) => abcd

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$string` isn't a string



1686
1687
1688
1689
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1686

def to_lower_case(string)
  assert_type string, :String, :string
  Sass::Script::Value::String.new(Sass::Util.downcase(string.value), string.type)
end

#to_upper_case($string) ⇒ Sass::Script::Value::String

Converts a string to upper case.

Examples:

to-upper-case(abcd) => ABCD

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$string` isn't a string



1671
1672
1673
1674
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1671

def to_upper_case(string)
  assert_type string, :String, :string
  Sass::Script::Value::String.new(Sass::Util.upcase(string.value), 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.

Examples:

transparentize(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.4)
transparentize(rgba(0, 0, 0, 0.8), 0.2) => rgba(0, 0, 0, 0.6)

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$amount` is out of bounds, or either parameter is the wrong type

See Also:



1045
1046
1047
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1045

def transparentize(color, amount)
  _adjust(color, amount, :alpha, 0..1, :-)
end

#type_of($value) ⇒ Sass::Script::Value::String

Returns the type of a value.

Examples:

type-of(100px)  => number
type-of(asdf)   => string
type-of("asdf") => string
type-of(true)   => bool
type-of(#fff)   => color
type-of(blue)   => color
type-of(null)   => null
type-of(a b c)  => list
type-of((a: 1, b: 2)) => map
type-of(get-function("foo")) => function

Parameters:

Returns:



1710
1711
1712
1713
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1710

def type_of(value)
  value.check_deprecated_interp if value.is_a?(Sass::Script::Value::String)
  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.

Returns:



2404
2405
2406
2407
2408
2409
2410
2411
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2404

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.

Examples:

unit(100) => ""
unit(100px) => "px"
unit(3em) => "em"
unit(10px * 5em) => "em*px"
unit(10px * 5em / 30cm / 1rem) => "em*px/cm*rem"

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1816
1817
1818
1819
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1816

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.

Examples:

unitless(100) => true
unitless(100px) => false

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$number` isn't a number



1831
1832
1833
1834
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1831

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.

Examples:

unquote("foo") => foo
unquote(foo) => foo

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if `$string` isn't a string

See Also:



1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 1500

def unquote(string)
  unless string.is_a?(Sass::Script::Value::String)
    # Don't warn multiple times for the same source line.
    # rubocop:disable GlobalVars
    $_sass_warned_for_unquote ||= Set.new
    frame = environment.stack.frames.last
    key = [frame.filename, frame.line] if frame
    return string if frame && $_sass_warned_for_unquote.include?(key)
    $_sass_warned_for_unquote << key if frame
    # rubocop:enable GlobalVars

    Sass::Util.sass_warn(<<MESSAGE.strip)
DEPRECATION WARNING: Passing #{string.to_sass}, a non-string value, to unquote()
will be an error in future versions of Sass.
#{environment.stack.to_s.gsub(/^/, ' ' * 8)}
MESSAGE
    return string
  end

  string.check_deprecated_interp
  return string if string.type == :identifier
  identifier(string.value)
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.

Examples:

$a-false-value: false;
variable-exists(a-false-value) => true
variable-exists(a-null-value) => true

variable-exists(nonexistent) => false

Parameters:

Returns:



2501
2502
2503
2504
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2501

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.

Examples:

zip(1px 1px 3px, solid dashed solid, red green blue)
=> 1px solid red, 1px dashed green, 3px solid blue

Parameters:

Returns:



2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
 
# File '.ruby-sass/lib/sass/script/functions.rb', line 2175

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