| Module | Sass::Script::Functions |
| In: |
lib/sass/script/functions.rb
|
Methods in this module are accessible from the SassScript context. For example, you can write
!color = hsl(120, 100%, 50%)
and it will call {Sass::Script::Functions#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 {Sass::Script::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.
Finds the absolute value of a number. For example:
abs(10px) => 10px
abs(-10px) => 10px
@param value [Number] The number @return [Number] The absolute value @raise [Sass::SyntaxError] if `value` isn‘t a number
# File lib/sass/script/functions.rb, line 173
173: def abs(value)
174: numeric_transformation(value) {|n| n.abs}
175: end
Rounds a number up to the nearest whole number. For example:
ciel(10.4px) => 11px
ciel(10.6px) => 11px
@param value [Number] The number @return [Number] The rounded number @raise [Sass::SyntaxError] if `value` isn‘t a number
# File lib/sass/script/functions.rb, line 147
147: def ceil(value)
148: numeric_transformation(value) {|n| n.ceil}
149: end
Rounds down to the nearest whole number. For example:
floor(10.4px) => 10px
floor(10.6px) => 10px
@param value [Number] The number @return [Number] The rounded number @raise [Sass::SyntaxError] if `value` isn‘t a number
# File lib/sass/script/functions.rb, line 160
160: def floor(value)
161: numeric_transformation(value) {|n| n.floor}
162: end
Creates a {Color} object from hue, saturation, and lightness as per the CSS3 spec (www.w3.org/TR/css3-color/#hsl-color).
@param hue [Number] The hue of the color.
Should be between 0 and 360 degrees, inclusive
@param saturation [Number] The saturation of the color.
Must be between `0%` and `100%`, inclusive
@param lightness [Number] The lightness of the color.
Must be between `0%` and `100%`, inclusive
@return [Color] The resulting color @raise [ArgumentError] if `saturation` or `lightness` are out of bounds
# File lib/sass/script/functions.rb, line 91
91: def hsl(hue, saturation, lightness)
92: original_s = saturation
93: original_l = lightness
94: # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color
95: h, s, l = [hue, saturation, lightness].map { |a| a.value }
96: raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100
97: raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100
98:
99: h = (h % 360) / 360.0
100: s /= 100.0
101: l /= 100.0
102:
103: m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
104: m1 = l * 2 - m2
105: Color.new([hue_to_rgb(m1, m2, h + 1.0/3),
106: hue_to_rgb(m1, m2, h),
107: hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round })
108: end
Converts a decimal number to a percentage. For example:
percentage(100px / 50px) => 200%
@param value [Number] The decimal number to convert to a percentage @return [Number] The percentage @raise [ArgumentError] If `value` isn‘t a unitless number
# File lib/sass/script/functions.rb, line 118
118: def percentage(value)
119: unless value.is_a?(Sass::Script::Number) && value.unitless?
120: raise ArgumentError.new("#{value} is not a unitless number")
121: end
122: Sass::Script::Number.new(value.value * 100, ['%'])
123: end
Creates a {Color} object from red, green, and blue values. @param red
A number between 0 and 255 inclusive
@param green
A number between 0 and 255 inclusive
@param blue
A number between 0 and 255 inclusive
# File lib/sass/script/functions.rb, line 72
72: def rgb(red, green, blue)
73: [red.value, green.value, blue.value].each do |v|
74: next unless v < 0 || v > 255
75: raise ArgumentError.new("Color value #{v} must be between 0 and 255 inclusive")
76: end
77: Color.new([red.value, green.value, blue.value])
78: end
Rounds a number to the nearest whole number. For example:
round(10.4px) => 10px
round(10.6px) => 11px
@param value [Number] The number @return [Number] The rounded number @raise [Sass::SyntaxError] if `value` isn‘t a number
# File lib/sass/script/functions.rb, line 134
134: def round(value)
135: numeric_transformation(value) {|n| n.round}
136: end