Module: Sass::Script::Functions

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

Overview

Methods in this module are accessible from the Sass script context. For example, you can write

color = hsl(120, 100%, 50%)

and it will call Sass::Script::Functions#hsl.

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 (currently undocumented) Sass::Script::Literal objects, Literal objects are also the expected return values.

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 a sass function you can call the options method to gain access to the options hash that was used to create the Sass::Engine that is processing the function call.

The following functions are provided:

  • hsl - converts an hsl(hue, saturation, lightness) triplet into a color.

    The hue value should be between 0 and 360 inclusive, saturation and lightness must be between 0% to 100% inclusive. The percent sign is optional.

  • percentage - converts a unitless number to a css percentage.

    Example: percentage(14px / 7px) => 200%

  • round - Rounds a number to the nearest whole number.

    Example: round(10.4px) => 10px

  • ceil - Rounds a number up to the nearest whole number.

    Example: ceil(10.4px) => 11px

  • floor - Rounds a number down to the nearest whole number.

    Example: floor(10.6px) => 10px

  • abs - Returns the absolute value of a number.

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

Defined Under Namespace

Classes: EvaluationContext

Instance Method Summary collapse

Instance Method Details

#abs(value) ⇒ Object

Returns the absolute value of a number.



108
109
110
 
# File 'lib/sass/script/functions.rb', line 108

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

#ceil(value) ⇒ Object

Rounds up to the nearest whole number.



98
99
100
 
# File 'lib/sass/script/functions.rb', line 98

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

#floor(value) ⇒ Object

Rounds down to the nearest whole number.



103
104
105
 
# File 'lib/sass/script/functions.rb', line 103

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

#hsl(h, s, l) ⇒ Object

Creates a Sass::Script::Color object from hue, saturation, and lightness. As per the CSS3 spec (www.w3.org/TR/css3-color/#hsl-color), hue is in degrees, and saturation and lightness are percentages.

Raises:

  • (ArgumentError) 


63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/sass/script/functions.rb', line 63

def hsl(h, s, l)
  original_s = s
  original_l = l
  # This algorithm is from http://www.w3.org/TR/css3-color#hsl-color
  h, s, l = [h, s, l].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

#percentage(value) ⇒ Object

Converts a unitless number into a percent and multiplies the number by 100. E.g. percentage(100px / 50px) => 200% Some may find this more natural than: 100% * 100px / 50px



85
86
87
88
89
90
 
# File 'lib/sass/script/functions.rb', line 85

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

#round(value) ⇒ Object

Rounds a number to the nearest whole number.



93
94
95
 
# File 'lib/sass/script/functions.rb', line 93

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