stylus-source 0.15.4 → 0.17.0

data/vendor/docs/conditionals.md

@@ -0,0 +1,107 @@
+
+## Conditionals
+
+ Conditionals provide control flow to a language which is otherwise static, providing conditional imports, mixins, functions, and more. The examples below are simply examples, and not recommended :)
+
+### if / else if / else
+
+ The `if` conditional works as you would expect, simply accepting an expression, evaluating the following block when `true`. Along with `if` are the typical `else if` and `else` tokens, acting as fallbacks.
+ 
+ The example below would conditionally overload the `padding` property, swapping it for margin.
+
+    overload-padding = true
+
+    if overload-padding
+      padding(y, x)
+        margin y x
+
+    body
+      padding 5px 10px
+
+Another example:
+
+    box(x, y, margin = false)
+      padding y x
+      if margin
+        margin y x
+
+    body
+      box(5px, 10px, true)
+
+Another `box()` helper:
+
+    box(x, y, margin-only = false)
+      if margin-only
+        margin y x
+      else
+        padding y x
+
+### unless
+
+ For users familiar with the ruby programming language, we have the `unless` conditional, which is essentially the opposite of `if`, essentially `if (!(expr))`.
+
+In the example below, if `disable-padding-override` is undefined or `false` padding will be overridden, displaying `margin` instead. However when `true` padding will remain outputting `padding 5px 10px` as expected.
+
+     disable-padding-override = true
+
+     unless disable-padding-override is defined and disable-padding-override
+       padding(x, y)
+         margin y x
+
+     body
+       padding 5px 10px
+
+### Postfix Conditionals
+
+  Stylus supports postfix conditionals, meaning the `if` and `unless` act as operators, evaluating the left-hand operand, when the right-hand expression is truthy.
+  
+  
+  For example let's define `negative()`, performing some basic type checking. Below we use block-style conditionals:
+  
+      negative(n)
+        unless n is a 'unit'
+          error('invalid number')
+        if n < 0
+          yes
+        else
+          no
+
+  Next we utilize postfix conditionals to keep our function terse.
+
+      negative(n)
+        error('invalid number') unless n is a 'unit'
+        return yes if n < 0
+        no
+
+  Of course we could take this further, and utilize `n < 0 ? yes : no`, or simply stick with booleans, and use only `n < 0`.
+
+  Postfix conditionals may be applied to most single-line statements, for example `@import`, `@charset`, mixins, and of course properties as shown below:
+  
+  
+      pad(types = margin padding, n = 5px)
+        padding unit(n, px) if padding in types
+        margin unit(n, px) if margin in types
+
+      body
+        pad()
+
+      body
+        pad(margin)
+
+      body
+        apply-mixins = true
+        pad(padding, 10) if apply-mixins
+
+yielding:
+
+      body {
+        padding: 5px;
+        margin: 5px;
+      }
+      body {
+        margin: 5px;
+      }
+      body {
+        padding: 10px;
+      }
+

data/vendor/docs/css-style.md

@@ -0,0 +1,77 @@
+
+## CSS Style
+
+ Stylus transparently supports a regular css-style syntax, meaning you do not need to use an alternative parser, or specify that a certain file is using a specific style.
+
+### Example
+
+ Below is a small style using the indented approach:
+ 
+     border-radius()
+       -webkit-border-radius arguments
+       -moz-border-radius arguments
+       border-radius arguments
+
+     body a
+       font 12px/1.4 "Lucida Grande", Arial, sans-serif
+       background black
+       color #ccc
+
+     form input
+       padding 5px
+       border 1px solid
+       border-radius 5px
+
+ Since braces, colons, and semi-colons are optional, we could write this example just as we would with normal css:
+ 
+     border-radius() {
+       -webkit-border-radius: arguments;
+       -moz-border-radius: arguments;
+       border-radius: arguments;
+     }
+
+     body a {
+       font: 12px/1.4 "Lucida Grande", Arial, sans-serif;
+       background: black;
+       color: #ccc;
+     }
+
+     form input {
+       padding: 5px;
+       border: 1px solid;
+       border-radius: 5px;
+     }
+
+ Since we may mix and match the two variants, the following is valid as well:
+ 
+     border-radius()
+       -webkit-border-radius: arguments;
+       -moz-border-radius: arguments;
+       border-radius: arguments;
+
+     body a {
+       font: 12px/1.4 "Lucida Grande", Arial, sans-serif;
+       background: black;
+       color: #ccc;
+     }
+
+     form input
+       padding: 5px;
+       border: 1px solid;
+       border-radius: 5px;
+
+ Variables, functions, mixins, and all of the other features that Stylus provides still work as expected:
+ 
+     main-color = white
+     main-hover-color = black
+
+     body a {
+       color: main-color;
+       &:hover { color: main-hover-color; }
+     }
+
+     body a { color: main-color; &:hover { color: main-hover-color; }}
+
+ There are currently a few exceptions to this rule, since the two styles may be mixed and matched some indentation rules still apply. So although not _every_ plain-css stylesheet will work without modification this feature still allows those who prefer css syntax may still utilize the other powerful features provided by Stylus.
+ 
+

data/vendor/docs/error-reporting.md

@@ -0,0 +1,50 @@
+
+## Error Reporting
+
+ Stylus has fantastic error reporting built in for syntax, parse, and evaluation errors, complete with stack traces, line numbers, and filenames.
+
+### Parse Error
+
+Parse error example:
+
+     body
+       form input
+         == padding 5px
+
+yielding:
+
+     Error: /Users/tj/Projects/stylus/testing/test.styl:4
+       3: '  form input'
+       4: '    == padding 5px'
+
+     illegal unary ==
+
+### Evaluation Error
+
+ This "runtime" or evaluation error is caused due to passing a string to `border-radius()` instead of the expected `Unit` by using our helper `ensure(n, 'unit')`.
+
+      ensure(val, type)
+        unless val is a type
+          error('expected a ' + type + ', but got ' + typeof(val))
+
+      border-radius(n)
+        ensure(n, 'unit')
+        -webkit-border-radius n
+        -moz-border-radius n
+        border-radius n
+
+      body
+        border-radius '5px'
+
+yielding:
+
+      Error: /Users/tj/Projects/stylus/examples/error.styl:12
+        11: ''
+        12: 'body'
+        13: '  border-radius \'5px\''
+        14: ''
+
+      expected a unit, but got string
+          at ensure() (/Users/tj/Projects/stylus/examples/error.styl:2)
+          at border-radius() (/Users/tj/Projects/stylus/examples/error.styl:5)
+          at "body" (/Users/tj/Projects/stylus/examples/error.styl:10)

data/vendor/docs/escape.md

@@ -0,0 +1,27 @@
+
+## Escaping
+
+ Stylus allows you to escape characters, effectively turning them into identifiers, so that they can be rendered as literals. For example:
+
+     body
+       padding 1 \+ 2
+
+will compile to:
+
+     body {
+       padding: 1 + 2;
+     }
+
+
+Not that Stylus requires that `/` is parenthesized when used in a property:
+
+    body
+      font 14px/1.4
+      font (14px/1.4)
+
+yields:
+
+    body {
+      font: 14px/1.4;
+      font: 10px;
+    }

data/vendor/docs/executable.md

@@ -0,0 +1,159 @@
+
+## Stylus Executable
+
+Stylus ships with the `stylus` executable for converting stylus to css.
+
+      Usage: stylus [options] [command] [< in [> out]]
+                    [file|dir ...]
+
+      Commands:
+
+        help <prop>     Opens help info for <prop> in
+                        your default browser. (osx only)
+
+      Options:
+
+        -u, --use <path>        Utilize the stylus plugin at <path>
+        -i, --interactive       Start interactive REPL
+        -w, --watch             Watch file(s) for changes and re-compile
+        -o, --out <dir>         Output to <dir> when passing files
+        -C, --css <src> [dest]  Convert css input to stylus
+        -I, --include <path>    Add <path> to lookup paths
+        -c, --compress          Compress css output
+        -d, --compare           Display input along with output
+        -f, --firebug           Emits debug infos in the generated css that
+                                can be used by the FireStylus Firebug plugin
+        -l, --line-numbers      Emits comments in the generated css
+                                indicating the corresponding stylus line
+        -V, --version           Display the version of stylus
+        -h, --help              Display help information
+
+### STDIO Compilation Example
+
+ `stylus` reads from _stdin_ and outputs to _stdout_, so for example:
+
+      $ stylus --compress < some.styl > some.css
+
+Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
+
+      $ stylus
+      body
+        color red
+        font 14px Arial, sans-serif
+
+### Compiling Files Example
+
+ `stylus` also accepts files and directories, for example a directory named `css` will compile and output the `.css` files in the same directory.
+ 
+      $ stylus css
+
+  The following will output to `./public/stylesheets`:
+
+      $ stylus css --out public/stylesheets
+
+  Or a few files:
+
+      $ stylus one.styl two.styl
+
+  For development purpose, you can enable the `linenos` option to emit comments indicating 
+  the Stylus filename and line number in the generated css:
+
+      $ stylus --line-numbers <path>
+
+  Or the `firebug` option if you want to use
+  the [FireStylus extension for Firebug](//github.com/LearnBoost/stylus/blob/master/docs/firebug.md):
+
+      $ stylus --firebug <path>
+
+### Converting CSS
+
+ If we wish to convert css to the terse Stylus syntax, we can utilize the `--css` flag.
+
+ Via stdio:
+ 
+      $ stylus --css < test.css > test.styl
+
+ Output a `.styl` file of the same basename:
+ 
+      $ stylus --css test.css
+
+ Output to a specific destination:
+ 
+      $ stylus --css test.css /tmp/out.styl
+
+### CSS Property Help
+
+  On osx `stylus help <prop>` will open your default browser and display help documentation for the given `<prop>`.
+
+    $ stylus help box-shadow
+
+### Interactive Shell
+
+ The Stylus REPL (Read-Eval-Print-Loop) or "interactive shell" allows you to
+ play around with Stylus expressions directly from your terminal. Note that this works only for expressions, not selectors etc. To use simple add the `-i`, or `--interactive` flag:
+ 
+     $ stylus -i
+     > color = white
+     => #fff
+     > color - rgb(200,50,0)
+     => #37cdff
+     > color
+     => #fff
+     > color -= rgb(200,50,0)
+     => #37cdff
+     > color
+     => #37cdff
+     > rgba(color, 0.5)
+     => rgba(55,205,255,0.5)
+
+### Utilizing Plugins
+
+ For our examples we will utilize the [nib](https://github.com/visionmedia/nib) Stylus plugin to illustrate it's CLI usage. Suppose we have the following stylus, importing nib and utilize it's `linear-gradient()` function.
+ 
+     @import 'nib'
+
+     body
+       background: linear-gradient(20px top, white, black) 
+
+ Our first attempt to render using `stylus(1)` via stdio might look like this:
+ 
+     $ stylus < test.styl
+
+ Which would yield the following error because stylus does not know where to find nib in our machine.
+
+       Error: stdin:3
+          1| 
+          2| 
+        > 3| @import 'nib'
+          4| 
+          5| body
+          6|   background: linear-gradient(20px top, white, black)
+
+  For plugins that simply supply stylus APIs we could add the path to the stylus lookup paths by using the `--include` or `-I` flag:
+
+     $ stylus < test.styl --include ../nib/lib
+
+  Now yielding the following output. As you might notice the calls to `gradient-data-uri()` and `create-gradient-image()` output as literals, this is because exposing the library path is not enough when the plugin provides a JavaScript API, though if we wished to only utilize the pure-stylus nib functions we would be fine. 
+
+      body {
+        background: url(gradient-data-uri(create-gradient-image(20px, top)));
+        background: -webkit-gradient(linear, left top, left bottom, color-stop(0, #fff), color-stop(1, #000));
+        background: -webkit-linear-gradient(top, #fff 0%, #000 100%);
+        background: -moz-linear-gradient(top, #fff 0%, #000 100%);
+        background: linear-gradient(top, #fff 0%, #000 100%);
+      }
+
+  So, what we need to do is utilize the `--use`, or `-u` flag which expects a path to a node module, with or without the ".js" extension. This `require()`s the module, expecting a function to be exported as `module.exports`, which then calls `style.use(fn())` to allow the plugin to expose itself, defining js functions etc.
+  
+    $ stylus < test.styl --use ../nib/lib/nib
+
+ Yielding the expected result:
+
+    body {
+      background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAUCAYAAABMDlehAAAABmJLR0QA/wD/AP+gvaeTAAAAI0lEQVQImWP4+fPnf6bPnz8zMH358oUBwkIjKJBgYGNj+w8Aphk4blt0EcMAAAAASUVORK5CYII=");
+      background: -webkit-gradient(linear, left top, left bottom, color-stop(0, #fff), color-stop(1, #000));
+      background: -webkit-linear-gradient(top, #fff 0%, #000 100%);
+      background: -moz-linear-gradient(top, #fff 0%, #000 100%);
+      background: linear-gradient(top, #fff 0%, #000 100%);
+    }
+  

data/vendor/docs/firebug.md

@@ -0,0 +1,60 @@
+
+## FireStylus extension for Firebug
+
+[FireStylus](//github.com/parallel/firestylus) is a Firebug extension 
+that makes Firebug display the Stylus filename and line numbers of 
+the Stylus-generated CSS styles rather than those of the generated CSS.
+
+![Screenshot](//raw.github.com/parallel/firestylus/master/src/chrome/skin/screenshot.png)
+
+### Usage
+
+First, you need to install [Firebug](https://addons.mozilla.org/firefox/downloads/latest/1843/addon-1843-latest.xpi?src=addondetail)
+and the [FireStylus extension](//github.com/parallel/firestylus)
+
+Then, you need to enable the Stylus's `firebug` option when generating your CSS.
+
+Command line
+
+	$ stylus -f <path>
+	$ stylus --firebug <path>
+	
+Javascript API
+
+	var stylus = require('stylus');
+
+	stylus(str)
+	  .set('firebug', true)
+	  .render(function(err, css){
+		// logic
+	  });
+
+Connect / Express
+
+    var stylus = require('stylus');
+
+    var server = connect.createServer(
+        stylus.middleware({
+            src: __dirname
+          , dest: __dirname + '/public'
+          , firebug: true
+        })
+      , connect.static(__dirname + '/public')
+    );
+
+### Compatibility
+
+ FireStylus should work with all versions of Firefox after 
+ and including 3.0, and all Firebug versions after and including 1.4
+
+ - Firefox 3+ (also works with version 5)
+ - Firebug 1.4+
+
+### Limitations
+
+FireStylus and FireSass are incompatible. You cannot enable them
+simultaneously.
+
+FireStylus (like FireSass) only works in the html pane of firebug, the others,
+such as the css pane won't work due to firebug limitations.
+

data/vendor/docs/font-face.md

@@ -0,0 +1,26 @@
+
+## @font-face
+
+ The `@font-face` at-rule expects as you would expect, simply followed by a block of properties:
+ 
+ 
+     @font-face
+       font-family Geo
+       font-style normal
+       src url(fonts/geo_sans_light/GensansLight.ttf)
+
+     .ingeo
+       font-family Geo
+
+yielding:
+
+
+      @font-face {
+        font-family: Geo;
+        font-style: normal;
+        src: url("fonts/geo_sans_light/GensansLight.ttf");
+      }
+      .ingeo {
+        font-family: Geo;
+      }
+

data/vendor/docs/functions.md

@@ -0,0 +1,192 @@
+
+## Functions
+
+ Stylus features powerful in-language function definition. Function definition appears 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 may then utilize this function in conditions, as 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 leading arguments! For example:
+ 
+ 
+     add(a, b = a)
+       a + b
+
+     add(10, 5)
+     // => 15
+     
+     add(10)
+     // => 20
+
+note that since argument defaults are assignments, we can also utilize function calls for defaults:
+
+     add(a, b = unit(a, px))
+       a + b
+
+### Function Bodies
+
+ We can take our simple `add()` function further, by casting all units passed as `px` via the `unit()` built-in. Re-assigning each argument and providing a unit type string (or identifier), which disregards 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 may either wrap in parens, or utilize 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 see if the value given 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 them-selves 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 we can simply assign a function's name to a new identifier. For example our previous `add()` function could be exposed as `plus()` as well, simply by:
+  
+      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 will return 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 you can see 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