Rewriting the "Custom functions" section of node-sass document

[ajhsu]

functions (>= v3.0.0) - experimental

This is an experimental LibSass feature. Use with caution.

// Mention about internal functions
Like these useful functions Sass provided out of box, you can implement your own functions as well.
functions is an Object that holds a collection of custom functions that may be invoked by the sass files being compiled.

functions: {
  "<Function Signature>": <Callback>,
  "<Function Signature>": <Callback>,
  // And so on ...
}

Function Signature (String)

Function signature is a plain JavaScript string that should be written in following function declaration syxtax:
"function-name($param1, $param2, $param3)"

For example:
"custom-url($path)": function (path) { }

So that you can call custom function within your Sass files:
background-image: custom-url('/images/example.jpg');

Since function signatures are also part of SassScript, few things should be remind:

1. Variable names should begin with dollar sign ($).
2. Underscores and dashes were both allowed in function name.

Callback (Function)

Callback may take zero or more input parameters and must return a value either synchronously (return ...;) or asynchronously (done();). Those parameters will be instances of one of the constructors contained in the require('node-sass').types hash. The return value must be of one of these types as well. See the list of available types below:

types.Number(value [, unit = ""])

• getValue()/ setValue(value) : gets / sets the numerical portion of the number
• getUnit() / setUnit(unit) : gets / sets the unit portion of the number

types.String(value)

• getValue() / setValue(value) : gets / sets the enclosed string

types.Color(r, g, b [, a = 1.0]) or types.Color(argb)

• getR() / setR(value) : red component (integer from 0 to 255)
• getG() / setG(value) : green component (integer from 0 to 255)
• getB() / setB(value) : blue component (integer from 0 to 255)
• getA() / setA(value) : alpha component (number from 0 to 1.0)

Example:

var Color = require('node-sass').types.Color,
  c1 = new Color(255, 0, 0),
  c2 = new Color(0xff0088cc);

types.Boolean(value)

• getValue() : gets the enclosed boolean
• types.Boolean.TRUE : Singleton instance of types.Boolean that holds "true"
• types.Boolean.FALSE : Singleton instance of types.Boolean that holds "false"

types.List(length [, commaSeparator = true])

• getValue(index) / setValue(index, value) : value must itself be an instance of one of the constructors in sass.types.
• getSeparator() / setSeparator(isComma) : whether to use commas as a separator
• getLength()

types.Map(length)

• getKey(index) / setKey(index, value)
• getValue(index) / setValue(index, value)
• getLength()

types.Null()

• types.Null.NULL : Singleton instance of types.Null.

Example

sass.renderSync({
  data: '#{headings(2,5)} { color: #08c; }',
  functions: {
  }
});

// Outputs:
//
'function_name($param1: [default_value], $param2: [default_value], ...)': function(param1, param2, ...) {
    param1.getValue()
    param2.getValue()
}
string as function name 
function(parameters)

sass.renderSync({
  data: '#{headings(2,5)} { color: #08c; }',
  functions: {
    'headings($from: 0, $to: 6)': function(from, to) {
      var i, f = from.getValue(), t = to.getValue(),
          list = new sass.types.List(t - f + 1);

      for (i = f; i <= t; i++) {
        list.setValue(i - f, new sass.types.String('h' + i));
      }

      return list;
    }
  }
});

[ajhsu]

Introduction of Sass functions from the official document
http://sass-lang.com/documentation/Sass/Script/Functions.html

Docs of api function of libSass
https://github.com/sass/node-sass/blob/master/src/libsass/docs/api-function.md

[ajhsu]

Draft of the PR

Since the Custom functions [was introduced](https://github.com/sass/node-sass/pull/644) with the first version of its document, it has been 2+ years past.

I think the section of document about the Custom functions should be explained in more detailed.

[ajhsu]

Original issue about custom functions:
https://github.com/sass/node-sass/issues/332

Original PR about custom functions:
https://github.com/sass/node-sass/pull/644