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 172 172: def abs(value) 173: numeric_transformation(value) {|n| n.abs} 174: 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 146 146: def ceil(value) 147: numeric_transformation(value) {|n| n.ceil} 148: 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 159 159: def floor(value) 160: numeric_transformation(value) {|n| n.floor} 161: 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 90 90: def hsl(hue, saturation, lightness) 91: original_s = saturation 92: original_l = lightness 93: # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color 94: h, s, l = [hue, saturation, lightness].map { |a| a.value } 95: raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100 96: raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100 97: 98: h = (h % 360) / 360.0 99: s /= 100.0 100: l /= 100.0 101: 102: m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s 103: m1 = l * 2 - m2 104: Color.new([hue_to_rgb(m1, m2, h + 1.0/3), 105: hue_to_rgb(m1, m2, h), 106: hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round }) 107: 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 117 117: def percentage(value) 118: unless value.is_a?(Sass::Script::Number) && value.unitless? 119: raise ArgumentError.new("#{value} is not a unitless number") 120: end 121: Sass::Script::Number.new(value.value * 100, ['%']) 122: 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: raise ArgumentError.new("Color value #{v} must be between 0 and 255 inclusive") if v <= 0 || v >= 255 75: end 76: Color.new([red.value, green.value, blue.value]) 77: 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 133 133: def round(value) 134: numeric_transformation(value) {|n| n.round} 135: end