Module: Sass::Script::Functions

Extended by:
Functions
Included in:
Functions
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.

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

Instance Method Summary collapse

Instance Method Details

#abs(value) ⇒ Object

Returns the absolute value of a number.



96
97
98
 
# File 'lib/sass/script/functions.rb', line 96

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

#ceil(value) ⇒ Object

Rounds up to the nearest whole number.



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

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

#floor(value) ⇒ Object

Rounds down to the nearest whole number.



91
92
93
 
# File 'lib/sass/script/functions.rb', line 91

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) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/sass/script/functions.rb', line 51

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



73
74
75
76
77
78
 
# File 'lib/sass/script/functions.rb', line 73

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.



81
82
83
 
# File 'lib/sass/script/functions.rb', line 81

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