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.

Methods

abs   ceil   floor   hsl   percentage   rgb   round  

Classes and Modules

Class Sass::Script::Functions::EvaluationContext

Public Instance methods

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

[Source]

     # 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

[Source]

     # 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

[Source]

     # 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

[Source]

     # 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

[Source]

     # 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

[Source]

     # 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

[Source]

     # File lib/sass/script/functions.rb, line 195
195:     def round(value)
196:       numeric_transformation(value) {|n| n.round}
197:     end

[Validate]