Permalink
Browse files

Documentation about named arguments.

  • Loading branch information...
1 parent f774ca4 commit a0effa0114e66df310d099869f9c7bb4778fceab @chriseppstein chriseppstein committed Oct 2, 2010
Showing with 92 additions and 39 deletions.
  1. +5 −0 doc-src/SASS_CHANGELOG.md
  2. +40 −1 doc-src/SASS_REFERENCE.md
  3. +47 −38 lib/sass/script/functions.rb
@@ -6,6 +6,11 @@
## 3.2.0 (Unreleased)
* Add an {Sass::Script::Functions#invert `invert` function} that takes the inverse of colors.
+* Sass Functions and Mixins now accept **Named Arguments** in addition to the more traditional
+ positional argument style. See the following documentation for more information:
+ {file:SASS_REFERENCE.md#named_arguments Named Arguments for Mixins},
+ {file:SASS_REFERENCE.md#functions Named Arguments for Sass Functions},
+ {file:SASS_REFERENCE.md#defining_custom_sass_functions Defining Custom Functions}
### Backwards Incompatibilities -- Must Read!
@@ -859,6 +859,19 @@ is compiled to:
p {
color: #ff0000; }
+Unlike their CSS counterparts, Sass-based functions allow you to pass
+named arguments in addition to the more traditional positional argument style.
+The example above can also be written as:
+
+ p {
+ color: hsl($hue: 0, $saturation: 100%, $lightness: 0.5);
+ }
+
+While this is more typing, you might prefer it to add clarity for the readers of
+the stylesheet. Additionally, since a sass function can accept arbitrary named
+arguments, this allows a ruby function to present a very flexible interface to
+the stylesheets.
+
See {Sass::Script::Functions} for a full listing of Sass functions,
as well as instructions on defining your own in Ruby.
@@ -1591,6 +1604,32 @@ is compiled to:
border-width: 2in;
border-style: dashed; }
+### Named Arguments
+
+Because mixins are not standardized, it can be difficult for readers of a stylesheet
+to know what the arguments mean when they come across a mixin include. Additionally, some
+mixins have many arguments and often those have defaults and it becomes difficult to include
+the mixin when you only care to override a small set of the default values. Because of
+these cases, Sass allows you to pass named arguments when including a mixin or calling a
+sass function.
+
+For instance, we could have written the above example like this:
+
+ @mixin sexy-border($color, $width: 1in) {
+ border: {
+ color: $color;
+ width: $width;
+ style: dashed;
+ }
+ }
+ p { @include sexy-border($color: blue); }
+ h1 { @include sexy-border($color: blue, $width: 2in); }
+
+Named arguments can be passed in any order and arguments with default values can be
+omitted just like they can when passing arguments positionally. Because the named
+arguments are variable names, it should be noted that underscores and dashes can be used
+interchangeably.
+
## Output Style
Although the default CSS style that Sass outputs is very nice
@@ -1684,7 +1723,7 @@ Using these features requires a strong understanding of Ruby.
The same way that Sass defines new functions for use in Sass stylesheets is available
to users who which to do so. For more information see the [source
-documentation](/docs/yardoc/Sass/Script/Functions.html#adding_custom_functions).
+documentation](Sass/Script/Functions.html#adding_custom_functions).
### Cache Stores
@@ -8,122 +8,125 @@ module Sass::Script
#
# The following functions are provided:
#
+ # *Note: These functions are described in more detail below.*
+ #
# ## RGB Functions
#
- # \{#rgb}
+ # \{#rgb rgb($red, $green, $blue)}
# : Converts an `rgb(red, green, blue)` triplet into a color.
#
- # \{#rgba}
+ # \{#rgba rgba($red, $green, $blue, $alpha)}
# : Converts an `rgba(red, green, blue, alpha)` quadruplet into a color.
#
- # \{#red}
+ # \{#rgba rgba($color, $alpha)}
+ # : Adds an alpha layer to any color value.
+ #
+ # \{#red red($color)}
# : Gets the red component of a color.
#
- # \{#green}
+ # \{#green green($color)}
# : Gets the green component of a color.
#
- # \{#blue}
+ # \{#blue blue($color)}
# : Gets the blue component of a color.
#
- # \{#mix}
+ # \{#mix mix($color-1, $color-2\[, $weight\])}
# : Mixes two colors together.
#
# ## HSL Functions
#
- # \{#hsl}
+ # \{#hsl hsl($hue, $saturation, $lightness)}
# : Converts an `hsl(hue, saturation, lightness)` triplet into a color.
#
- # \{#hsla}
+ # \{#hsla hsla($hue, $saturation, $lightness, $alpha)}
# : Converts an `hsla(hue, saturation, lightness, alpha)` quadruplet into a color.
#
- # \{#hue}
+ # \{#hue hue($color)}
# : Gets the hue component of a color.
#
- # \{#saturation}
+ # \{#saturation saturation($color)}
# : Gets the saturation component of a color.
#
- # \{#lightness}
+ # \{#lightness lightness($color))}
# : Gets the lightness component of a color.
#
- # \{#adjust_hue #adjust-hue}
+ # \{#adjust_hue adjust-hue($color, $degrees)}
# : Changes the hue of a color.
#
- # \{#lighten}
+ # \{#lighten lighten($color, $amount)}
# : Makes a color lighter.
#
- # \{#darken}
+ # \{#darken darken($color, $amount)}
# : Makes a color darker.
#
- # \{#saturate}
+ # \{#saturate saturate($color, $amount)}
# : Makes a color more saturated.
#
- # \{#desaturate}
+ # \{#desaturate desaturate($color, $amount)}
# : Makes a color less saturated.
#
- # \{#grayscale}
+ # \{#grayscale grayscale($color)}
# : Converts a color to grayscale.
#
- # \{#complement}
+ # \{#complement complement($color)}
# : Returns the complement of a color.
#
- # \{#invert}
+ # \{#invert invert($color)}
# : Returns the inverse of a color.
#
# ## Opacity Functions
#
- # \{#alpha} / \{#opacity}
+ # \{#alpha alpha($color)} / \{#opacity opacity($color)}
# : Gets the alpha component (opacity) of a color.
#
- # \{#rgba}
- # : Sets the alpha component of a color.
+ # \{#rgba rgba($color, $alpha)}
+ # : Add or change an alpha layer for any color value.
#
- # \{#opacify} / \{#fade_in #fade-in}
+ # \{#opacify opacify($color, $amount)} / \{#fade_in fade-in($color, $amount)}
# : Makes a color more opaque.
#
- # \{#transparentize} / \{#fade_out #fade-out}
+ # \{#transparentize transparentize($color, $amount)} / \{#fade_out fade-out($color, $amount)}
# : Makes a color more transparent.
#
# ## String Functions
#
- # \{#unquote}
+ # \{#unquote unquote($string)}
# : Removes the quotes from a string.
#
- # \{#quote}
+ # \{#quote quote($string)}
# : Adds quotes to a string.
#
# ## Number Functions
#
- # \{#percentage}
+ # \{#percentage percentage($value)}
# : Converts a unitless number to a percentage.
#
- # \{#round}
+ # \{#round round($value)}
# : Rounds a number to the nearest whole number.
#
- # \{#ceil}
+ # \{#ceil ceil($value)}
# : Rounds a number up to the nearest whole number.
#
- # \{#floor}
+ # \{#floor floor($value)}
# : Rounds a number down to the nearest whole number.
#
- # \{#abs}
+ # \{#abs abs($value)}
# : Returns the absolute value of a number.
#
# ## Introspection Functions
#
- # \{#type_of}
+ # \{#type_of type-of($value)}
# : Returns the type of a value.
#
- # \{#unit}
+ # \{#unit unit($number)}
# : Returns the units associated with a number.
#
- # \{#unitless}
+ # \{#unitless unitless($number)}
# : Returns whether a number has units or not.
#
- # \{#comparable}
+ # \{#comparable comparable($number-1, $number-2)}
# : 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.
@@ -134,8 +137,14 @@ module Sass::Script
# assert_type string, :String
# Sass::Script::String.new(string.value.reverse)
# end
+ # define :reverse, :args => [:string]
# end
#
+ # Calling `define` after creating your function is how you tell
+ # Sass what function signature(s) your function presents to the stylesheets.
+ # If omitted, the function will still work, but will not be able to accept
+ # named arguments. See {Sass::Script::Functions.define} for more information.
+ #
# 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.
@@ -204,7 +213,7 @@ def self.define(method_name, options)
# @param arg_arity The number of unnamed arguments the function was invoked with
# @param kwarg_arity The number of named arguments the function was invoked with
#
- # @return The signature options for the matching signature that were passed to {define}
+ # @return [Hash] The signature options for the matching signature that were passed to {define}
def self.signature(method_name, arg_arity, kwarg_arity)
return unless @signatures[method_name.to_sym]
@signatures[method_name.to_sym].each do |signature|

0 comments on commit a0effa0

Please sign in to comment.