stylus-source 0.23.0 → 0.24.0

data/vendor/docs/functions.md

@@ -1,197 +0,0 @@
-
-## Functions
-
- Stylus features powerful in-language function definitions. Function definitions appear identical to mixins; however, functions may return a value.
-
-### Return Values
-
- Let's try a trivial example: creating a function that adds two numbers.
-
-    add(a, b)
-      a + b
-
- We can then use this function in conditions, in property values, etc.
- 
-     body 
-       padding add(10px, 5)
-
- Rendering:
-     
-     body {
-       padding: 15px;
-     }
-
-### Argument Defaults
-
- Optional arguments may default to a given expression. With Stylus we may even default arguments to earlier arguments! 
- 
- For example:
- 
- 
-     add(a, b = a)
-       a + b
-
-     add(10, 5)
-     // => 15
-     
-     add(10)
-     // => 20
-
-**Note:** Since argument defaults are assignments, we can also use function calls for defaults:
-
-     add(a, b = unit(a, px))
-       a + b
-
-### Function Bodies
-
- We can take our simple `add()` function further. Let's casting all units passed as `px` via the `unit()` built-in. It reassigns each argument, and provides a unit-type string (or identifier), which ignores unit conversion.
- 
-     add(a, b = a)
-       a = unit(a, px)
-       b = unit(b, px)
-       a + b
-
-     add(15%, 10deg)
-     // => 25
-
-### Multiple Return Values
-
- Stylus functions can return several values—just as you can assign several values to a variable. 
- 
- For example, the following is a valid assignment:
- 
-       sizes = 15px 10px
-     
-       sizes[0]
-       // => 15px 
-
-Similarly, we may return several values:
-
-       sizes()
-         15px 10px
-
-       sizes()[0]
-       // => 15px
-
-One slight exception is when return values are identifiers. For example, the following looks like a property assignment to Stylus (since no operators are present):
-
-     swap(a, b)
-       b a
-
-To disambiguate, we can either wrap with parentheses, or use the `return` keyword:
-
-      swap(a, b)
-        (b a)
-
-      swap(a, b)
-        return b a
-
-### Conditionals
-
- Let's say we want to create a function named `stringish()` to determine whether the argument can be transformed to a string. We check if `val` is a string, or an ident (which is string-like). Because undefined identifiers yield themselves as the value, we may compare them to themselves as shown below (where `yes` and `no` are used in place of `true` and `false`):
- 
- 
-     stringish(val)
-       if val is a 'string' or val is a 'ident'
-         yes
-       else
-         no
-
-Usage:
-
-     stringish('yay') == yes
-     // => true
-   
-     stringish(yay) == yes
-     // => true
-   
-     stringish(0) == no
-     // => true
-
-__note__: `yes` and `no` are not boolean literals. They are simply undefined identifiers in this case.
-
-Another example:
-
-    compare(a, b)
-      if a > b
-        higher
-      else if a < b
-        lower
-      else
-        equal
-
-Usage:
-
-    compare(5, 2)
-    // => higher
-
-    compare(1, 5)
-    // => lower
-
-    compare(10, 10)
-    // => equal
-
-### Aliasing
-
-  To alias a function, simply assign a function's name to a new identifier. For example, our `add()` function could be aliased as `plus()`, like so:
-  
-      plus = add
-      
-      plus(1, 2)
-      // => 3
-
-### Variable Functions
-
-  In the same way that we can "alias" a function, we can pass a function as well. Here, our `invoke()` function accepts a function, so we can pass it `add()` or `sub()`.
-
-    invoke(a, b, fn)
-      fn(a, b)
-
-    add(a, b)
-      a + b
-
-    body
-      padding invoke(5, 10, add)
-      padding invoke(5, 10, sub)
-
-Yielding:
-
-    body {
-      padding: 15;
-      padding: -5;
-    }
-
-### arguments
-
- The `arguments` local is available to all function bodies, and contains all the arguments passed. 
- 
- For example:
- 
-     sum()
-       n = 0
-       for num in arguments
-         n = n + num
-
-     sum(1,2,3,4,5)
-     // => 15
-
-### Hash Example
-
- Below we define the `get(hash, key)` function, which returns the
- value of `key` (or `null`). We iterate each `pair` in `hash`, returning the pair's second node when the first (the `key`) matches. 
-
-      get(hash, key)
-        return pair[1] if pair[0] == key for pair in hash
-
-As demonstrated below, in-language functions—paired with robust Stylus expressions—can provide great flexibility:
-      
-      hash = (one 1) (two 2) (three 3)
-      
-      get(hash, two)
-      // => 2
-
-      get(hash, three)
-      // => 3
-
-      get(hash, something)
-      // => null

data/vendor/docs/functions.url.md

@@ -1,32 +0,0 @@
-## Data URI Image Inlining
-
-Stylus is bundled with an optional function named `url()`, which replaces the literal `url()` calls (and conditionally inlines them using base64 [Data URIs](http://en.wikipedia.org/wiki/Data_URI_scheme)).
-
-### Example
-
-The function itself is available via `require('stylus').url`. It accepts an `options` object, returning a function that Stylus calls internally when it sees `url()`.
-
-The `.define(name, callback)` method assigned a JavaScript function that can be called from Stylus source. In this case, since our images are in `./css/images`,  we can ignore the `paths` option (by default image lookups are performed relative to the file being rendered).  But if desired, this behavior can be altered:
-
-      stylus(str)
-        .set('filename', __dirname + '/css/test.styl')
-        .define('url', stylus.url())
-        .render(function(err, css){
-    
-        });
-
-For example, imagine our images live in `./public/images`.  We want to use `url(images/tobi.png)`.  We could pass `paths` our public directory, so that it becomes part of the lookup process. 
-
-Likewise, if instead we wanted `url(tobi.png)`, we could pass `paths: [__dirname + '/public/images']`.
-
-      stylus(str)
-        .set('filename', __dirname + '/css/test.styl')
-        .define('url', stylus.url({ paths: [__dirname + '/public'] }))
-        .render(function(err, css){
-          
-        });
-  
-### Options
-
-  - `limit` bytesize limit defaulting to 30Kb (30000)
-  - `paths` image resolution path(s)

data/vendor/docs/gedit.md

@@ -1,24 +0,0 @@
-## gedit language-spec
-
- Stylus ships with a temporary version of `styl.lang` for [GtkSourceView](http://live.gnome.org/GtkSourceView), based off [Yanekk](https://github.com/yanekk)'s [work](https://github.com/gmate/gmate/blob/master/lang-specs/scss.lang) on `scss.lang`.
- 
- ![Stylus Language Specification for GtkSourceView](http://i.imgur.com/uBppL.png))
-
- This is a start and provides a basic [language spec](http://live.gnome.org/Gedit/NewLanguage) for GtkSourceView editors such as [gedit](http://projects.gnome.org/gedit/).
-
- **Installation Steps**
- 
- Download `styl.lang` to your local `language-specs` folder:
- 
-    mkdir -p ~/.local/share/gtksourceview-2.0/language-specs/ && wget https://raw.github.com/LearnBoost/stylus/master/editors/gedit/styl.lang -O ~/.local/share/gtksourceview-2.0/language-specs/styl.lang
-
- Update the MIME database and enjoy Stylus syntax in gedit!
- 
-    cd ~/.local/share
-    update-mime-database mime
- 
- This is much more enjoyable than having gedit recognize your `.styl` files as Apache Confs!
- 
- ---
- 
- **Have a sweet tooth?**  Add more icing to gedit with gedit-icing: [https://github.com/niftylettuce/gedit-icing](https://github.com/niftylettuce/gedit-icing)

data/vendor/docs/import.md

@@ -1,75 +0,0 @@
-## Import
-
- Stylus supports both literal __@import__ for CSS, as well as dynamic importing of other Stylus sheets.
-
-### Literal CSS
-
-  Any filename with the extension `.css` will become a literal. For example:
-  
-     @import "reset.css"
-
-Render the literal CSS __@import__ shown below:
-
-     @import "reset.css"
-
-### Stylus Import
-
- When using __@import__ without the `.css` extension, it's assumed to be a Stylus sheet (e.g., `@import "mixins/border-radius"`).
-
- __@import__ works by iterating an array of directories, and checking if this file lives in any of them (similar to node's `require.paths`). This array defaults to a single path, which is derived from the `filename` option's `dirname`. So, if your filename is `/tmp/testing/stylus/main.styl`, then import will look in `/tmp/testing/stylus/`.
- 
- __@import__ also supports index styles. This means when you `@import blueprint`, it will resolve **either** `blueprint.styl` **or** `blueprint/index.styl`.  This is really useful for libraries that want to expose all their features, while still allowing feature subsets to be imported. 
- 
- For example, a common lib structure might be:
-
-    ./tablet
-      |-- index.styl 
-      |-- vendor.styl 
-      |-- buttons.styl 
-      |-- images.styl 
-
- In the example below, we set the `paths` options to provide additional paths to Stylus. Within `./test.styl`, we could then `@import "mixins/border-radius"`, or `@import "border-radius"` (since `./mixins` is exposed to Stylus).
-
-      /**
-       * Module dependencies.
-       */
-
-      var stylus = require('../')
-        , str = require('fs').readFileSync(__dirname + '/test.styl', 'utf8');
-
-      var paths = [
-          __dirname
-        , __dirname + '/mixins'
-      ];
-
-      stylus(str)
-        .set('filename', __dirname + '/test.styl')
-        .set('paths', paths)
-        .render(function(err, css){
-          if (err) throw err;
-          console.log(css);
-        });
-
-### JavaScript Import API
-
- When using the `.import(path)` method, these imports are deferred until evaluation:
- 
-       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);
-       });
-
- The following statement...
- 
-     @import 'mixins/vendor'
-
-...is equivalent to...
-
-     .import('mixins/vendor') 
- 

data/vendor/docs/interpolation.md

@@ -1,55 +0,0 @@
-
-## Interpolation
-
-  Stylus supports interpolation by using the `{}` characters to surround an expression, which then becomes part of the identifier. For example, `-webkit-{'border' + '-radius'}` evaluates to `-webkit-border-radius`.
-
- A great example use-case for this is expanding properties with vendor prefixes.
-
-      vendor(prop, args)
-        -webkit-{prop} args
-        -moz-{prop} args
-        {prop} args
-
-      border-radius()
-        vendor('border-radius', arguments)
-      
-      box-shadow()
-        vendor('box-shadow', arguments)
-
-      button
-        border-radius 1px 2px / 3px 4px
-
-Yields:
-
-      button {
-        -webkit-border-radius: 1px 2px / 3px 4px;
-        -moz-border-radius: 1px 2px / 3px 4px;
-        border-radius: 1px 2px / 3px 4px;
-      }
-
-## Selector Interpolation
-
- Interpolation works with selectors as well. For example, we may iterate to assign the `height` property for the first 5 rows in a table, as shown below:
-
-    table
-      for row in 1 2 3 4 5
-        tr:nth-child({row})
-          height: 10px * row
-
-Yields:
-
-    table tr:nth-child(1) {
-      height: 10px;
-    }
-    table tr:nth-child(2) {
-      height: 20px;
-    }
-    table tr:nth-child(3) {
-      height: 30px;
-    }
-    table tr:nth-child(4) {
-      height: 40px;
-    }
-    table tr:nth-child(5) {
-      height: 50px;
-    }

data/vendor/docs/introspection.md

@@ -1,38 +0,0 @@
-
-## Introspection API
-
- Stylus supports an introspection API. This allows mixins and functions to reflect relative to the caller, etc.
-
-
-## mixin
-
-  The `mixin` local variable is automatically assigned within function bodies.
-  It contains the string `root` if the function was called at the root
-  level, or `block` indicating otherwise, and finally `false` if the invoked function expects a return value.
-
-  In the following example, we define `reset()` to alter its behaviour depending on whether it's mixed into root, into another block, or into a return value, as used in the `foo` property below:
-
-      reset()
-        if mixin == 'root'
-          got
-            root true
-        else if mixin
-          got 'a mixin'
-        else
-          'not a mixin'
-
-      reset()
-
-      body
-        reset()
-        foo reset()
-
-Compiles to:
-
-        got {
-          root: true;
-        }
-        body {
-          foo: "not a mixin";
-          got: "a mixin";
-        }

data/vendor/docs/iteration.md

@@ -1,102 +0,0 @@
-
-## Iteration
-
- Stylus allows you to iterate expressions via the `for/in` construct, taking the form of:
- 
-      for <val-name> [, <key-name>] in <expression>
-
-For example:
-
-    body
-      for num in 1 2 3
-        foo num
-
-Yields:
-
-      body {
-        foo: 1;
-        foo: 2;
-        foo: 3;
-      }
-
-The example below shows how to use the `<key-name>`:
-
-      body
-        fonts = Impact Arial sans-serif
-        for font, i in fonts
-          foo i font
-
-Yielding:
-
-        body {
-          foo: 0 Impact;
-          foo: 1 Arial;
-          foo: 2 sans-serif;
-        }
-
-### Mixins
-
- We can use iteration within mixins to produce powerful functionality. For example, we can apply expression pairs as properties using interpolation and iteration. 
- 
- Below we define `apply()`, conditionally utilizing all the `arguments` so that comma-delimited _and_ expression lists are supported:
- 
-     apply(props)
-       props = arguments if length(arguments) > 1
-       for prop in props
-         {prop[0]} prop[1]
-
-     body
-       apply(one 1, two 2, three 3)
-
-     body
-       list = (one 1) (two 2) (three 3)
-       apply(list)
-
-### Functions
-
- Stylus functions may also contain for-loops. Below are some example use-cases:
-
-Sum:
-
-      sum(nums)
-        sum = 0
-        for n in nums
-          sum += n
-
-      sum(1 2 3)
-      // => 6
-
-join:
-
-      join(delim, args)
-        buf = ''
-        for arg, index in args
-          if index
-            buf += delim + arg
-          else
-            buf += arg
-
-      join(', ', foo bar baz)
-      // => "foo, bar, baz"
-
-### Postfix
-
- Much like `if` / `unless` may be utilized post-statement, the same can be done with `for`. Below are the same examples as above utilizing the postfix syntax:
- 
-       sum(nums)
-         sum = 0
-         sum += n for n in nums
-
-
-       join(delim, args)
-         buf = ''
-         buf += i ? delim + arg : arg for arg, i in args
-
- We can also __return__ from within a loop, below is an example returning the
- number when `n % 2 == 0` evaluates to __true__.
- 
-     first-even(nums)
-       return n if n % 2 == 0 for n in nums
-
-     first-even(1 3 5 5 6 3 2)
-     // => 6

data/vendor/docs/js.md

@@ -1,157 +0,0 @@
-## JavaScript API
-
-Simply `require` the module, and call `render()` with the given string of Stylus code, and (optional) `options` object. 
-
-Frameworks utilizing Stylus should pass the `filename` option to provide better error reporting.
-
-    var stylus = require('stylus');
-
-    stylus.render(str, { filename: 'nesting.css' }, function(err, css){
-      if (err) throw err;
-      console.log(css);
-    });
-
-We can also do the same thing in a more progressive manner:
-
-    var stylus = require('stylus');
-
-    stylus(str)
-      .set('filename', 'nesting.css')
-      .render(function(err, css){
-        // logic
-      });
-
-### .set(setting, value)
-
- Apply a setting such as a `filename`, or import `paths`:
- 
-     .set('filename', __dirname + '/test.styl')
-     .set('paths', [__dirname, __dirname + '/mixins'])
-
-### .include(path)
-
-  A progressive alternative to `.set('paths',...)` is `.include()`.  This is ideal when exposing external Stylus libraries which expose a path.
-  
-    stylus(str)
-      .include(require('nib').path)
-      .include(process.env.HOME + '/mixins')
-      .render(...)
-
-### .import(path)
-
-Defer importing of the given `path` until evaluation is performed. The example below is essentially the same as doing `@import 'mixins/vendor'` within your Stylus sheet.
-
-      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)
-
- By passing a `Node`, we may define a global variable. This is useful when exposing conditional features within your library depending on the availability of another. For example the **Nib** extension library conditionally supports node-canvas, providing image generation. 
- 
- However, this is not always available, so Nib may define:
- 
-     .define('has-canvas', stylus.nodes.false);
-     .define('some-setting', new stylus.nodes.String('some value'));
-
- Stylus also casts JavaScript values to their Stylus equivalents when possible. Here are a few examples:
-
-     .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'])
-
-  These same rules apply to return values in js functions as well:
-
-     .define('get-list', function(){
-       return ['foo', 'bar', 'baz'];
-     })
-
-### .define(name, fn)
-
- This method allows you to provide a JavaScript-defined function to Stylus. Think of these as you would JavaScript-to-C++ bindings. When there's something you cannot do in Stylus, define it in JavaScript!
-
-In this example, we define four functions: `add()`, `sub()`, `image-width()`, and `image-height()`. These functions must return a `Node`, this constructor and the other nodes are available via `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);
-        });
-
- For further reference (until documentation is complete) please see the following files:
- 
-   - `lib/nodes/*`
-   - `lib/utils.js`
-
-### .use(fn)
-
-  When called, the given `fn` is invoked with the renderer, allowing all of the methods above to be used. This allows for plugins to easily expose themselves, defining functions, paths etc.
-
-    var mylib = function(style){
-      style.define('add', add);
-      style.define('sub', sub);
-    };
-
-    stylus(str)
-      .use(mylib)
-      .render(...)