stylus-source 0.15.4 → 0.17.0

data/vendor/docs/functions.url.md

@@ -0,0 +1,30 @@
+## 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`, and 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 we have our images in `./css/images` then we can ignore the `paths` option, since image lookups are performed relative to the file being rendered (by default), we may alter this with the option.
+
+      stylus(str)
+        .set('filename', __dirname + '/css/test.styl')
+        .define('url', stylus.url())
+        .render(function(err, css){
+    
+        });
+
+For example if our images live in `./public/images` and we wish to use `url(images/tobi.png)`, we can pass `paths` with our public directory, which will become part of the lookup process. Like-wise if we wanted `url(tobi.png)` instead, we would 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

@@ -0,0 +1,24 @@
+## 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

@@ -0,0 +1,73 @@
+## 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"
+
+will render to the literal css __@import__ shown below:
+
+     @import "reset.css"
+
+### Stylus Import
+
+ When using __@import__ without the `.css` extension, it is assumed to be a Stylus sheet, for example `@import "mixins/border-radius"`.
+
+ __@import__ works by iterating an array of directories, and seeing 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, meaning if you `@import blueprint`, it will resolve either `blueprint.styl` or `blueprint/index.styl`, useful for libraries to expose all of their features, but still allow a subset of the library 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 are essentially equivalent:
+ 
+     @import 'mixins/vendor'
+
+and
+
+     .import('mixins/vendor') 
+ 

data/vendor/docs/interpolation.md

@@ -0,0 +1,55 @@
+
+## Interpolation
+
+  Stylus supports interpolation by using the `{}` characters to surround an expression, which then becomes part of the identifier. For example `-webkit-{'border' + '-radius'}` would evaluate 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
+
+yielding:
+
+      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 while assigning 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
+
+yielding:
+
+    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

@@ -0,0 +1,39 @@
+
+## Introspection API
+
+ Stylus supports an introspection API, allowing mixins and functions to reflect relative to the caller etc.
+
+
+## mixin
+
+  The `mixin` local variable is automatically assigned within function bodies,
+  containing the string "root" indicating the function is called at the root
+  level, or "block" indicating otherwise, and finally `false` if the function
+  is invoked expecting a return value.
+
+  In the following example we define `reset()` altering its behaviour when mixed in to root, another block, or 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

@@ -0,0 +1,100 @@
+
+## 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 may utilize 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

@@ -0,0 +1,136 @@
+## 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 setting `paths` via `.set()`, which 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" extensions 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(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 you have something you cannot do within Stylus, you define it in JavaScript.
+
+In our 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 reference 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(...)

data/vendor/docs/keyframes.md

@@ -0,0 +1,120 @@
+
+## @keyframes
+
+ Stylus supports the `@keyframes` at-rule, which is converted to `@-webkit-keyframes` when compiled:
+
+
+     @keyframes pulse
+       0%
+         background-color red
+         opacity 1.0
+         -webkit-transform scale(1.0) rotate(0deg)
+       33%
+         background-color blue
+         opacity 0.75
+         -webkit-transform scale(1.1) rotate(-5deg)
+       67%
+         background-color green
+         opacity 0.5
+         -webkit-transform scale(1.1) rotate(5deg)
+       100%
+         background-color red
+         opacity 1.0
+         -webkit-transform scale(1.0) rotate(0deg)
+
+yielding:
+
+      @-webkit-keyframes pulse {
+        0% {
+          background-color: red;
+          opacity: 1;
+          -webkit-transform: scale(1) rotate(0deg);
+        }
+
+        33% {
+          background-color: blue;
+          opacity: 0.75;
+          -webkit-transform: scale(1.1) rotate(-5deg);
+        }
+
+        67% {
+          background-color: green;
+          opacity: 0.5;
+          -webkit-transform: scale(1.1) rotate(5deg);
+        }
+
+        100% {
+          background-color: red;
+          opacity: 1;
+          -webkit-transform: scale(1) rotate(0deg);
+        }
+
+      }
+
+## Expansion
+
+ By utilizing `@keyframes` your rules are automatically expanded to the vendor prefixes defined by the `vendors` variable, defaulting to `webkit moz official`. This means we can alter it at any time for the expansion to take effect immediately. For example consider the following
+
+    @keyframes foo {
+      from {
+        color: black
+      }
+      to {
+        color: white
+      }
+    }
+
+expands to our two default vendors and the official syntax:
+
+    @-moz-keyframes foo {
+      0% {
+        color: #000;
+      }
+
+      100% {
+        color: #fff;
+      }
+    }
+    @-webkit-keyframes foo {
+      0% {
+        color: #000;
+      }
+
+      100% {
+        color: #fff;
+      }
+    }
+    @keyframes foo {
+      0% {
+        color: #000;
+      }
+
+      100% {
+        color: #fff;
+      }
+    }
+
+if we wanted to limit to the official syntax only, simply alter `vendors`:
+
+    vendors = official
+
+    @keyframes foo {
+      from {
+        color: black
+      }
+      to {
+        color: white
+      }
+    }
+
+yielding:
+
+    @keyframes foo {
+      0% {
+        color: #000;
+      }
+
+      100% {
+        color: #fff;
+      }
+    }

data/vendor/docs/kwargs.md

@@ -0,0 +1,35 @@
+
+## Keyword Arguments
+
+ Stylus supports keyword arguments, or "kwargs", allowing you to key
+ arguments by their associated parameter name.
+
+ The examples shown below are functionally equivalent, however we can
+ place keyword arguments anywhere within the list. The remaining arguments
+ that are _not_ keyed will be applied to the parameters that have not
+ been satisfied.
+
+      body {
+        color: rgba(255, 200, 100, 0.5);
+        color: rgba(red: 255, green: 200, blue: 100, alpha: 0.5);
+        color: rgba(alpha: 0.5, blue: 100, red: 255, 200);
+        color: rgba(alpha: 0.5, blue: 100, 255, 200);
+      }
+
+ yielding:
+ 
+       body {
+         color: rgba(255,200,100,0.5);
+         color: rgba(255,200,100,0.5);
+         color: rgba(255,200,100,0.5);
+         color: rgba(255,200,100,0.5);
+       }
+
+
+ To see what parameters a function or mixin accept, use the `p()` function:
+ 
+    p(rgba)
+
+ yielding:
+
+    inspect: rgba(red, green, blue, alpha)

data/vendor/docs/literal.md

@@ -0,0 +1,16 @@
+## Literal CSS
+
+ If for any reason Stylus cannot accommodate a specific need, you can always resort to literal css via `@css`:
+ 
+     
+     @css {
+       body {
+         font: 14px;
+       }
+     }
+
+compiling to:
+
+    body {
+      font: 14px;
+    }

data/vendor/docs/media.md

@@ -0,0 +1,18 @@
+
+## @media
+
+ The `@media` works just as it does within regular css, however with Stylus block notation:
+
+     @media print
+       #header
+       #footer
+         display none
+
+yielding:
+
+      @media print {
+        #header,
+        #footer {
+          display: none;
+        }
+      }