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