Module: Sass::Script::Functions

Defined in:: lib/sass/script/functions.rb

Overview

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 value accessor for getting their Ruby values. Color objects, though, must be accessed using 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 options parameter to pass in data that can be accessed from your Sass functions.

Within one of the functions in this module, methods of EvaluationContext can be used.

Defined Under Namespace

Classes: EvaluationContext

Instance Method Summary

- (Number) abs(value) Finds the absolute value of a number.
- (Number) ceil(value) Rounds a number up to the nearest whole number.
- (Number) floor(value) Rounds down to the nearest whole number.
- (Color) hsl(hue, saturation, lightness) Creates a Color object from hue, saturation, and lightness.
- (Number) percentage(value) Converts a decimal number to a percentage.
- rgb(red, green, blue) Creates a Color object from red, green, and blue values.
- (Number) round(value) Rounds a number to the nearest whole number.

Instance Method Details

- (Number) abs(value)

Finds the absolute value of a number. For example:

abs(10px) => 10px
abs(-10px) => 10px

Parameters:

(Number) value — The number

Returns:

(Number) — The absolute value

Raises:

(Sass::SyntaxError) — if value isn’t a number



234
235
236

# File 'lib/sass/script/functions.rb', line 234

def abs(value)
  numeric_transformation(value) {|n| n.abs}
end

- (Number) ceil(value)

Rounds a number up to the nearest whole number. For example:

ciel(10.4px) => 11px
ciel(10.6px) => 11px

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(Sass::SyntaxError) — if value isn’t a number



208
209
210

# File 'lib/sass/script/functions.rb', line 208

def ceil(value)
  numeric_transformation(value) {|n| n.ceil}
end

- (Number) floor(value)

Rounds down to the nearest whole number. For example:

floor(10.4px) => 10px
floor(10.6px) => 10px

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(Sass::SyntaxError) — if value isn’t a number



221
222
223

# File 'lib/sass/script/functions.rb', line 221

def floor(value)
  numeric_transformation(value) {|n| n.floor}
end

- (Color) hsl(hue, saturation, lightness)

Creates a Color object from hue, saturation, and lightness. Uses the algorithm from the CSS3 spec.

Parameters:

(Number) hue — The hue of the color. Should be between 0 and 360 degrees, inclusive
(Number) saturation — The saturation of the color. Must be between 0% and 100%, inclusive
(Number) lightness — The lightness of the color. Must be between 0% and 100%, inclusive

Returns:

(Color) — The resulting color

Raises:

(ArgumentError) — if saturation or lightness are out of bounds

# File 'lib/sass/script/functions.rb', line 148

def hsl(hue, saturation, lightness)
  assert_type hue, :Number
  assert_type saturation, :Number
  assert_type lightness, :Number

  original_s = saturation
  original_l = lightness
  # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color
  h, s, l = [hue, saturation, lightness].map { |a| a.value }
  raise ArgumentError.new("Saturation #{s} must be between 0% and 100%") if s < 0 || s > 100
  raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") if l < 0 || l > 100

  h = (h % 360) / 360.0
  s /= 100.0
  l /= 100.0

  m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
  m1 = l * 2 - m2
  Color.new([hue_to_rgb(m1, m2, h + 1.0/3),
             hue_to_rgb(m1, m2, h),
             hue_to_rgb(m1, m2, h - 1.0/3)].map { |c| (c * 0xff).round })
end

- (Number) percentage(value)

Converts a decimal number to a percentage. For example:

percentage(100px / 50px) => 200%

Parameters:

(Number) value — The decimal number to convert to a percentage

Returns:

(Number) — The percentage

Raises:

(ArgumentError) — If value isn’t a unitless number

# File 'lib/sass/script/functions.rb', line 179

def percentage(value)
  unless value.is_a?(Sass::Script::Number) && value.unitless?
    raise ArgumentError.new("#{value.inspect} is not a unitless number")
  end
  Sass::Script::Number.new(value.value * 100, ['%'])
end

- rgb(red, green, blue)

Creates a Color object from red, green, and blue values.

Parameters:

red — A number between 0 and 255 inclusive, or between 0% and 100% inclusive
green — A number between 0 and 255 inclusive, or between 0% and 100% inclusive
blue — A number between 0 and 255 inclusive, or between 0% and 100% inclusive

# File 'lib/sass/script/functions.rb', line 119

def rgb(red, green, blue)
  assert_type red, :Number
  assert_type green, :Number
  assert_type blue, :Number

  rgb = [red, green, blue].map do |c|
    v = c.value
    if c.numerator_units == ["%"] && c.denominator_units.empty?
      next v * 255 / 100.0 if (0..100).include?(v)
      raise ArgumentError.new("Color value #{c} must be between 0% and 100% inclusive")
    else
      next v if (0..255).include?(v)
      raise ArgumentError.new("Color value #{v} must be between 0 and 255 inclusive")
    end
  end
  Color.new(rgb)
end

- (Number) round(value)

Rounds a number to the nearest whole number. For example:

round(10.4px) => 10px
round(10.6px) => 11px

Parameters:

(Number) value — The number

Returns:

(Number) — The rounded number

Raises:

(Sass::SyntaxError) — if value isn’t a number



195
196
197

# File 'lib/sass/script/functions.rb', line 195

def round(value)
  numeric_transformation(value) {|n| n.round}
end