Documentation for custom functions

Author: matryo

README.md

@@ -92,6 +92,66 @@ The callback function is passed a results object, containing the following keys:
 #### importer (starting from v2)
 `importer` is a `Function` to be called when libsass parser encounters the import directive. If present, libsass will call node-sass and let the user change file, data or both during the compilation. This option is optional, and applies to both render and renderSync functions. Also, it can either return object of form `{file:'..', contents: '..'}` or send it back via `done({})`. Note in renderSync or render, there is no restriction imposed on using `done()` callback or `return` statement (dispite of the asnchrony difference).
 
+#### functions
+`functions` is an `Object` that holds a collection of custom functions that may be invoked by the sass files being compiled. They 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:
+
+```javascript
+var Color = require('node-sass').types.Color,
+	c1 = new Color(255, 0, 0),
+	c2 = new Color(0xff0088cc);
+```
+
+##### types.Boolean(value)
+* `getValue()` / `setValue(value)` : gets / sets the enclosed boolean
+
+##### 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()
+
+##### Example
+
+```javascript
+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;
+    }
+  }
+});
+```
+
+
 #### includePaths
 `includePaths` is an `Array` of path `String`s to look for any `@import`ed files. It is recommended that you use this option if you are using the `data` option and have **any** `@import` directives, as otherwise [libsass] may not find your depended-on files.
 

test/api.js

@@ -593,6 +593,27 @@ describe('api', function() {
       assert.equal(result.css.trim(), 'div {\n  width: 50px; }');
       done();
     });
+
+    it('should return a list of selectors after calling the headings custom function', function(done) {
+      var result = 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;
+          }
+        }
+      });
+
+      assert.equal(result.css.trim(), 'h2, h3, h4, h5 {\n  color: #08c; }');
+      done();
+    });
   });
 
   describe('.renderSync(options)', function() {