JavaScript API

require Stylus模块，用给定的Stylus代码字符串调用render()，以及（可选的）optional对象。

传递filename参数可以利用Stylus框架提供更好的错误报告。

var stylus = require('stylus');

stylus.render(str, { filename: 'nesting.css' }, function(err, css){
  if (err) throw err;
  console.log(css);
});

var stylus = require('stylus');

stylus.render(str, { filename: 'nesting.css' }, function(err, css){
  if (err) throw err;
  console.log(css);
});

我们可以用更渐进的方式实现做一样的事:

var stylus = require('stylus');

stylus(str)
  .set('filename', 'nesting.css')
  .render(function(err, css){
    // logic
  });

var stylus = require('stylus');

stylus(str)
  .set('filename', 'nesting.css')
  .render(function(err, css){
    // logic
  });

.set(setting, value)

应用诸如filename的设置，或导入paths:

.set('filename', __dirname + '/test.styl')
.set('paths', [__dirname, __dirname + '/mixins'])

.set('filename', __dirname + '/test.styl')
.set('paths', [__dirname, __dirname + '/mixins'])

.include(path)

渐进替换.set('paths',...)的就是.include(). 当其他Stylus库（已暴露路径）暴露的时候，这个是理想的选择。

stylus(str)
  .include(require('nib').path)
  .include(process.env.HOME + '/mixins')
  .render(...)

stylus(str)
  .include(require('nib').path)
  .include(process.env.HOME + '/mixins')
  .render(...)

.import(path)

推迟给定path导入，直到计算被执行。下面这个例子基本上跟在Stylus片段中执行@import 'mixins/vendor'一样：

var stylus = require('../')
  , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');

stylus(str)
  .set('filename', __dirname + '/test.styl')
  .import('mixins/vendor')
  .render(function(err, css){
  if (err) throw err;
  console.log(css);
});

var stylus = require('../')
  , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');

stylus(str)
  .set('filename', __dirname + '/test.styl')
  .import('mixins/vendor')
  .render(function(err, css){
  if (err) throw err;
  console.log(css);
});

.define(name, node[, raw])

通过传递一个Node，我们可以定义一个全局变量。当库（该库依赖于其它库可用性）里面暴露某些条件特征的时候，这个就很有用。例如Nib扩展库条件支持node-canvas, 提供图片生成。

但这并不是一直可用的，因此Nib可以定义：

.define('has-canvas', stylus.nodes.false);
.define('some-setting', new stylus.nodes.String('some value'));

.define('has-canvas', stylus.nodes.false);
.define('some-setting', new stylus.nodes.String('some value'));

如果可能，Stylus也会转换JavaScript值为Stylus值，例如:

.define('string', 'some string')
.define('number', 15.5)
.define('some-bool', true)
.define('list', [1,2,3])
.define('list', [1,2,[3,4,[5,6]]])
.define('list', { foo: 'bar', bar: 'baz' })
.define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])

.define('string', 'some string')
.define('number', 15.5)
.define('some-bool', true)
.define('list', [1,2,3])
.define('list', [1,2,[3,4,[5,6]]])
.define('list', { foo: 'bar', bar: 'baz' })
.define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])

Note: In default, The JavaScript object variable will coerce to a tuple-array-like expression. For example { foo: 'bar', bar: 'baz' } would become the expression (foo 'bar') (bar 'baz'). If you want to get a hash object return, please set raw to true.

下面是一些规则应用在js函数返回值上：

.define('get-list', function(){
  return ['foo', 'bar', 'baz'];
})

.define('get-list', function(){
  return ['foo', 'bar', 'baz'];
})

.define(name, fn)

该方法允许你向Stylus提供JavaScript定义的函数。正如想到JavaScript用C++绑定。当有一些事情无法用Stylus完成的时候，就在JavaScript中定义它。

下面这个例子，我们定义了4个函数：add(), sub(), image-width(), image-height(). 这些函数必须返回一个Node, 通过stylus.nodes该构造以及其它nodes都可以了。

var stylus = require('../')
  , nodes = stylus.nodes
  , utils = stylus.utils
  , fs = require('fs');

function add(a, b) {
  return a.operate('+', b);
}

function sub(a, b) {
  return a.operate('-', b);
}

function imageDimensions(img) {
  // assert that the node (img) is a String node, passing
  // the param name for error reporting
  utils.assertType(img, 'string', 'img');
  var path = img.val;

  // Grab bytes necessary to retrieve dimensions.
  // if this was real you would do this per format,
  // instead of reading the entire image :)
  var data = fs.readFileSync(__dirname + '/' + path);

  // GIF
  // of course you would support.. more :)
  if ('GIF' == data.slice(0, 3).toString()) {
    var w = data.slice(6, 8)
      , h = data.slice(8, 10);
    w = w[1] << 8 | w[0];
    h = h[1] << 8 | h[0];
  }

  return [w, h];
}

function imageWidth(img) {
  return new nodes.Unit(imageDimensions(img)[0]);
}

function imageHeight(img) {
  return new nodes.Unit(imageDimensions(img)[1]);
}

stylus(str)
  .set('filename', 'js-functions.styl')
  .define('add', add)
  .define('sub', sub)
  .define('image-width', imageWidth)
  .define('image-height', imageHeight)
  .render(function(err, css){
    if (err) throw err;
    console.log(css);
  });

var stylus = require('../')
  , nodes = stylus.nodes
  , utils = stylus.utils
  , fs = require('fs');

function add(a, b) {
  return a.operate('+', b);
}

function sub(a, b) {
  return a.operate('-', b);
}

function imageDimensions(img) {
  // assert that the node (img) is a String node, passing
  // the param name for error reporting
  utils.assertType(img, 'string', 'img');
  var path = img.val;

  // Grab bytes necessary to retrieve dimensions.
  // if this was real you would do this per format,
  // instead of reading the entire image :)
  var data = fs.readFileSync(__dirname + '/' + path);

  // GIF
  // of course you would support.. more :)
  if ('GIF' == data.slice(0, 3).toString()) {
    var w = data.slice(6, 8)
      , h = data.slice(8, 10);
    w = w[1] << 8 | w[0];
    h = h[1] << 8 | h[0];
  }

  return [w, h];
}

function imageWidth(img) {
  return new nodes.Unit(imageDimensions(img)[0]);
}

function imageHeight(img) {
  return new nodes.Unit(imageDimensions(img)[1]);
}

stylus(str)
  .set('filename', 'js-functions.styl')
  .define('add', add)
  .define('sub', sub)
  .define('image-width', imageWidth)
  .define('image-height', imageHeight)
  .render(function(err, css){
    if (err) throw err;
    console.log(css);
  });

为了进一步的参考（直到本文档全部结束），请看下面的文件：

- `lib/nodes/*`
- `lib/utils.js`

- `lib/nodes/*`
- `lib/utils.js`

.use(fn)

当被调用时，给定fn被渲染器调用，允许所有上面的方法被使用。这允许插件轻易地暴露自己，定义函数，路径等。

var mylib = function(style){
  style.define('add', add);
  style.define('sub', sub);
};

stylus(str)
  .use(mylib)
  .render(...)

var mylib = function(style){
  style.define('add', add);
  style.define('sub', sub);
};

stylus(str)
  .use(mylib)
  .render(...)

When calling the render() method with options, the use option can be given a function or array of functions to be invoked with the renderer.

stylus.render(str, { use: mylib }, function(err, css){
  if (err) throw err;
  console.log(css);
});

stylus.render(str, { use: mylib }, function(err, css){
  if (err) throw err;
  console.log(css);
});

.deps()

Returns array of dependencies (import files):

stylus('@import "a"; @import "b"')
  .deps();

// => ['a.styl', 'b.styl']

stylus('@import "a"; @import "b"')
  .deps();

// => ['a.styl', 'b.styl']

stylus.resolver([options])

Optional built-in function which may be used to resolve relative urls inside imported files:

stylus(str)
  .define('url', stylus.resolver())
  .render(function(err, css) {

  });

stylus(str)
  .define('url', stylus.resolver())
  .render(function(err, css) {

  });

JavaScript API #

.set(setting, value) #

.include(path) #

.import(path) #

.define(name, node[, raw]) #

.define(name, fn) #

.use(fn) #

.deps() #

stylus.resolver([options]) #