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

ajhsu commented 7 years ago

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:

Variable names should begin with dollar sign ($).
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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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

ajhsu / blog