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(120, 100%, 50%)

and it will call #hsl.

The following functions are provided:

#hsl : Converts an hsl(hue, saturation, lightness) triplet into a color.

#percentage : Converts a unitless number to a percentage.

#round : Rounds a number to the nearest whole number.

#ceil : Rounds a number up to the nearest whole number.

#floor : Rounds a number down to the nearest whole number.

#abs : Returns the absolute value of a number.

You can add your own functions to this module, but there are a few things to keep in mind. First of all, the arguments passed are Literal objects. Literal objects are also expected to be returned.

Second, making Ruby functions accessible from Sass introduces the temptation to do things like database access within stylesheets. This temptation must be resisted. Keep in mind that Sass stylesheets are only compiled once at a somewhat indeterminate time and then left as static CSS files. Any dynamic CSS should be left in <style> tags in the HTML.

Within one of the functions in this module, methods of EvaluationContext can be used.

Defined Under Namespace

Classes: EvaluationContext

Instance Method Summary collapse

Instance Method Details

#abs(value) ⇒ Number

Finds the absolute value of a number. For example:

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

Parameters:

  • value (Number) —

    The number

Returns:

  • (Number) —

    The absolute value

Raises:



173
174
175
 
# File 'lib/sass/script/functions.rb', line 173

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

#ceil(value) ⇒ Number

Rounds a number up to the nearest whole number. For example:

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

Parameters:

  • value (Number) —

    The number

Returns:

  • (Number) —

    The rounded number

Raises:



147
148
149
 
# File 'lib/sass/script/functions.rb', line 147

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

#floor(value) ⇒ Number

Rounds down to the nearest whole number. For example:

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

Parameters:

  • value (Number) —

    The number

Returns:

  • (Number) —

    The rounded number

Raises:



160
161
162
 
# File 'lib/sass/script/functions.rb', line 160

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

#hsl(hue, saturation, lightness) ⇒ Color

Creates a Color object from hue, saturation, and lightness as per the CSS3 spec (http://www.w3.org/TR/css3-color/#hsl-color).

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:

  • (Color) —

    The resulting color

Raises:

  • (ArgumentError) —

    if saturation or lightness are out of bounds



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/sass/script/functions.rb', line 91

def hsl(hue, saturation, lightness)
  original_s = saturation
  original_l = lightness
  # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color
  h, s, l = [hue, saturation, lightness].map { |a| a.value }
  raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100
  raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100

  h = (h % 360) / 360.0
  s /= 100.0
  l /= 100.0

  m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
  m1 = l * 2 - m2
  Color.new([hue_to_rgb(m1, m2, h + 1.0/3),
             hue_to_rgb(m1, m2, h),
             hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round })
end

#percentage(value) ⇒ Number

Converts a decimal number to a percentage. For example:

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

Parameters:

  • value (Number) —

    The decimal number to convert to a percentage

Returns:

Raises:

  • (ArgumentError) —

    If value isn't a unitless number



118
119
120
121
122
123
 
# File 'lib/sass/script/functions.rb', line 118

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

#rgb(red, green, blue) ⇒ Object

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

Parameters:

  • red —

    A number between 0 and 255 inclusive

  • green —

    A number between 0 and 255 inclusive

  • blue —

    A number between 0 and 255 inclusive



72
73
74
75
76
77
78
 
# File 'lib/sass/script/functions.rb', line 72

def rgb(red, green, blue)
  [red.value, green.value, blue.value].each do |v|
    next unless v < 0 || v > 255
    raise ArgumentError.new("Color value #{v} must be between 0 and 255 inclusive")
  end
  Color.new([red.value, green.value, blue.value])
end

#round(value) ⇒ Number

Rounds a number to the nearest whole number. For example:

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

Parameters:

  • value (Number) —

    The number

Returns:

  • (Number) —

    The rounded number

Raises:



134
135
136
 
# File 'lib/sass/script/functions.rb', line 134

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