Skip to content

N
node-sass
Commit 900589fb by Jakob Heuser
Options

Removal of option hashed based success and error callbacks 

This change removes the object hash success/error callbacks in
favor of node style callbacks. This includes README and test
updates, including the removal of two tests that are now
obsolete.

This also updates the CLI code pathway to use the node style
callback.

BREAKING API CHANGE
This removes the success/error option keys as ways to register
callbacks into node-sass. Instead, a function should be passed as
the second parameter for the asyncronous `render` call. It takes
a standard node signature of `error, callback`.
parent 2b7bd560
Showing with 39 additions and 72 deletions
README.md
......@@ -66,7 +66,7 @@ var result = sass.renderSync({
```
### Options
The API for using node-sass has changed, so that now there is only one options hash. In the options hash, some items are optional, others may be mandatory depending on circumstances.
The API for using node-sass has changed. It supports an options hash and a node-style callback function for `render`, and just the options hash for `renderSync`. In the options hash, some items are optional, others may be mandatory depending on circumstances.
#### file
`file` is a `String` of the path to an `scss` file for [libsass] to render. One of this or `data` options are required, for both render and renderSync.
......@@ -74,34 +74,7 @@ The API for using node-sass has changed, so that now there is only one options h
#### data
`data` is a `String` containing the scss to be rendered by [libsass]. One of this or `file` options are required, for both render and renderSync. It is recommended that you use the `includePaths` option in conjunction with this, as otherwise [libsass] may have trouble finding files imported via the `@import` directive.
#### success
`success` is a `Function` to be called upon successful rendering of the scss to css. This option is required but only for the render function. If provided to `renderSync` it will be ignored. The error object take
The callback function is passed a results object, containing the following keys:
* `css` - The compiled CSS. Write this to a file, or serve it out as needed.
* `map` - The source map
* `stats` - An object containing information about the compile. It contains the following keys:
* `entry` - The path to the scss file, or `data` if the source was not a file
* `start` - Date.now() before the compilation
* `end` - Date.now() after the compilation
* `duration` - *end* - *start*
* `includedFiles` - Absolute paths to all related scss files in no particular order.
#### error
`error` is a `Function` to be called upon occurrence of an error when rendering the scss to css. This option is optional, and only applies to the render function.
The callback function is passed an error object, containing the following keys:
* `message` - The error message.
* `line` - The line number of error.
* `column` - The column number of error.
* `status` - The status code.
* `file` - The filename of error. In case `file` option was not set (in favour of `data`), this will reflect the value `stdin`.
Note: If this option is provided to renderSync it will be ignored. In case of `renderSync` the error is thrown to stderr, which is try-catchable. In catch block, the same error object will be received.
#### importer (starting from v2)
#### importer (>= v2.0.0)
`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).
The options passed in to `render` and `renderSync` are available as `this.options` within the `Function`.
......@@ -137,7 +110,7 @@ You must define this option as well as `outFile` in order to generate a source m
#### sourceMapContents
`sourceMapContents` is a `Boolean` flag to determine whether to include `contents` in maps.
### The `render` Callback (starting from v2.1)
### The `render` Callback (>= v3.0.0)
node-sass supports standard node style asynchronous callbacks with the signature of `function(err, result)`. In error conditions, the `error` argument is populated with the error object. In success conditions, the `result` object is populated with an object describing the result of the render call.
#### The Error Object
......@@ -164,23 +137,11 @@ var sass = require('node-sass');
sass.render({
file: '/path/to/myFile.scss',
data: 'body{background:blue; a{color:black;}}',
success: function(result) {
// result is an object: v2 change
console.log(result.css);
console.log(result.stats);
console.log(result.map)
},
error: function(error) { // starting v2.1 error is an Error-typed object
// error is an object: v2 change
console.log(error.message);
console.log(error.status); // changed from code to status in v2.1
console.log(error.line);
console.log(error.column); // new in v2
},
importer: function(url, prev, done) {
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
// this.options contains this options hash, this.callback contains the node-style callback
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
......@@ -193,10 +154,18 @@ sass.render({
},
includePaths: [ 'lib/', 'mod/' ],
outputStyle: 'compressed'
}, function(error, result) {
// starting v2.1 the node-style callback has error (Object) and result (Object)
// the objects are identical to those provided for the error and success keys
// in the options object
}, function(error, result) { // >= v3.0.0
if (error) {
console.log(error.status); // use "code" <= v2.1.0
console.log(error.column); // >= v2.0.0
console.log(error.message);
console.log(error.line);
}
else {
console.log(result.css);
console.log(result.stats);
console.log(result.map);
}
});
// OR
var result = sass.renderSync({
......@@ -209,6 +178,7 @@ var result = sass.renderSync({
// url is the path in import as is, which libsass encountered.
// prev is the previously resolved path.
// done is an optional callback, either consume it or return value synchronously.
// this.options contains this options hash
someAsyncFunction(url, prev, function(result){
done({
file: result.path, // only one of them is required, see section Sepcial Behaviours.
......@@ -230,7 +200,7 @@ console.log(result.stats);
* In the case that both `file` and `data` options are set, node-sass will give precedence to `data` and use `file` to calculate paths in sourcemaps.
### Version information (v2 change)
### Version information (>= v2.0.0)
Both `node-sass` and `libsass` version info is now present in `package.json` and is exposed via `info` method:
......
lib/index.js
......@@ -140,19 +140,14 @@ function getOptions(options, cb) {
options.style = getStyle(options) || 0;
// context object represents node-sass environment
options.context = { options: options };
var error = options.error;
var success = options.success;
options.context = { options: options, callback: cb };
// options.error and options.success are for libsass binding
options.error = function(err) {
var payload = util._extend(new Error(), JSON.parse(err));
if (cb) {
cb.call(options.context, payload, null);
}
if (error) {
error.call(options.context, payload);
options.context.callback.call(options.context, payload, null);
}
};
......@@ -166,10 +161,7 @@ function getOptions(options, cb) {
};
if (cb) {
cb.call(options.context, null, payload);
}
if (success) {
success.call(options.context, payload);
options.context.callback.call(options.context, null, payload);
}
};
......
lib/render.js
......@@ -33,7 +33,7 @@ module.exports = function(options, emitter) {
renderOptions.file = options.src;
}
renderOptions.success = function(result) {
var success = function(result) {
var todo = 1;
var done = function() {
if (--todo <= 0) {
......@@ -86,9 +86,18 @@ module.exports = function(options, emitter) {
emitter.emit('render', result.css);
};
renderOptions.error = function(error) {
var error = function(error) {
emitter.emit('error', chalk.red(JSON.stringify(error, null, 2)));
};
sass.render(renderOptions);
var renderCallback = function(err, result) {
if (err) {
error(err);
}
else {
success(result);
}
};
sass.render(renderOptions, renderCallback);
};
test/spec.js
......@@ -39,15 +39,11 @@ describe('spec', function() {
sass.render({
file: t.src,
includePaths: t.paths,
success: function(result) {
assert.equal(util.normalize(result.css), expected);
done();
},
error: function(err) {
assert(!err);
done();
}
includePaths: t.paths
}, function(error, result) {
assert(!error);
assert.equal(util.normalize(result.css), expected);
done();
});
});
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment