JavaScript API

モジュールを `require` し、Stylusコードの文字列と（オプションの）`options`オブジェクトを指定して `render()` を呼び出すだけです。

Stylusを利用するフレームワークは、より良いエラー報告のために `filename` オプションを渡す必要があります。

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'])

注：デフォルトでは、JavaScriptオブジェクト変数はタプル配列のような式に強制変換されます。たとえば、`{ foo: 'bar', bar: 'baz' }` は式 `(foo 'bar') (bar 'baz')` になります。ハッシュオブジェクトの戻り値を取得する場合は、`raw` を `true` に設定してください。

これらの同じルールは、js 関数の戻り値にも適用されます。

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

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

.define(name, fn)

このメソッドでは、JavaScript で定義された関数を Stylus に提供できます。これらは、JavaScript から C++ へのバインディングのように考えてください。Stylus でできないことがある場合は、JavaScript で定義してください。

この例では、`add()`、`sub()`、`image-width()`、`image-height()` の4つの関数を定義します。これらの関数は `Node` を返す必要があり、このコンストラクタと他のノードは `stylus.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(...)

オプション付きで `render()` メソッドを呼び出すと、`use` オプションに、レンダラーと共に呼び出される関数または関数の配列を指定できます。

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()

依存関係（インポートファイル）の配列を返します。

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

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

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

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

--deps CLI フラグも参照してください。

stylus.resolver([options])

インポートされたファイル内の相対 URL を解決するために使用できるオプションの組み込み関数

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

  });

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

  });

--resolve-url CLI フラグも参照してください。

オプション

- `paths` additional resolution path(s)
- `nocheck` don't check file existence

- `paths` additional resolution path(s)
- `nocheck` don't check file existence

JavaScript API #

.set(setting, value) #

.include(path) #

.import(path) #

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

.define(name, fn) #

.use(fn) #

.deps() #

stylus.resolver([options]) #