Roole API

JavaScript API

For browsers, a global object roole is exposed when the Roole JavaScript file is inserted into HTML.

For Node.js, use var roole = require('roole').

roole.compile(input, [options], callback);
input

The Roole code string

options

An optional literal object for options. See the Options section for details.

callback(error, css)

A callback function that will be called when CSS is generated. See the Callback section for details on arguments.

Options

base

An absolute path. Relative paths do not start with ./ and ../ are relative this path. If no specified, these relative paths are not translated.

filename (default: base)

The absolute path of the file containg this Roole code. Relative paths starting with ./ or ../ are relative to the directory of this path. If not specified, these relative paths are relative to the value of the base option. If that's also unspecified, these relative paths are not translated.

out (default: base)

The absolute path of the directory where the file containing the generated CSS code lives. Translated relative paths are relative to this directory.

indent (default: "\t")

Indentation string to use in the generated CSS code.

precision (default: 5)

Max number of decimal digits to use in the generated CSS code.

prefixes (default: ["webkit", "moz", "ms", "o"])

An array of vendor names to use for prefixing. The order determines the order of prefixed properties in the generated CSS code.

Use an empty array or a falsy value to disable prefixing completely.

skipPrefixed (default: false)

Not generating prefixed rules that already exist. Enabling this option will slow down things a little bit. If you don't mix prefixed rules with unprefixed rules in the source code, leave this option to false.

imports (default: {})

An object literal containing the files to be imported. When a file that needs to be imported exists in this object, it will be used directly and no external requests are made.

The key is the absolute file path, and the value is the file content.

When CSS is generated, this option will contain the files that have been imported.

global (default: {})

An literal object containing global variables that will be defined for the code. The key is the variables name, the value is the variable value.

Values are converted to Roole values the same way as how the returning values of builtin functions are converted.

Callback

The callback function supports these arguments:

error

If there is no error when compiling, this object is null or undefined.

Otherwise this is an error object. See the Error Object section for details.

css

The generated CSS string

Error Object

An error object is passed to the callback function when there is an error. It contains these additional properties:

loc

An object containing the location info indicating where that error has happened in code.

The line number is line (one-based). The column number is column (one-based). Its start position in the source code string is start (zero-based), and end position end (zero-based).

context([indent])

A function will return a few lines of code near the error location, with a line number added at the start of each line.

Use indent to add indentation to these lines of code. By default it's an empty string, meaning no indentation is added.

Plugin API

Plugins can do two things:

Plugins are created by passing a function to roole.use().

roole.use(function (roole) {
  // plugin code
});

The function will be passed to the roole object.

Node.js authors should export this function, and let users pass this function to roole.use() themselves.

module.exports = function (roole) {
  // plugin code
});

Browser authors can either use roole.use() or manipulate roole directly.

Add Builtin Functions

Plugins define new builtin functions by adding properties to roole.builtin. The key is the builtin function name, the value is a function.

Arguments passed to the builtin function will be passed to this JavaScript function. Each argument is a Roole node. A Roole node is simply a JSON object. Refer to Roole grammar on the structure of different Roole nodes.

this keyword in the function refer to an instance of Roole evaluator, which contains some useful properties.

The returning value of this function becomes the returning value of the builtin function. Promises are recgonized.

When a primitive value (or a promise whose fulfilling value is a primitive value) is returned, it will be converted to Roole values if possible. null and numbers are converted directly. undefined is converted to null. Strings are parsed. For example, returning "'string'" will result 'string' in Roole.

A JSON object representing a Roole node can also be returned. Node utilities function of the roole-node project may come in handy when you do that.

To indicate an error, throw a RooleError object which can be found in the roole-error project. In addition to the error message, pass it the responsible Roole node to indicate the error location.

See the roole-builtin project for how builtin functions come with Roole are written.

Modify Abstract Syntax Trees

Roole code is converted to an abstract syntax tree. You can modify this tree to control what CSS code will be generated.

To tap into this abstract syntax tree, pass a function to roole.on().

roole.on() accepts two arguments, the first argument is a string, denoting in which stage you want to get this tree. Currently the only supported stage is evaluate, which is after evaluation when the abstract syntax tree only contains CSS nodes and has't been prefixed yet. The second argument is the function you pass to.

roole.on('evaluate', function (ast, options) {
  // plugin code
});

The passed function will get two arguments: a JSON object presenting the abstract syntax tree and the options object passed to Roole.compile().

To traverse the abstract syntax tree, you are encouraged to use tree-transformer or tree-transformer-async depending on whether or not nodes are transformed asynchronously.

For example, roole-evaluator uses tree-transformer-async to evaluate nodes asynchronously, and roole-compiler uses tree-transformer to compile abstract syntax trees into strings synchronously.

The returning value is the modified abstract syntax tree. Promises are recognized.

To indicate an error, throw a RooleError object which can be found in the roole-error project. In addition to the error message, pass it the responsible Roole node to indicate the error location.