Module: Sass::Script::Functions
- Defined in:
- /var/www/sass-pages/.haml/lib/sass/script/functions.rb
Overview
Methods in this module are accessible from the SassScript context. For example, you can write
$color = hsl(120deg, 100%, 50%)
and it will call Sass::Script::Functions#hsl.
The following functions are provided:
RGB Functions
- #rgb
- Converts an
rgb(red, green, blue)triplet into a color. - #rgba
- Converts an
rgba(red, green, blue, alpha)quadruplet into a color. - #red
- Gets the red component of a color.
- #green
- Gets the green component of a color.
- #blue
- Gets the blue component of a color.
- #mix
- Mixes two colors together.
HSL Functions
- #hsl
- Converts an
hsl(hue, saturation, lightness)triplet into a color. - #hsla
- Converts an
hsla(hue, saturation, lightness, alpha)quadruplet into a color. - #hue
- Gets the hue component of a color.
- #saturation
- Gets the saturation component of a color.
- #lightness
- Gets the lightness component of a color.
- #adjust-hue
- Changes the hue of a color.
- #lighten
- Makes a color lighter.
- #darken
- Makes a color darker.
- #saturate
- Makes a color more saturated.
- #desaturate
- Makes a color less saturated.
- #grayscale
- Converts a color to grayscale.
- #complement
- Returns the complement of a color.
Opacity Functions
- #alpha / #opacity
- Gets the alpha component (opacity) of a color.
- #rgba
- Sets the alpha component of a color.
- #opacify / #fade-in
- Makes a color more opaque.
- #transparentize / #fade-out
- Makes a color more transparent.
String Functions
Number Functions
- #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.
Introspection Functions
- #type_of
- Returns the type of a value.
- #unit
- Returns the units associated with a number.
- #unitless
- Returns whether a number has units or not.
- #comparable
- Returns whether two numbers can be added or compared.
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, red, green, or blue.
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.
Caveats
When creating new Literal objects within functions, be aware that it’s not safe to call #to_s (or other methods that use the string representation) on those objects without first setting the #options attribute.
Defined Under Namespace
Classes: EvaluationContext
Instance Method Summary
- - (Number) abs(value) Finds the absolute value of a number.
- - (Color) adjust_hue(color, degrees) Changes the hue of a color while retaining the lightness and saturation.
- - alpha(color) Returns the alpha component (opacity) of a color.
- - (Number) blue(color) Returns the blue component of a color.
- - (Number) ceil(value) Rounds a number up to the nearest whole number.
- - (Bool) comparable(number1, number2) Returns true if two numbers are similar enough to be added, subtracted, or compared.
- - (Color) complement(color) Returns the complement of a color.
- - (Color) darken(color, amount) Makes a color darker.
- - (Color) desaturate(color, amount) Makes a color less saturated.
- - (Number) floor(value) Rounds down to the nearest whole number.
- - (Color) grayscale(color) Converts a color to grayscale.
- - (Number) green(color) Returns the green component of a color.
- - (Color) hsl(hue, saturation, lightness) Creates a Color object from hue, saturation, and lightness.
- - (Color) hsla(hue, saturation, lightness, alpha) Creates a Color object from hue, saturation, and lightness, as well as an alpha channel indicating opacity.
- - (Number) hue(color) Returns the hue component of a color.
- - (Color) lighten(color, amount) Makes a color lighter.
- - (Number) lightness(color) Returns the hue component of a color.
- - (Color) mix(color1, color2, weight = 50%) Mixes together two colors.
- - (Color) opacify(color, amount) (also: #fade_in) Makes a color more opaque.
- - (Number) opacity(color) Returns the alpha component (opacity) of a color.
- - (Number) percentage(value) Converts a decimal number to a percentage.
- - (String) quote(str) Add quotes to a string if the string isn’t quoted, or returns the same string if it is.
- - (Number) red(color) Returns the red component of a color.
- - (Color) rgb(red, green, blue) Creates a Color object from red, green, and blue values.
- - rgba(*args)
- - (Number) round(value) Rounds a number to the nearest whole number.
- - (Color) saturate(color, amount) Makes a color more saturated.
- - (Number) saturation(color) Returns the saturation component of a color.
- - (Color) transparentize(color, amount) (also: #fade_out) Makes a color more transparent.
- - (String) type_of(obj) Inspects the type of the argument, returning it as an unquoted string.
- - (String) unit(number) Inspects the unit of the number, returning it as a quoted string.
- - (Bool) unitless(number) Inspects the unit of the number, returning a boolean indicating if it is unitless.
- - (String) unquote(str) Removes quotes from a string if the string is quoted, or returns the same string if it’s not.
Instance Method Details
- (Number) abs(value)
Finds the absolute value of a number. For example:
abs(10px) => 10px abs(-10px) => 10px
833 834 835 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 833
def abs(value)
numeric_transformation(value) {|n| n.abs}
end
|
- (Color) adjust_hue(color, degrees)
Changes the hue of a color while retaining the lightness and saturation. Takes a color and a number of degrees (usually between -360deg and 360deg), and returns a color with the hue rotated by that value.
For example:
adjust-hue(hsl(120, 30%, 90%), 60deg) => hsl(180, 30%, 90%) adjust-hue(hsl(120, 30%, 90%), 060deg) => hsl(60, 30%, 90%) adjust-hue(#811, 45deg) => #886a11
581 582 583 584 585 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 581
def adjust_hue(color, degrees)
assert_type color, :Color
assert_type degrees, :Number
color.with(:hue => color.hue + degrees.value)
end
|
- alpha(color)
Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.
This function also supports the proprietary Microsoft alpha(opacity=20) syntax.
426 427 428 429 430 431 432 433 434 435 436 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 426
def alpha(*args)
if args.all? do |a|
a.is_a?(Sass::Script::String) && a.type == :identifier &&
a.value =~ /^[a-zA-Z]+\s*=/
end
# Support the proprietary MS alpha() function
return Sass::Script::String.new("alpha(#{args.map {|a| a.to_s}.join(", ")})")
end
opacity(*args)
end
|
- (Number) blue(color)
Returns the blue component of a color.
362 363 364 365 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 362
def blue(color)
assert_type color, :Color
Sass::Script::Number.new(color.blue)
end
|
- (Number) ceil(value)
Rounds a number up to the nearest whole number. For example:
ciel(10.4px) => 11px ciel(10.6px) => 11px
807 808 809 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 807
def ceil(value)
numeric_transformation(value) {|n| n.ceil}
end
|
- (Bool) comparable(number1, number2)
Returns true if two numbers are similar enough to be added, subtracted, or compared. For example:
comparable(2px, 1px) => true comparable(100px, 3em) => false comparable(10cm, 3mm) => true
764 765 766 767 768 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 764
def comparable(number1, number2)
assert_type number1, :Number
assert_type number2, :Number
Sass::Script::Bool.new(number1.comparable_to?(number2))
end
|
- (Color) complement(color)
Returns the complement of a color. This is identical to adjust-hue(color, 180deg).
671 672 673 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 671
def complement(color)
adjust_hue color, Number.new(180)
end
|
- (Color) darken(color, amount)
Makes a color darker. Takes a color and an amount between 0% and 100%, and returns a color with the lightness decreased by that value.
For example:
darken(hsl(25, 100%, 80%), 30%) => hsl(25, 100%, 50%) darken(#800, 20%) => #200
525 526 527 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 525
def darken(color, amount)
adjust(color, amount, :lightness, 0..100, :-, "%")
end
|
- (Color) desaturate(color, amount)
Makes a color less saturated. Takes a color and an amount between 0% and 100%, and returns a color with the saturation decreased by that value.
For example:
desaturate(hsl(120, 30%, 90%), 20%) => hsl(120, 10%, 90%) desaturate(#855, 20%) => #726b6b
563 564 565 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 563
def desaturate(color, amount)
adjust(color, amount, :saturation, 0..100, :-, "%")
end
|
- (Number) floor(value)
Rounds down to the nearest whole number. For example:
floor(10.4px) => 10px floor(10.6px) => 10px
820 821 822 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 820
def floor(value)
numeric_transformation(value) {|n| n.floor}
end
|
- (Color) grayscale(color)
Converts a color to grayscale. This is identical to desaturate(color, 100%).
660 661 662 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 660
def grayscale(color)
desaturate color, Number.new(100)
end
|
- (Number) green(color)
Returns the green component of a color.
352 353 354 355 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 352
def green(color)
assert_type color, :Color
Sass::Script::Number.new(color.green)
end
|
- (Color) hsl(hue, saturation, lightness)
298 299 300 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 298
def hsl(hue, saturation, lightness)
hsla(hue, saturation, lightness, Number.new(1))
end
|
- (Color) hsla(hue, saturation, lightness, alpha)
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 317
def hsla(hue, saturation, lightness, alpha)
assert_type hue, :Number
assert_type saturation, :Number
assert_type lightness, :Number
assert_type alpha, :Number
unless (0..1).include?(alpha.value)
raise ArgumentError.new("Alpha channel #{alpha.value} must be between 0 and 1")
end
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%") unless (0..100).include?(s)
raise ArgumentError.new("Lightness #{l} must be between 0% and 100%") unless (0..100).include?(l)
Color.new(:hue => h, :saturation => s, :lightness => l, :alpha => alpha.value)
end
|
- (Number) hue(color)
Returns the hue component of a color.
See the CSS3 HSL specification.
Calculated from RGB where necessary via this algorithm.
377 378 379 380 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 377
def hue(color)
assert_type color, :Color
Sass::Script::Number.new(color.hue, ["deg"])
end
|
- (Color) lighten(color, amount)
Makes a color lighter. Takes a color and an amount between 0% and 100%, and returns a color with the lightness increased by that value.
For example:
lighten(hsl(0, 0%, 0%), 30%) => hsl(0, 0, 30) lighten(#800, 20%) => #e00
506 507 508 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 506
def lighten(color, amount)
adjust(color, amount, :lightness, 0..100, :+, "%")
end
|
- (Number) lightness(color)
Returns the hue component of a color.
See the CSS3 HSL specification.
Calculated from RGB where necessary via this algorithm.
409 410 411 412 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 409
def lightness(color)
assert_type color, :Color
Sass::Script::Number.new(color.lightness, ["%"])
end
|
- (Color) mix(color1, color2, weight = 50%)
Mixes together two colors. Specifically, takes the average of each of the RGB components, optionally weighted by the given percentage. The opacity of the colors is also considered when weighting the components.
The weight specifies the amount of the first color that should be included in the returned color. The default, 50%, means that half the first color and half the second color should be used. 25% means that a quarter of the first color and three quarters of the second color should be used.
For example:
mix(#f00, #00f) => #7f007f mix(#f00, #00f, 25%) => #3f00bf mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)
612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 612
def mix(color1, color2, weight = Number.new(50))
assert_type color1, :Color
assert_type color2, :Color
assert_type weight, :Number
unless (0..100).include?(weight.value)
raise ArgumentError.new("Weight #{weight} must be between 0% and 100%")
end
# This algorithm factors in both the user-provided weight
# and the difference between the alpha values of the two colors
# to decide how to perform the weighted average of the two RGB values.
#
# It works by first normalizing both parameters to be within [-1, 1],
# where 1 indicates "only use color1", -1 indicates "only use color 0",
# and all values in between indicated a proportionately weighted average.
#
# Once we have the normalized variables w and a,
# we apply the formula (w + a)/(1 + w*a)
# to get the combined weight (in [-1, 1]) of color1.
# This formula has two especially nice properties:
#
# * When either w or a are -1 or 1, the combined weight is also that number
# (cases where w * a == -1 are undefined, and handled as a special case).
#
# * When a is 0, the combined weight is w, and vice versa
#
# Finally, the weight of color1 is renormalized to be within [0, 1]
# and the weight of color2 is given by 1 minus the weight of color1.
p = weight.value/100.0
w = p*2 - 1
a = color1.alpha - color2.alpha
w1 = (((w * a == -1) ? w : (w + a)/(1 + w*a)) + 1)/2.0
w2 = 1 - w1
rgb = color1.rgb.zip(color2.rgb).map {|v1, v2| v1*w1 + v2*w2}
alpha = color1.alpha*p + color2.alpha*(1-p)
Color.new(rgb + [alpha])
end
|
- (Color) opacify(color, amount) Also known as: fade_in
Makes a color more opaque. Takes a color and an amount between 0 and 1, and returns a color with the opacity increased by that value.
For example:
opacify(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.6) opacify(rgba(0, 0, 17, 0.8), 0.2) => #001
466 467 468 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 466
def opacify(color, amount)
adjust(color, amount, :alpha, 0..1, :+)
end
|
- (Number) opacity(color)
Returns the alpha component (opacity) of a color. This is 1 unless otherwise specified.
446 447 448 449 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 446
def opacity(color)
assert_type color, :Color
Sass::Script::Number.new(color.alpha)
end
|
- (Number) percentage(value)
Converts a decimal number to a percentage. For example:
percentage(100px / 50px) => 200%
778 779 780 781 782 783 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 778
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
|
- (String) quote(str)
Add quotes to a string if the string isn’t quoted, or returns the same string if it is.
700 701 702 703 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 700
def quote(str)
assert_type str, :String
Sass::Script::String.new(str.value, :string)
end
|
- (Number) red(color)
Returns the red component of a color.
342 343 344 345 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 342
def red(color)
assert_type color, :Color
Sass::Script::Number.new(color.red)
end
|
- (Color) rgb(red, green, blue)
Creates a Color object from red, green, and blue values.
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 222
def rgb(red, green, blue)
assert_type red, :Number
assert_type green, :Number
assert_type blue, :Number
Color.new([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)
end
|
- (Color) rgba(red, green, blue, alpha) - (Color) rgba(color, alpha)
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 265
def rgba(*args)
case args.size
when 2
color, alpha = args
assert_type color, :Color
assert_type alpha, :Number
unless (0..1).include?(alpha.value)
raise ArgumentError.new("Alpha channel #{alpha.value} must be between 0 and 1 inclusive")
end
color.with(:alpha => alpha.value)
when 4
red, green, blue, alpha = args
rgba(rgb(red, green, blue), alpha)
else
raise ArgumentError.new("wrong number of arguments (#{args.size} for 4)")
end
end
|
- (Number) round(value)
Rounds a number to the nearest whole number. For example:
round(10.4px) => 10px round(10.6px) => 11px
794 795 796 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 794
def round(value)
numeric_transformation(value) {|n| n.round}
end
|
- (Color) saturate(color, amount)
Makes a color more saturated. Takes a color and an amount between 0% and 100%, and returns a color with the saturation increased by that value.
For example:
saturate(hsl(120, 30%, 90%), 20%) => hsl(120, 50%, 90%) saturate(#855, 20%) => #9e3f3f
544 545 546 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 544
def saturate(color, amount)
adjust(color, amount, :saturation, 0..100, :+, "%")
end
|
- (Number) saturation(color)
Returns the saturation component of a color.
See the CSS3 HSL specification.
Calculated from RGB where necessary via this algorithm.
393 394 395 396 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 393
def saturation(color)
assert_type color, :Color
Sass::Script::Number.new(color.saturation, ["%"])
end
|
- (Color) transparentize(color, amount) Also known as: fade_out
Makes a color more transparent. Takes a color and an amount between 0 and 1, and returns a color with the opacity decreased by that value.
For example:
transparentize(rgba(0, 0, 0, 0.5), 0.1) => rgba(0, 0, 0, 0.4) transparentize(rgba(0, 0, 0, 0.8), 0.2) => rgba(0, 0, 0, 0.6)
486 487 488 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 486
def transparentize(color, amount)
adjust(color, amount, :alpha, 0..1, :-)
end
|
- (String) type_of(obj)
Inspects the type of the argument, returning it as an unquoted string. For example:
type-of(100px) => number
type-of(asdf) => string
type-of("asdf") => string
type-of(true) => bool
type-of(#fff) => color
type-of(blue) => color
717 718 719 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 717
def type_of(obj)
Sass::Script::String.new(obj.class.name.gsub(/Sass::Script::/,'').downcase)
end
|
- (String) unit(number)
Inspects the unit of the number, returning it as a quoted string. Complex units are sorted in alphabetical order by numerator and denominator. For example:
unit(100) => "" unit(100px) => "px" unit(3em) => "em" unit(10px * 5em) => "em*px" unit(10px * 5em / 30cm / 1rem) => "em*px/cm*rem"
734 735 736 737 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 734
def unit(number)
assert_type number, :Number
Sass::Script::String.new(number.unit_str, :string)
end
|
- (Bool) unitless(number)
Inspects the unit of the number, returning a boolean indicating if it is unitless. For example:
unitless(100) => true unitless(100px) => false
748 749 750 751 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 748
def unitless(number)
assert_type number, :Number
Sass::Script::Bool.new(number.unitless?)
end
|
- (String) unquote(str)
Removes quotes from a string if the string is quoted, or returns the same string if it’s not.
685 686 687 688 |
# File '/var/www/sass-pages/.haml/lib/sass/script/functions.rb', line 685
def unquote(str)
assert_type str, :String
Sass::Script::String.new(str.value, :identifier)
end
|