Module: Sass::Script::Functions

Included in:
EvaluationContext
Defined in:
lib/sass/script/functions.rb

Overview

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

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

and it will call #hsl.

The following functions are provided:

Note: These functions are described in more detail below.

RGB Functions

rgb($red, $green, $blue) : Creates a Color from red, green, and blue values.

rgba($red, $green, $blue, $alpha) : Creates a Color from red, green, blue, and alpha values.

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

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

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

mix($color-1, $color-2, [$weight]) : Mixes two colors together.

HSL Functions

hsl($hue, $saturation, $lightness) : Creates a Color from hue, saturation, and lightness values.

hsla($hue, $saturation, $lightness, $alpha) : Creates a Color from hue, saturation, lightness, and alpha values.

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

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

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

adjust-hue($color, $degrees) : Changes the hue of a color.

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

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

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

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

grayscale($color) : Converts a color to grayscale.

complement($color) : Returns the complement of a color.

invert($color) : Returns the inverse of a color.

Opacity Functions

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

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

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

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

Other Color Functions

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

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

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

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

String Functions

unquote($string) : Removes quotes from a string.

quote($string) : Adds quotes to a string.

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 next whole number.

floor($value) : Rounds a number down to the previous whole number.

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

min($numbers...) : Finds the minimum of several numbers.

max($numbers...) : Finds the maximum of several numbers.

List Functions #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.

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.

Introspection Functions

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($number-1, $number-2) : Returns whether two numbers can be added, subtracted, or compared.

Miscellaneous Functions

if($condition, $if-true, $if-false) : Returns one of two values, depending on whether or not $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 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 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 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 collapse

Instance Method Summary collapse

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:

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



267
268
269
270
271
272
273
 
# File 'lib/sass/script/functions.rb', line 267

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

.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 (Number) —

    The number of unnamed arguments the function was passed.

  • kwarg_arity (Number) —

    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.



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/sass/script/functions.rb', line 286

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

#abs($value) ⇒ Number

Returns the absolute value of a number.

Examples:

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if $value isn't a number



1260
1261
1262
 
# File 'lib/sass/script/functions.rb', line 1260

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

#adjust_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ 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:

  • $color (Color)
  • $red (Number) —

    The adjustment to make on the red component, between -255 and 255 inclusive

  • $green (Number) —

    The adjustment to make on the green component, between -255 and 255 inclusive

  • $blue (Number) —

    The adjustment to make on the blue component, between -255 and 255 inclusive

  • $hue (Number) —

    The adjustment to make on the hue component, in degrees

  • $saturation (Number) —

    The adjustment to make on the saturation component, between -100% and 100% inclusive

  • $lightness (Number) —

    The adjustment to make on the lightness component, between -100% and 100% inclusive

  • $alpha (Number) —

    The adjustment to make on the alpha component, between -1 and 1 inclusive

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



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
 
# File 'lib/sass/script/functions.rb', line 828

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

    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

#adjust_hue($color, $degrees) ⇒ 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%), 060deg) => hsl(60, 30%, 90%)
adjust-hue(#811, 45deg) => #886a11

Parameters:

  • $color (Color)
  • $degrees (Number) —

    The number of degrees to rotate the hue

Returns:

Raises:

  • (ArgumentError) —

    if either parameter is the wrong type



771
772
773
774
775
 
# File 'lib/sass/script/functions.rb', line 771

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) ⇒ 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:

  • (Number) —

    The alpha component, between 0 and 1

Raises:

  • (ArgumentError) —

    if $color isn't a color



604
605
606
607
608
609
610
611
612
613
614
615
616
617
 
# File 'lib/sass/script/functions.rb', line 604

def alpha(*args)
  if args.all? do |a|
      a.is_a?(Sass::Script::String) && a.type == :identifier &&
        a.value =~ /^[a-zA-Z]+\s*=/
    end
    # Support the proprietary MS alpha() function
    return Sass::Script::String.new("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
  Sass::Script::Number.new(args.first.alpha)
end

#append($list, $val, $separator: auto) ⇒ 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.

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:

  • $list (Literal)
  • $val (Literal)
  • $separator (String) —

    The list separator to use. If this is comma or space, that separator will be used. If this is auto (the default), the separator is determined as explained above.

Returns:



1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
 
# File 'lib/sass/script/functions.rb', line 1398

def append(list, val, separator = Sass::Script::String.new("auto"))
  assert_type separator, :String, :separator
  unless %w[auto space comma].include?(separator.value)
    raise ArgumentError.new("Separator name must be space, comma, or auto")
  end
  sep = 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

#blue($color) ⇒ Number

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

Parameters:

Returns:

  • (Number) —

    The blue component, between 0 and 255 inclusive

Raises:

  • (ArgumentError) —

    if $color isn't a color



537
538
539
540
 
# File 'lib/sass/script/functions.rb', line 537

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

#ceil($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 $value isn't a number



1232
1233
1234
 
# File 'lib/sass/script/functions.rb', line 1232

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

#change_color($color, [$red], [$green], [$blue], [$hue], [$saturation], [$lightness], [$alpha]) ⇒ 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:

  • $color (Color)
  • $red (Number) —

    The new red component for the color, within 0 and 255 inclusive

  • $green (Number) —

    The new green component for the color, within 0 and 255 inclusive

  • $blue (Number) —

    The new blue component for the color, within 0 and 255 inclusive

  • $hue (Number) —

    The new hue component for the color, in degrees

  • $saturation (Number) —

    The new saturation component for the color, between 0% and 100% inclusive

  • $lightness (Number) —

    The new lightness component for the color, within 0% and 100% inclusive

  • $alpha (Number) —

    The new alpha component for the color, within 0 and 1 inclusive

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



962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
 
# File 'lib/sass/script/functions.rb', line 962

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

#comparable($number-1, $number-2) ⇒ 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



1185
1186
1187
1188
1189
 
# File 'lib/sass/script/functions.rb', line 1185

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

#complement($color) ⇒ 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:



1063
1064
1065
 
# File 'lib/sass/script/functions.rb', line 1063

def complement(color)
  adjust_hue color, Number.new(180)
end

#counter($args...) ⇒ String

This function only exists as a workaround for IE7's content: counter bug. It works identically to any other plain-CSS function, except it avoids adding spaces between the argument commas.

Examples:

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

Returns:



1501
1502
1503
 
# File 'lib/sass/script/functions.rb', line 1501

def counter(*args)
  Sass::Script::String.new("counter(#{args.map {|a| a.to_s(options)}.join(',')})")
end

#counters($args...) ⇒ String

This function only exists as a workaround for IE7's content: counters 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:



1516
1517
1518
 
# File 'lib/sass/script/functions.rb', line 1516

def counters(*args)
  Sass::Script::String.new("counters(#{args.map {|a| a.to_s(options)}.join(',')})")
end

#darken($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to dencrease the lightness by, between 0% and 100%

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



711
712
713
 
# File 'lib/sass/script/functions.rb', line 711

def darken(color, amount)
  _adjust(color, amount, :lightness, 0..100, :-, "%")
end

#desaturate($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to decrease the saturation by, between 0% and 100%

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



753
754
755
 
# File 'lib/sass/script/functions.rb', line 753

def desaturate(color, amount)
  _adjust(color, amount, :saturation, 0..100, :-, "%")
end

#floor($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 $value isn't a number



1246
1247
1248
 
# File 'lib/sass/script/functions.rb', line 1246

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

#grayscale($color) ⇒ 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:



1049
1050
1051
1052
 
# File 'lib/sass/script/functions.rb', line 1049

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

#green($color) ⇒ Number

Gets the green component of a color. Calculated from HSL where necessary via this algorithm.

Parameters:

Returns:

  • (Number) —

    The green component, between 0 and 255 inclusive

Raises:

  • (ArgumentError) —

    if $color isn't a color



522
523
524
525
 
# File 'lib/sass/script/functions.rb', line 522

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

#hsl($hue, $saturation, $lightness) ⇒ Color

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

Parameters:

  • $hue (Number) —

    The hue of the color. Should be between 0 and 360 degrees, inclusive

  • $saturation (Number) —

    The saturation of the color. Must be between 0% and 100%, inclusive

  • $lightness (Number) —

    The lightness of the color. Must be between 0% and 100%, inclusive

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



459
460
461
 
# File 'lib/sass/script/functions.rb', line 459

def hsl(hue, saturation, lightness)
  hsla(hue, saturation, lightness, Number.new(1))
end

#hsla($hue, $saturation, $lightness, $alpha) ⇒ Color

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

Parameters:

  • $hue (Number) —

    The hue of the color. Should be between 0 and 360 degrees, inclusive

  • $saturation (Number) —

    The saturation of the color. Must be between 0% and 100%, inclusive

  • $lightness (Number) —

    The lightness of the color. Must be between 0% and 100%, inclusive

  • $alpha (Number) —

    The opacity of the color. Must be between 0 and 1, inclusive

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



482
483
484
485
486
487
488
489
490
491
492
493
494
495
 
# File 'lib/sass/script/functions.rb', line 482

def hsla(hue, saturation, lightness, alpha)
  assert_type hue, :Number, :hue
  assert_type saturation, :Number, :saturation
  assert_type lightness, :Number, :lightness
  assert_type alpha, :Number, :alpha

  Sass::Util.check_range('Alpha channel', 0..1, alpha)

  h = hue.value
  s = Sass::Util.check_range('Saturation', 0..100, saturation, '%')
  l = Sass::Util.check_range('Lightness', 0..100, lightness, '%')

  Color.new(:hue => h, :saturation => s, :lightness => l, :alpha => alpha.value)
end

#hue($color) ⇒ Number

Returns the hue component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

Parameters:

Returns:

  • (Number) —

    The hue component, between 0deg and 360deg

Raises:

  • (ArgumentError) —

    if $color isn't a color



554
555
556
557
 
# File 'lib/sass/script/functions.rb', line 554

def hue(color)
  assert_type color, :Color, :color
  Sass::Script::Number.new(color.hue, ["deg"])
end

#ie_hex_str($color) ⇒ 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:

  • (String) —

    The IE-formatted string representation of the color

Raises:

  • (ArgumentError) —

    if $color isn't a color



788
789
790
791
792
 
# File 'lib/sass/script/functions.rb', line 788

def ie_hex_str(color)
  assert_type color, :Color, :color
  alpha = (color.alpha * 255).round.to_s(16).rjust(2, '0')
  Sass::Script::String.new("##{alpha}#{color.send(:hex_str)[1..-1]}".upcase)
end

#if($condition, $if-true, $if-false) ⇒ Literal

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:

  • $condition (Literal) —

    Whether the $if-true or $if-false will be returned

  • $if-true (Literal)
  • $if-false (Literal)

Returns:

  • (Literal) —

    $if-true or $if-false



1482
1483
1484
1485
1486
1487
1488
 
# File 'lib/sass/script/functions.rb', line 1482

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

#index($list, $value) ⇒ Number, Bool

Returns the position of a value within a list. If the value isn't found, returns false instead.

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

Examples:

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

Parameters:

Returns:

  • (Number, Bool) —

    The 1-based index of $value in $list, or false



1459
1460
1461
1462
1463
1464
1465
1466
 
# File 'lib/sass/script/functions.rb', line 1459

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

#invert($color) ⇒ Color

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if $color isn't a color



1075
1076
1077
1078
1079
1080
1081
1082
1083
 
# File 'lib/sass/script/functions.rb', line 1075

def invert(color)
  return Sass::Script::String.new("invert(#{color})") if color.is_a?(Sass::Script::Number)

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

#join($list1, $list2, $separator: auto) ⇒ 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.

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:

  • $list1 (Literal)
  • $list2 (Literal)
  • $separator (String) —

    The list separator to use. If this is comma or space, that separator will be used. If this is auto (the default), the separator is determined as explained above.

Returns:



1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
 
# File 'lib/sass/script/functions.rb', line 1362

def join(list1, list2, separator = Sass::Script::String.new("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
  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

#length($list) ⇒ Number

Return the length of a list.

Examples:

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

Parameters:

Returns:



1307
1308
1309
 
# File 'lib/sass/script/functions.rb', line 1307

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

#lighten($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to increase the lightness by, between 0% and 100%

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



692
693
694
 
# File 'lib/sass/script/functions.rb', line 692

def lighten(color, amount)
  _adjust(color, amount, :lightness, 0..100, :+, "%")
end

#lightness($color) ⇒ Number

Returns the lightness component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

Parameters:

Returns:

  • (Number) —

    The lightness component, between 0% and 100%

Raises:

  • (ArgumentError) —

    if $color isn't a color



588
589
590
591
 
# File 'lib/sass/script/functions.rb', line 588

def lightness(color)
  assert_type color, :Color, :color
  Sass::Script::Number.new(color.lightness, ["%"])
end

#max($numbers...) ⇒ 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



1293
1294
1295
1296
 
# File 'lib/sass/script/functions.rb', line 1293

def max(*values)
  values.each {|v| assert_type v, :Number}
  values.inject {|max, val| max.gt(val).to_bool ? max : val}
end

#min($numbers...) ⇒ 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



1276
1277
1278
1279
 
# File 'lib/sass/script/functions.rb', line 1276

def min(*numbers)
  numbers.each {|n| assert_type n, :Number}
  numbers.inject {|min, num| min.lt(num).to_bool ? min : num}
end

#mix($color-1, $color-2, $weight: 50%) ⇒ 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:

  • $color-1 (Color)
  • $color-2 (Color)
  • $weight (Number) —

    The relative weight of each color. Closer to 0% gives more weight to $color, closer to 100% gives more weight to $color2

Returns:

Raises:

  • (ArgumentError) —

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



1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
 
# File 'lib/sass/script/functions.rb', line 1001

def mix(color_1, color_2, weight = Number.new(50))
  assert_type color_1, :Color, :color_1
  assert_type color_2, :Color, :color_2
  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 color_1", -1 indicates "only use color_2", 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 color_1.
  # 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 color_1 is renormalized to be within [0, 1]
  # and the weight of color_2 is given by 1 minus the weight of color_1.
  p = (weight.value/100.0).to_f
  w = p*2 - 1
  a = color_1.alpha - color_2.alpha

  w1 = (((w * a == -1) ? w : (w + a)/(1 + w*a)) + 1)/2.0
  w2 = 1 - w1

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

#nth($list, $n) ⇒ Literal

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:

Returns:

Raises:

  • (ArgumentError) —

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



1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
 
# File 'lib/sass/script/functions.rb', line 1326

def nth(list, n)
  assert_type n, :Number, :n
  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

#opacify($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to increase the opacity by, between 0 and 1

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



648
649
650
 
# File 'lib/sass/script/functions.rb', line 648

def opacify(color, amount)
  _adjust(color, amount, :alpha, 0..1, :+)
end

#opacity($color) ⇒ Number

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

Parameters:

Returns:

  • (Number) —

    The alpha component, between 0 and 1

Raises:

  • (ArgumentError) —

    if $color isn't a color



627
628
629
630
631
 
# File 'lib/sass/script/functions.rb', line 627

def opacity(color)
  return Sass::Script::String.new("opacity(#{color})") if color.is_a?(Sass::Script::Number)
  assert_type color, :Color, :color
  Sass::Script::Number.new(color.alpha)
end

#percentage($value) ⇒ Number

Converts a unitless number to a percentage.

Examples:

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if $value isn't a unitless number



1201
1202
1203
1204
1205
1206
 
# File 'lib/sass/script/functions.rb', line 1201

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

#quote($string) ⇒ 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:



1117
1118
1119
1120
 
# File 'lib/sass/script/functions.rb', line 1117

def quote(string)
  assert_type string, :String, :string
  Sass::Script::String.new(string.value, :string)
end

#red($color) ⇒ Number

Gets the red component of a color. Calculated from HSL where necessary via this algorithm.

Parameters:

Returns:

  • (Number) —

    The red component, between 0 and 255 inclusive

Raises:

  • (ArgumentError) —

    if $color isn't a color



507
508
509
510
 
# File 'lib/sass/script/functions.rb', line 507

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

#rgb($red, $green, $blue) ⇒ Color

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

Parameters:

  • $red (Number) —

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

  • $green (Number) —

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

  • $blue (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:



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/sass/script/functions.rb', line 377

def rgb(red, green, blue)
  assert_type red, :Number, :red
  assert_type green, :Number, :green
  assert_type blue, :Number, :blue

  Color.new([[red, :red], [green, :green], [blue, :blue]].map do |(c, name)|
      v = c.value
      if c.numerator_units == ["%"] && c.denominator_units.empty?
        v = Sass::Util.check_range("$#{name}: Color value", 0..100, c, '%')
        v * 255 / 100.0
      else
        Sass::Util.check_range("$#{name}: Color value", 0..255, c)
      end
    end)
end

#rgba($red, $green, $blue, $alpha) ⇒ Color #rgba($color, $alpha) ⇒ Color

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

Overloads:

  • #rgba($red, $green, $blue, $alpha) ⇒ Color

    Parameters:

    • $red (Number) —

      The amount of red in the color. Must be between 0 and 255 inclusive

    • $green (Number) —

      The amount of green in the color. Must be between 0 and 255 inclusive

    • $blue (Number) —

      The amount of blue in the color. Must be between 0 and 255 inclusive

    • $alpha (Number) —

      The opacity of the color. Must be between 0 and 1 inclusive

    Returns:

    Raises:

    • (ArgumentError) —

      if any parameter is the wrong type or out of bounds

  • #rgba($color, $alpha) ⇒ Color

    Sets the opacity of an existing 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) —

      The color whose opacity will be changed.

    • $alpha (Number) —

      The new opacity of the color. Must be between 0 and 1 inclusive

    Returns:

    Raises:

    • (ArgumentError) —

      if $alpha is out of bounds or either parameter is the wrong type

See Also:



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/sass/script/functions.rb', line 423

def rgba(*args)
  case args.size
  when 2
    color, alpha = args

    assert_type color, :Color, :color
    assert_type alpha, :Number, :alpha

    Sass::Util.check_range('Alpha channel', 0..1, alpha)
    color.with(:alpha => alpha.value)
  when 4
    red, green, blue, alpha = args
    rgba(rgb(red, green, blue), alpha)
  else
    raise ArgumentError.new("wrong number of arguments (#{args.size} for 4)")
  end
end

#round($value) ⇒ Number

Rounds a number to the nearest whole number.

Examples:

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if $value isn't a number



1218
1219
1220
 
# File 'lib/sass/script/functions.rb', line 1218

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

#saturate($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to increase the saturation by, between 0% and 100%

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



730
731
732
733
734
735
 
# File 'lib/sass/script/functions.rb', line 730

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 Sass::Script::String.new("saturate(#{color})") if amount.nil?
  _adjust(color, amount, :saturation, 0..100, :+, "%")
end

#saturation($color) ⇒ Number

Returns the saturation component of a color. See the CSS3 HSL specification. Calculated from RGB where necessary via this algorithm.

Parameters:

Returns:

  • (Number) —

    The saturation component, between 0% and 100%

Raises:

  • (ArgumentError) —

    if $color isn't a color



571
572
573
574
 
# File 'lib/sass/script/functions.rb', line 571

def saturation(color)
  assert_type color, :Color, :color
  Sass::Script::Number.new(color.saturation, ["%"])
end

#scale_color($color, [$red], [$green], [$blue], [$saturation], [$lightness], [$alpha]) ⇒ 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



896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
 
# File 'lib/sass/script/functions.rb', line 896

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|

    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

#transparentize($color, $amount) ⇒ 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:

  • $color (Color)
  • $amount (Number) —

    The amount to decrease the opacity by, between 0 and 1

Returns:

Raises:

  • (ArgumentError) —

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

See Also:



670
671
672
 
# File 'lib/sass/script/functions.rb', line 670

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

#type_of($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

Parameters:

  • $value (Literal) —

    The value to inspect

Returns:

  • (String) —

    The unquoted string name of the value's type



1135
1136
1137
 
# File 'lib/sass/script/functions.rb', line 1135

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

#unit($number) ⇒ 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:

  • (String) —

    The unit(s) of the number, as a quoted string

Raises:

  • (ArgumentError) —

    if $number isn't a number



1153
1154
1155
1156
 
# File 'lib/sass/script/functions.rb', line 1153

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

#unitless($number) ⇒ Bool

Returns whether a number has units.

Examples:

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

Parameters:

Returns:

Raises:

  • (ArgumentError) —

    if $number isn't a number



1168
1169
1170
1171
 
# File 'lib/sass/script/functions.rb', line 1168

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

#unquote($string) ⇒ 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:



1097
1098
1099
1100
1101
1102
1103
 
# File 'lib/sass/script/functions.rb', line 1097

def unquote(string)
  if string.is_a?(Sass::Script::String)
    Sass::Script::String.new(string.value, :identifier)
  else
    string
  end
end

#zip($lists...) ⇒ 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:



1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
 
# File 'lib/sass/script/functions.rb', line 1428

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(new_list_value.map{|list| List.new(list, :space)}, :comma)
end