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.
\{rgb} : Converts an `rgb(red, green, blue)` 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.
These functions are described in more detail below.
## 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 end
There are a few things to keep in mind when modifying this module. First of all, the arguments passed are {Sass::Script::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 {Sass::Script::Literal#value value} accessor for getting their Ruby values. Color objects, though, must be accessed using {Sass::Script::Color#rgb rgb}.
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 {Sass::Engine} to render the code, using the {file:SASS_REFERENCE.md#custom-option `options` parameter} to pass in data that {EvaluationContext#options can be accessed} from your Sass functions.
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 234 234: def abs(value) 235: numeric_transformation(value) {|n| n.abs} 236: 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 208 208: def ceil(value) 209: numeric_transformation(value) {|n| n.ceil} 210: 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 221 221: def floor(value) 222: numeric_transformation(value) {|n| n.floor} 223: end
Creates a {Color} object from hue, saturation, and lightness. Uses the algorithm from 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 148 148: def hsl(hue, saturation, lightness) 149: assert_type hue, :Number 150: assert_type saturation, :Number 151: assert_type lightness, :Number 152: 153: original_s = saturation 154: original_l = lightness 155: # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color 156: h, s, l = [hue, saturation, lightness].map { |a| a.value } 157: raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100 158: raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100 159: 160: h = (h % 360) / 360.0 161: s /= 100.0 162: l /= 100.0 163: 164: m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s 165: m1 = l * 2 - m2 166: Color.new([hue_to_rgb(m1, m2, h + 1.0/3), 167: hue_to_rgb(m1, m2, h), 168: hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round }) 169: 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 179 179: def percentage(value) 180: unless value.is_a?(Sass::Script::Number) && value.unitless? 181: raise ArgumentError.new("#{value.inspect} is not a unitless number") 182: end 183: Sass::Script::Number.new(value.value * 100, ['%']) 184: end
Creates a {Color} object from red, green, and blue values. @param red
A number between 0 and 255 inclusive, or between 0% and 100% inclusive
@param green
A number between 0 and 255 inclusive, or between 0% and 100% inclusive
@param blue
A number between 0 and 255 inclusive, or between 0% and 100% inclusive
# File lib/sass/script/functions.rb, line 119 119: def rgb(red, green, blue) 120: assert_type red, :Number 121: assert_type green, :Number 122: assert_type blue, :Number 123: 124: rgb = [red, green, blue].map do |c| 125: v = c.value 126: if c.numerator_units == ["%"] && c.denominator_units.empty? 127: next v * 255 / 100.0 if (0..100).include?(v) 128: raise ArgumentError.new("Color value #{c} must be between 0% and 100% inclusive") 129: else 130: next v if (0..255).include?(v) 131: raise ArgumentError.new("Color value #{v} must be between 0 and 255 inclusive") 132: end 133: end 134: Color.new(rgb) 135: 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 195 195: def round(value) 196: numeric_transformation(value) {|n| n.round} 197: end