Module: Sass::Script::Functions

Defined in:: /var/www/sass-pages/.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 Sass::Script::Functions#hsl.

The following functions are provided:

Note: These functions are described in more detail below.

RGB Functions

rgb($red, $green, $blue): Converts an rgb(red, green, blue) triplet into a color.
rgba($red, $green, $blue, $alpha): Converts an rgba(red, green, blue, alpha) quadruplet into a color.
rgba($color, $alpha): Adds an alpha layer to any color value.
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($color-1, $color-2, [$weight]): Mixes two colors together.

HSL Functions

hsl($hue, $saturation, $lightness): Converts an hsl(hue, saturation, lightness) triplet into a color.
hsla($hue, $saturation, $lightness, $alpha): Converts an hsla(hue, saturation, lightness, alpha) quadruplet into a color.
hue($color): Gets the hue component of a color.
saturation($color): Gets the saturation component of a color.
lightness($color): Gets the lightness component of a color.
adjust-hue($color, $degrees): Changes the hue of a color.
lighten($color, $amount): Makes a color lighter.
darken($color, $amount): Makes a color darker.
saturate($color, $amount): Makes a color more saturated.
desaturate($color, $amount): Makes a color less saturated.
grayscale($color): Converts a color to grayscale.
complement($color): Returns the complement of a color.
invert($color): Returns the inverse of a color.

Opacity Functions

alpha($color) / opacity($color): Gets the alpha component (opacity) of a color.
rgba($color, $alpha): Add or change an alpha layer for any color value.
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]: Increase or decrease any of the components of a color.
scale-color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]: Fluidly scale one or more components of a color.
change-color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]: Changes one or more properties of a color.

String Functions

unquote($string): Removes the quotes from a string.
quote($string): Adds quotes to a string.

Number Functions

percentage($value): Converts a unitless number to a percentage.
round($value): Rounds a number to the nearest whole number.
ceil($value): Rounds a number up to the nearest whole number.
floor($value): Rounds a number down to the nearest whole number.
abs($value): Returns the absolute value of a number.

List Functions

length($list): Returns the length of a list.
nth($list, $n): Returns a specific item in a list.
join($list1, $list2, [$separator]): Joins together two lists into one.

Introspection Functions

type-of($value): Returns the type of a value.
unit($number): Returns the units associated with a number.
unitless($number): Returns whether a number has units or not.
comparable($number-1, $number-2): Returns whether two numbers can be added or compared.

Miscellaneous Functions

if($condition, $if-true, $if-false): Returns one of two values, depending on whether or not a condition is true.

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::String.new(string.value.reverse)
  end
  declare :reverse, :args => [: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 Sass::Script::Literal objects. Literal objects are also expected to be returned. This means that Ruby values must be unwrapped and wrapped.

Most Literal 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 Sass::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 Literal 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

+ declare(method_name, args, options = {}) Declare a Sass signature for a Ruby-defined function.
+ ({Symbol => Object}^?) signature(method_name, arg_arity, kwarg_arity) Determine the correct signature for the number of arguments passed in for a given function.

Instance Method Summary

- (Number) abs(value) Finds the absolute value of a number.
- (Color) adjust_color(color, kwargs) Adjusts one or more properties of a color.
- (Color) adjust_hue(color, degrees) Changes the hue of a color while retaining the lightness and saturation.
- alpha(color) Returns the alpha component (opacity) of a color.
- join(list, val, separator:auto) Appends a single value onto the end of a list.
- (Number) blue(color) Returns the blue component of a color.
- (Number) ceil(value) Rounds a number up to the nearest whole number.
- (Color) change_color(color, kwargs) Changes one or more properties of a color.
- (Bool) comparable(number_1, number_2) Returns true if two numbers are similar enough to be added, subtracted, or compared.
- (Color) complement(color) Returns the complement of a color.
- (Color) darken(color, amount) Makes a color darker.
- (Color) desaturate(color, amount) Makes a color less saturated.
- (Number) floor(value) Rounds down to the nearest whole number.
- grayscale(color)
- (Number) green(color) Returns the green component of a color.
- (Color) hsl(hue, saturation, lightness) Creates a Color object from hue, saturation, and lightness.
- (Color) hsla(hue, saturation, lightness, alpha) Creates a Color object from hue, saturation, and lightness, as well as an alpha channel indicating opacity.
- (Number) hue(color) Returns the hue component of a color.
- if(condition, if_true, if_false) Returns one of two values based on the truth value of the first argument.
- index(list, value) Returns the position of the given value within the given list.
- (Color) invert(color) Returns the inverse (negative) of a color.
- join(list1, list2, separator:auto) Joins together two lists into a new list.
- (Number) length(list) Return the length of a list.
- (Color) lighten(color, amount) Makes a color lighter.
- (Number) lightness(color) Returns the hue component of a color.
- (Color) mix(color1, color2, weight:50%) Mixes together two colors.
- (Literal) nth(list, n) Gets the nth item in a list.
- (Color) opacify(color, amount) (also: #fade_in) Makes a color more opaque.
- (Number) opacity(color) Returns the alpha component (opacity) of a color.
- (Number) percentage(value) Converts a decimal number to a percentage.
- (String) quote(string) Add quotes to a string if the string isn’t quoted, or returns the same string if it is.
- (Number) red(color) Returns the red component of a color.
- (Color) rgb(red, green, blue) Creates a Color object from red, green, and blue values.
- rgba(*args)
- (Number) round(value) Rounds a number to the nearest whole number.
- (Color) saturate(color, amount) Makes a color more saturated.
- (Number) saturation(color) Returns the saturation component of a color.
- (Color) scale_color(color, kwargs) Scales one or more properties of a color by a percentage value.
- (Color) transparentize(color, amount) (also: #fade_out) Makes a color more transparent.
- (String) type_of(value) Inspects the type of the argument, returning it as an unquoted string.
- (String) unit(number) Inspects the unit of the number, returning it as a quoted string.
- (Bool) unitless(number) Inspects the unit of the number, returning a boolean indicating if it is unitless.
- (String) unquote(string) Removes quotes from a string if the string is quoted, or returns the same string if it’s not.
- zip(*lists) Combines several lists into a single comma separated list space separated lists.

Class Method Details

+ declare(method_name, args, options = {})

Declare a Sass signature for a Ruby-defined function. This includes the names of the arguments, whether the function takes a variable number of arguments, and whether the function takes an arbitrary set of keyword arguments.

It’s not necessary to declare a signature for a function. However, without a signature it won’t support keyword arguments.

A single function can have multiple signatures declared as long as each one takes a different number of arguments. It’s also possible to declare multiple signatures that all take the same number of arguments, but none of them but the first will be used unless the user uses keyword arguments.

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:

(Symbol) method_name — The name of the method whose signature is being declared.
(Array<Symbol>) args — The names of the arguments for the function signature.

Options Hash (`options`):

(Boolean) :var_args — default: false —Whether the function accepts a variable number of (unnamed) arguments in addition to the named arguments.
(Boolean) :var_kwargs — 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 Sass::Script::Literals 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.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 250

def self.declare(method_name, args, options = {})
  @signatures[method_name] ||= []
  @signatures[method_name] << Signature.new(
    args.map {|s| s.to_s},
    options[:var_args],
    options[:var_kwargs])
end

+ ({Symbol => Object}^?) signature(method_name, arg_arity, kwarg_arity)

Determine the correct signature for the number of arguments passed in for a given function. If no signatures match, the first signature is returned for error messaging.

Parameters:

(Symbol) method_name — The name of the Ruby function to be called.
(Number) arg_arity — The number of unnamed arguments the function was passed.
(Number) kwarg_arity — 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.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 269

def self.signature(method_name, arg_arity, kwarg_arity)
  return unless @signatures[method_name]
  @signatures[method_name].each do |signature|
    return signature if signature.args.size == arg_arity + kwarg_arity
    next unless signature.args.size < 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 signature.args.size > 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 -= (signature.args.size - t_arg_arity)
      t_arg_arity = signature.args.size
    end

    if (  t_arg_arity == signature.args.size ||   t_arg_arity > signature.args.size && 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

- (Number) abs(value)

Finds the absolute value of a number.

Examples:

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

Parameters:

(Number) value — The number

Returns:

(Number) — The absolute value

Raises:

(ArgumentError) — if value isn’t a number



1182
1183
1184

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1182

def abs(value)
  numeric_transformation(value) {|n| n.abs}
end

- (Color) adjust_color(color, kwargs)

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

$red, $green, and $blue properties should be between 0 and 255. $saturation and $lightness should be between 0% and 100%. $alpha should be between 0 and 1.

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:

(Color) color
(Number) red
(Number) green
(Number) blue
(Number) hue
(Number) saturation
(Number) lightness
(Number) alpha

Returns:

(Color)

Raises:

(ArgumentError) — if color is not a color, if any keyword argument is not a number, if any keyword argument is not in the legal range, if an unexpected keyword argument is given, or if both HSL and RGB properties are given.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 758

def adjust_color(color, kwargs)
  assert_type 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)|

    next unless val = kwargs.delete(name)
    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

- (Color) adjust_hue(color, degrees)

Changes the hue of a color while retaining the lightness and saturation. Takes a color and a number of degrees (usually between -360deg and 360deg), and returns a color with the hue rotated by that value.

Examples:

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

Parameters:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 720

def adjust_hue(color, degrees)
  assert_type color, :Color
  assert_type degrees, :Number
  color.with(:hue => color.hue + degrees.value)
end

- alpha(color)

Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.

This function also supports the proprietary Microsoft alpha(opacity=20) syntax.

Parameters:

(Color) color

Returns:

(Number)

Raises:

(ArgumentError) — If color isn’t a color

Examples:

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

Parameters:

(Literal) list1 — The first list to join
(Literal) list2 — The second list to join
(String) separator — How the list separator (comma or space) should be determined. If this is comma or space, that is always the separator; if this is auto (the default), the separator is determined as explained above.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1282

def append(list, val, separator = Sass::Script::String.new("auto"))
  assert_type separator, :String
  unless %w[auto space comma].include?(separator.value)
    raise ArgumentError.new("Separator name must be space, comma, or auto")
  end
  sep = list.separator if list.is_a?(Sass::Script::List)
  Sass::Script::List.new(
    list.to_a + [val],
    if separator.value == 'auto'
      sep || :space
    else
      separator.value.to_sym
    end)
end

- (Number) blue(color)

Returns the blue component of a color.

Parameters:

(Color) color

Returns:

(Number)

Raises:

(ArgumentError) — If color isn’t a color

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 499

def blue(color)
  assert_type color, :Color
  Sass::Script::Number.new(color.blue)
end

- (Number) ceil(value)

Rounds a number up to the nearest whole number.

Examples:

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

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(ArgumentError) — if value isn’t a number



1156
1157
1158

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1156

def ceil(value)
  numeric_transformation(value) {|n| n.ceil}
end

- (Color) change_color(color, kwargs)

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.

$red, $green, and $blue properties should be between 0 and 255. $saturation and $lightness should be between 0% and 100%. $alpha should be between 0 and 1.

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:

(Color) color
(Number) red
(Number) green
(Number) blue
(Number) hue
(Number) saturation
(Number) lightness
(Number) alpha

Returns:

(Color)

Raises:

(ArgumentError) — if color is not a color, if any keyword argument is not a number, if any keyword argument is not in the legal range, if an unexpected keyword argument is given, or if both HSL and RGB properties are given.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 891

def change_color(color, kwargs)
  assert_type color, :Color
  with = Sass::Util.map_hash(%w[red green blue hue saturation lightness alpha]) do |name, max|
    next unless val = kwargs.delete(name)
    assert_type val, :Number, name
    [name.to_sym, val.value]
  end

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

  color.with(with)
end

- (Bool) comparable(number_1, number_2)

Returns true if two numbers are similar enough to be added, subtracted, or compared.

Examples:

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

Parameters:

(Number) number_1
(Number) number_2

Returns:

(Bool) — indicating if the numbers can be compared.

Raises:

(ArgumentError) — if number_1 or number_2 aren’t numbers

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1113

def comparable(number_1, number_2)
  assert_type number_1, :Number
  assert_type number_2, :Number
  Sass::Script::Bool.new(number_1.comparable_to?(number_2))
end

- (Color) complement(color)

Returns the complement of a color. This is identical to adjust-hue(color, 180deg).

Parameters:

(Color) color

Returns:

(Color)

Raises:

(ArgumentError) — if color isn’t a color

Examples:

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

Parameters:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0% and 100%

Examples:

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

Parameters:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0% and 100%

Examples:

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

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(ArgumentError) — if value isn’t a number



1169
1170
1171

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1169

def floor(value)
  numeric_transformation(value) {|n| n.floor}
end

- (Color) grayscale(color) - (Sass::Script::String) grayscale(number)

Overloads:

- (Color) grayscale(color)

Converts a color to grayscale. This is identical to desaturate(color, 100%).
Parameters:
- (Color) color
Returns:
- (Color)
Raises:
- (ArgumentError) — if color isn’t a color
See Also:
- #desaturate
- (Sass::Script::String) grayscale(number)

Returns an unquoted string grayscale(number), as though the function were not defined. This is for the grayscale function used in -webkit-filter.
Parameters:
- (Number) number
Returns:
- (Sass::Script::String)

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 987

def grayscale(color)
  return Sass::Script::String.new("grayscale(#{color})") if color.is_a?(Sass::Script::Number)
  desaturate color, Number.new(100)
end

- (Number) green(color)

Returns the green component of a color.

Parameters:

(Color) color

Returns:

(Number)

Raises:

(ArgumentError) — If color isn’t a color

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 488

def green(color)
  assert_type color, :Color
  Sass::Script::Number.new(color.green)
end

- (Color) hsl(hue, saturation, lightness)

Creates a Color object from hue, saturation, and lightness. Uses the algorithm from the CSS3 spec.

Parameters:

(Number) hue — The hue of the color. Should be between 0 and 360 degrees, inclusive
(Number) saturation — The saturation of the color. Must be between 0% and 100%, inclusive
(Number) lightness — The lightness of the color. Must be between 0% and 100%, inclusive

Returns:

(Color) — The resulting color

Raises:

(ArgumentError) — if saturation or lightness are out of bounds

Parameters:

(Number) hue — The hue of the color. Should be between 0 and 360 degrees, inclusive
(Number) saturation — The saturation of the color. Must be between 0% and 100%, inclusive
(Number) lightness — The lightness of the color. Must be between 0% and 100%, inclusive
(Number) alpha — The opacity of the color. Must be between 0 and 1, inclusive

Returns:

(Color) — The resulting color

Raises:

(ArgumentError) — if saturation, lightness, or alpha are out of bounds

Parameters:

(Color) color

Returns:

(Number) — between 0deg and 360deg

Raises:

(ArgumentError) — if color isn’t a color

Examples:

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

Parameters:

(Bool) condition — Whether the first or second value will be returned.
(Literal) if_true — The value that will be returned if $condition is true.
(Literal) if_false — The value that will be returned if $condition is false.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1350

def if(condition, if_true, if_false)
  if condition.to_bool
    if_true
  else
    if_false
  end
end

- index(list, value)

Returns the position of the given value within the given list. If not found, returns false.

Examples:

  index(1px solid red, solid) => 2
  index(1px solid red, dashed) => false

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1331

def index(list, value)
  assert_type list, :List
  index = list.value.index {|e| e.eq(value).to_bool }
  if index
    Number.new(index + 1)
  else
    Bool.new(false)
  end
end

- (Color) invert(color)

Returns the inverse (negative) of a color. The red, green, and blue values are inverted, while the opacity is left alone.

Parameters:

(Color) color

Returns:

(Color)

Raises:

(ArgumentError) — if color isn’t a color

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1011

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

- join(list1, list2, separator:auto)

Joins together two lists into a new list.

Unless the $separator argument 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 the lists have only one item each, spaces are used for the resulting list.

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

Parameters:

(Literal) list1 — The first list to join
(Literal) list2 — The second list to join
(String) separator — How the list separator (comma or space) should be determined. If this is comma or space, that is always the separator; if this is auto (the default), the separator is determined as explained above.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1246

def join(list1, list2, separator = Sass::Script::String.new("auto"))
  assert_type separator, :String
  unless %w[auto space comma].include?(separator.value)
    raise ArgumentError.new("Separator name must be space, comma, or auto")
  end
  sep1 = list1.separator if list1.is_a?(Sass::Script::List) && !list1.value.empty?
  sep2 = list2.separator if list2.is_a?(Sass::Script::List) && !list2.value.empty?
  Sass::Script::List.new(
    list1.to_a + list2.to_a,
    if separator.value == 'auto'
      sep1 || sep2 || :space
    else
      separator.value.to_sym
    end)
end

- (Number) length(list)

Return the length of a list.

Examples:

  length(10px) => 1
  length(10px 20px 30px) => 3

Parameters:

(Literal) list — The list

Returns:

(Number) — The length



1194
1195
1196

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1194

def length(list)
  Sass::Script::Number.new(list.to_a.size)
end

- (Color) lighten(color, amount)

Makes a color lighter. Takes a color and an amount between 0% and 100%, and returns a color with the lightness increased by that value.

Examples:

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

Parameters:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0% and 100%

Parameters:

(Color) color

Returns:

(Number) — between 0% and 100%

Raises:

(ArgumentError) — if color isn’t a color

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:

(Color) color1
(Color) color2
(Number) weight — between 0% and 100%

Returns:

(Color)

Raises:

(ArgumentError) — if color1 or color2 aren’t colors, or weight isn’t a number between 0% and 100%

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 931

def mix(color1, color2, weight = Number.new(50))
  assert_type color1, :Color
  assert_type color2, :Color
  assert_type weight, :Number

  Sass::Util.check_range("Weight", 0..100, weight, '%')

  # This algorithm factors in both the user-provided weight
  # and the difference between the alpha values of the two colors
  # 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 color 0",
  # 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

  rgb = color1.rgb.zip(color2.rgb).map {|v1, v2| v1*w1 + v2*w2}
  alpha = color1.alpha*p + color2.alpha*(1-p)
  Color.new(rgb + [alpha])
end

- (Literal) nth(list, n)

Gets the nth item in a list.

Note that unlike some languages, the first item in a Sass list is number 1, the second number 2, and so forth.

Examples:

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

Parameters:

(Literal) list — The list
(Number) n — The index into the list

Returns:

(Literal) — The nth item in the list

Raises:

(ArgumentError) — If n isn’t an integer between 1 and the list’s length.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1211

def nth(list, n)
  assert_type n, :Number
  if !n.int?
    raise ArgumentError.new("List index #{n} must be an integer")
  elsif n.to_i < 1
    raise ArgumentError.new("List index #{n} must be greater than or equal to 1")
  elsif list.to_a.size == 0
    raise ArgumentError.new("List index is #{n} but list has no items")
  elsif n.to_i > (size = list.to_a.size)
    raise ArgumentError.new("List index is #{n} but list is only #{size} item#{'s' if size != 1} long")
  end

  list.to_a[n.to_i - 1]
end

- (Color) opacify(color, amount) Also known as: fade_in

Makes a color more opaque. Takes a color and an amount between 0 and 1, and returns a color with the opacity increased by that value.

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:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0 and 1

Parameters:

(Color) color

Returns:

(Number)

Raises:

(ArgumentError) — If color isn’t a color

Examples:

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

Parameters:

(Number) value — The decimal number to convert to a percentage

Returns:

(Number) — The percentage

Raises:

(ArgumentError) — If value isn’t a unitless number

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1127

def percentage(value)
  unless value.is_a?(Sass::Script::Number) && value.unitless?
    raise ArgumentError.new("#{value.inspect} is not a unitless number")
  end
  Sass::Script::Number.new(value.value * 100, ['%'])
end

- (String) quote(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:

(String) string

Returns:

(String)

Raises:

(ArgumentError) — if string isn’t a string

Parameters:

(Color) color

Returns:

(Number)

Raises:

(ArgumentError) — If color isn’t a color

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 477

def red(color)
  assert_type color, :Color
  Sass::Script::Number.new(color.red)
end

- (Color) rgb(red, green, blue)

Creates a Color object from red, green, and blue values.

Parameters:

(Number) red — A number between 0 and 255 inclusive, or between 0% and 100% inclusive
(Number) green — A number between 0 and 255 inclusive, or between 0% and 100% inclusive
(Number) blue — A number between 0 and 255 inclusive, or between 0% and 100% inclusive

Returns:

(Color)

Overloads:

- (Color) rgba(red, green, blue, alpha)

Creates a Color object from red, green, and blue values, as well as an alpha channel indicating opacity.
Parameters:
- (Number) red — A number between 0 and 255 inclusive
- (Number) green — A number between 0 and 255 inclusive
- (Number) blue — A number between 0 and 255 inclusive
- (Number) alpha — A number between 0 and 1
Returns:
- (Color)
- (Color) rgba(color, alpha)

Sets the opacity of a color.
Examples:
```
  rgba(#102030, 0.5) => rgba(16, 32, 48, 0.5)
  rgba(blue, 0.2)    => rgba(0, 0, 255, 0.2)
```
Parameters:
- (Color) color
- (Number) alpha — A number between 0 and 1
Returns:
- (Color)

Examples:

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

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(ArgumentError) — if value isn’t a number



1143
1144
1145

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1143

def round(value)
  numeric_transformation(value) {|n| n.round}
end

- (Color) saturate(color, amount)

Makes a color more saturated. Takes a color and an amount between 0% and 100%, and returns a color with the saturation increased by that value.

Examples:

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

Parameters:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0% and 100%

Parameters:

(Color) color

Returns:

(Number) — between 0% and 100%

Raises:

(ArgumentError) — if color isn’t a color

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:

(Color) color
(Number) red
(Number) green
(Number) blue
(Number) saturation
(Number) lightness
(Number) alpha

Returns:

(Color)

Raises:

(ArgumentError) — if color is not a color, if any keyword argument is not a percentage between 0% and 100%, if an unexpected keyword argument is given, or if both HSL and RGB properties are given.

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 826

def scale_color(color, kwargs)
  assert_type color, :Color
  with = Sass::Util.map_hash({
      "red" => 255,
      "green" => 255,
      "blue" => 255,
      "saturation" => 100,
      "lightness" => 100,
      "alpha" => 1
    }) do |name, max|

    next unless val = kwargs.delete(name)
    assert_type val, :Number, name
    if !(val.numerator_units == ['%'] && val.denominator_units.empty?)
      raise ArgumentError.new("$#{name}: Amount #{val} must be a % (e.g. #{val.value}%)")
    else
      Sass::Util.check_range("$#{name}: Amount", -100..100, val, '%')
    end

    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

- (Color) transparentize(color, amount) Also known as: fade_out

Makes a color more transparent. Takes a color and an amount between 0 and 1, and returns a color with the opacity decreased by that value.

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:

(Color) color
(Number) amount

Returns:

(Color)

Raises:

(ArgumentError) — If color isn’t a color, or number isn’t a number between 0 and 1

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

Parameters:

(Literal) value — The object to inspect

Returns:

(String) — The unquoted string name of the literal’s type



1066
1067
1068

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1066

def type_of(value)
  Sass::Script::String.new(value.class.name.gsub(/Sass::Script::/,'').downcase)
end

- (String) unit(number)

Inspects the unit of the number, returning it as a quoted string. 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:

(Literal) number — The number to inspect

Returns:

(String) — The unit(s) of the number

Raises:

(ArgumentError) — if number isn’t a number

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1083

def unit(number)
  assert_type number, :Number
  Sass::Script::String.new(number.unit_str, :string)
end

- (Bool) unitless(number)

Inspects the unit of the number, returning a boolean indicating if it is unitless.

Examples:

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

Parameters:

(Literal) number — The number to inspect

Returns:

(Bool) — Whether or not the number is unitless

Raises:

(ArgumentError) — if number isn’t a number

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1097

def unitless(number)
  assert_type number, :Number
  Sass::Script::Bool.new(number.unitless?)
end

- (String) unquote(string)

Removes quotes from a string if the string is quoted, or returns the same string if it’s not.

Examples:

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

Parameters:

(String) string

Returns:

(String)

Raises:

(ArgumentError) — if string isn’t a string

Examples:

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

# File '/var/www/sass-pages/.sass/lib/sass/script/functions.rb', line 1308

def zip(*lists)
  length = nil
  values = []
  lists.each do |list|
    assert_type list, :List
    values << list.value.dup
    length = length.nil? ? list.value.length : [length, list.value.length].min
  end
  values.each do |value|
    value.slice!(length)
  end
  new_list_value = values.first.zip(*values[1..-1])
  List.new(new_list_value.map{|list| List.new(list, :space)}, :comma)
end

Module: Sass::Script::Functions

Overview

RGB Functions

HSL Functions

Opacity Functions

Other Color Functions

String Functions

Number Functions

List Functions

Introspection Functions

Miscellaneous Functions

Adding Custom Functions

Caveats

Defined Under Namespace

Class Method Summary

Instance Method Summary

Class Method Details

Examples:

Parameters:

Options Hash (options):

Parameters:

Returns:

Instance Method Details

Examples:

Parameters:

Returns:

Raises:

Examples:

Parameters:

Returns:

Raises:

Examples:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

See Also:

Examples:

Parameters:

Parameters:

Returns:

Raises:

Examples:

Parameters:

Returns:

Raises:

Examples:

Parameters:

Returns:

Raises:

Examples:

Parameters:

Returns:

Raises:

Parameters:

Returns:

Raises:

See Also:

Examples:

Parameters:

Returns:

Raises:

See Also:

Examples:

Parameters:

Returns:

Raises:

See Also:

Examples:

Parameters:

Returns:

Raises:

Overloads:

Parameters:

Returns:

Raises:

See Also:

Parameters:

Options Hash (`options`):