stylus-source 0.23.0 → 0.24.0

data/vendor/docs/operators.md

@@ -1,470 +0,0 @@
-
-## Operator Precedence
-
-Below is the operator precedence table, highest to lowest:
-
-     []
-     ! ~ + -
-     is defined
-     ** * / %
-     + -
-     ... ..
-     <= >= < >
-     in
-     == is != is not isnt
-     is a
-     && and || or
-     ?:
-     = := ?= += -= *= /= %=
-     not
-     if unless
-
-## Unary Operators
-
-The following unary operators are available, `!`, `not`, `-`, `+`, and `~`.
-
-    !0
-    // => true
-    
-    !!0
-    // => false
-
-    !1
-    // => false
-    
-    !!5px
-    // => true
-
-    -5px
-    // => -5px
-    
-    --5px
-    // => 5px
-
-    not true
-    // => false
-    
-    not not true
-    // => true
-    
-The logical `not` operator has low precedence, therefore the following example could be replaced with
-
-    a = 0
-    b = 1
-    
-    !a and !b
-    // => false
-    // pased as: (!a) and (!b)
-
-With:
-
-    not a or b
-    // => false
-    // parsed as: not (a or b)
-
-## Binary Operators
-
-### Subscript []
-
- The subscript operator allows us to grab a value inside an expression via index. Parenthesized expressions may act as tuples (e.g. `(15px 5px)`, `(1 2 3)`).
- 
- Below is an example that uses tuples for error handling (and showcasing the versatility of this construct):
- 
-     add(a, b)
-       if a is a 'unit' and b is a 'unit'
-         a + b
-       else
-         (error 'a and b must be units!')
-
-     body
-       padding add(1,'5')
-       // => padding: error "a and b must be units";
-       
-       padding add(1,'5')[0]
-       // => padding: error;
-       
-       padding add(1,'5')[0] == error
-       // => padding: true;
-
-       padding add(1,'5')[1]
-       // => padding: "a and b must be units";
-
- Here's a more complex example. Now we're invoking the built-in `error()` function with the return error message, whenever the ident (the first value) equals `error`.
- 
- 
-     if (val = add(1,'5'))[0] == error
-       error(val[1])
-
-## Range .. ...
-
- Both the inclusive (`..`) and exclusive (`...`) range operators are provided, expanding to expressions:
- 
-     1..5
-     // => 1 2 3 4 5
-
-     1...5
-     // => 1 2 3 4
-
-### Additive: + -
-
-Multiplicative and additive binary operators work as expected. Type conversion is applied within unit type classes, or default to the literal value. For example `5s - 2px` results in `3s`.
-
-    15px - 5px
-    // => 10px
-    
-    5 - 2
-    // => 3
-    
-    5in - 50mm
-    // => 3.031in
-    
-    5s - 1000ms
-    // => 4s
-    
-    20mm + 4in
-    // => 121.6mm
-
-    "foo " + "bar"
-    // => "foo bar"
-
-    "num " + 15
-    // => "num 15"
-
-### Multiplicative: / * %
-
-    2000ms + (1s * 2)
-    // => 4ms
-
-    5s / 2
-    // => 2.5s
-
-    4 % 2
-    // => 0
-
-When using `/` within a property value, you **must** wrap with parens. Otherwise the `/` is taken literally (to support CSS `line-height`):
-
-    font: 14px/1.5;
-
-But the following is evaluated as `14px` ÷ `1.5`:
-
-    font: (14px/1.5);
-
-This is _only_ required for the `/` operator.
-
-### Exponent: **
-
-The Exponent operator:
-
-    2 ** 8
-    // => 256
-
-### Equality & Relational: == != >= <= > <
-
-Equality operators can be used to equate units, colors, strings, and even identifiers. This is a powerful concept, as even arbitrary identifiers (such as as `wahoo`) can be utilized as atoms. A function could return `yes` or `no` instead of `true` or `false` (although not advised). 
-
-    5 == 5
-    // => true
-    
-    10 > 5
-    // => true
-    
-    #fff == #fff
-    // => true
-    
-    true == false
-    // => false
-    
-    wahoo == yay
-    // => false
-    
-    wahoo == wahoo
-    // => true
-    
-    "test" == "test"
-    // => true
-
-    true is true
-    // => true
-
-    'hey' is not 'bye'
-    // => true
-
-    'hey' isnt 'bye'
-    // => true
-
-    (foo bar) == (foo bar)
-    // => true
-
-    (1 2 3) == (1 2 3)
-    // => true
-
-    (1 2 3) == (1 1 3)
-    // => false
-
-Only exact values match. For example, `0 == false` and `null == false` are both `false`.
-
-Aliases:
-
-    ==    is
-    !=    is not
-    !=    isnt
-
-## Truthfulness
-
- Nearly everything within Stylus resolves to `true`, including units with a suffix. Even `0%`, `0px`, etc. will resolve to `true` (because it's common in Stylus for mixins or functions to accept units as valid). 
- 
- However, `0` itself is `false` in terms of arithmetic. 
- 
- Expressions (or "lists") with a length greater than 1 are considered truthy.
-
-`true` examples:
-
-      0% 
-      0px
-      1px 
-      -1
-      -1px
-      hey
-      'hey'
-      (0 0 0)
-      ('' '')
-
-`false` examples:
-
-     0 
-     null
-     false
-     ''
-
-### Logical Operators: && || and or
-
-Logical operators `&&` and `||` are aliased `and` / `or` which apply the same precedence.
-
-    5 && 3
-    // => 3
-    
-    0 || 5
-    // => 5
-    
-    0 && 5
-    // => 0
-    
-    #fff is a 'rgba' and 15 is a 'unit'
-    // => true
-
-### Existence Operator: in
-
- Checks for the existence of the _left-hand_ operand within the _right-hand_ expression.
-
-Simple examples:
-
-      nums = 1 2 3
-      1 in nums
-      // => true
-
-      5 in nums
-      // => false
-
-Some undefined identifiers:
-
-      words = foo bar baz
-      bar in words
-      // => true
-
-      HEY in words
-      // => false
-
-Works with tuples too:
-
-      vals = (error 'one') (error 'two')
-      error in vals
-      // => false
-      
-      (error 'one') in vals
-      // => true
-
-      (error 'two') in vals
-      // => true
-
-      (error 'something') in vals
-      // => false
-
-Example usage in mixin:
-
-      pad(types = padding, n = 5px)
-        if padding in types
-          padding n
-        if margin in types
-          margin n
-
-      body
-        pad()
-
-      body
-        pad(margin)
-
-      body
-        pad(padding margin, 10px)
-
-Yielding:
-
-      body {
-        padding: 5px;
-      }
-      body {
-        margin: 5px;
-      }
-      body {
-        padding: 10px;
-        margin: 10px;
-      }
-
-### Conditional Assignment: ?= :=
-
-The conditional assignment operator `?=` (aliased as `:=`) lets us define variables without clobbering old values (if present). This operator expands to an `is defined` binary operation within a ternary. 
-
-For example, the following are equivalent:
-
-    color := white
-    color ?= white
-    color = color is defined ? color : white
-
-When using plain `=`, we simply reassign:
-
-    color = white
-    color = black
-    
-    color
-    // => black
-
-But when using `?=`, our second attempt fails (since the variable is already defined):
-
-    color = white
-    color ?= black
-    
-    color
-    // => white
-
-### Instance Check: is a
-
-Stylus provides a binary operator named `is a` used to type check.
-
-    15 is a 'unit'
-    // => true
-    
-    #fff is a 'rgba'
-    // => true
-    
-    15 is a 'rgba'
-    // => false
-
-Alternatively, we could use the `type()` BIF:
-
-    type(#fff) == 'rgba'
-    // => true                                                                            
-
-**Note:** `color` is the only special-case, evaluating to `true` when the
-left-hand operand is an `RGBA` or `HSLA` node.
-
-### Variable Definition: is defined
-
-This pseudo binary operator does not accept a right-hand operator, and does _not_ evaluate the left. This allows us to check if a variable has a value assigned to it.
-
-    foo is defined
-    // => false
-    
-    foo = 15px
-    foo is defined
-    // => true
-    
-    #fff is defined
-    // => 'invalid "is defined" check on non-variable #fff'
-
-Alternatively, one can use the `lookup(name)` built-in function to do this—or to perform dynamic lookups:
-
-    name = 'blue'
-    lookup('light-' + name)
-    // => null
-    
-    light-blue = #80e2e9
-    lookup('light-' + name)
-    // => #80e2e9
-
-This operator is essential, as an undefined identifier is still a truthy value. For example:
-
-    body
-      if ohnoes
-        padding 5px
-
-_Will_ yield the following CSS when undefined:
-
-    body {
-      padding: 5px;
-    }
-
-However this will be safe:
-
-    body
-      if ohnoes is defined
-        padding 5px
-
-## Ternary
-
-The ternary operator works as we would expect in most languages. It's the only operator with three operands (the _condition_ expression, the _truth_ expression, and the _false_ expression).
-
-    num = 15
-    num ? unit(num, 'px') : 20px
-    // => 15px
-
-## Casting
-
- As an terse alternative to the `unit()` built-in function, the syntax `(expr) unit` may be used to force the suffix. 
-
-    body
-      n = 5
-      foo: (n)em
-      foo: (n)%
-      foo: (n + 5)%
-      foo: (n * 5)px
-      foo: unit(n + 5, '%')
-      foo: unit(5 + 180 / 2, deg)
-
-## Color Operations
-
- Operations on colors provide a terse, expressive way to alter components. For example, we can operate on each RGB:
- 
-    #0e0 + #0e0
-    // => #0f0
-
- Another example is adjust the lightness value by adding or subtracting a percentage. To lighten a color, add; to darken, subtract.
- 
-    #888 + 50%
-    // => #c3c3c3
-
-    #888 - 50%
-    // => #444
-
-  Adjust the hue is also possible by adding or subtracting with degrees. For example, adding `50deg` to this red value results in a yellow:
-  
-     #f00 + 50deg
-     // => #ffd500
-
-  Values clamp appropriately. For example, we can "spin" the hue 180 degrees, and if the current value is `320deg`, it will resolve to `140deg`.
-
-  We may also tweak several values at once (including the alpha) by using `rgb()`, `rgba()`, `hsl()`, or `hsla()`:
-  
-      #f00 - rgba(100,0,0,0.5)
-      // => rgba(155,0,0,0.5)
-
-## Sprintf
-
- The string sprintf-like operator `%` can be used to generate a literal value, internally passing arguments through the `s()` built-in:
-
-       'X::Microsoft::Crap(%s)' % #fc0
-       // => X::Microsoft::Crap(#fc0)
-
-  Multiple values should be parenthesized:
-  
-      '-webkit-gradient(%s, %s, %s)' % (linear (0 0) (0 100%))
-      // => -webkit-gradient(linear, 0 0, 0 100%)
-   

data/vendor/docs/selectors.md

@@ -1,133 +0,0 @@
-## Selectors
-
-### Indentation
-
-Stylus is "pythonic" (i.e. indentation-based). Whitespace is significant, so we substitute `{` and `}` with an _indent_, and an _outdent_ as shown below:
-
-    body
-      color white
-
-Which compiles to:
-
-    body {
-      color: #fff;
-    }
-
-If preferred, you can use colons to separate properties and values:
-
-    body
-      color: white
-
-### Rule Sets
-
-Stylus, just like CSS, allows you to define properties for several selectors at once through comma separation.
-
-    textarea, input
-      border 1px solid #eee
-
-The same can be done with a newline:
-
-    textarea
-    input
-      border 1px solid #eee
-
-Both compile to:
-
-    textarea,
-    input {
-      border: 1px solid #eee;
-    }
-
-**The only exception to this rule** are selectors that look like properties. For example, the following `foo bar baz` might be a property **or** a selector:
-
-    foo bar baz
-    > input
-      border 1px solid
-
-So for this reason (or simply if preferred), we may trail with a comma:
-
-    foo bar baz,
-    form input,
-    > a
-      border 1px solid
-
-### Parent Reference
-
-The `&` character references the parent selector(s). In the example below our two selectors (`textarea` and `input`) both alter the `color` on the `:hover` pseudo selector. 
-
-    textarea
-    input
-      color #A7A7A7
-      &:hover
-        color #000
-
-Compiles to:
-
-    textarea,
-    input {
-      color: #a7a7a7;
-    }
-    textarea:hover,
-    input:hover {
-      color: #000;
-    }
-
-Below is an example providing a simple `2px` border for Internet Exploder utilizing the parent reference within a mixin:
-
-      box-shadow()
-        -webkit-box-shadow arguments
-        -moz-box-shadow arguments
-        box-shadow arguments
-        html.ie8 &,
-        html.ie7 &,
-        html.ie6 &
-          border 2px solid arguments[length(arguments) - 1]
-
-      body
-        #login
-          box-shadow 1px 1px 3px #eee
-
-Yielding:
-
-      body #login {
-        -webkit-box-shadow: 1px 1px 3px #eee;
-        -moz-box-shadow: 1px 1px 3px #eee;
-        box-shadow: 1px 1px 3px #eee;
-      }
-      html.ie8 body #login,
-      html.ie7 body #login,
-      html.ie6 body #login {
-        border: 2px solid #eee;
-      }
-
-### Disambiguation
-
-Expressions such as `padding - n` could be interpreted both as a subtraction operation, as well as a property with an unary minus. To disambiguate, wrap the expression with parens:
-
-    pad(n)
-      padding (- n)
-
-    body
-      pad(5px)
-
-Compiles to:
-
-    body {
-      padding: -5px;
-    }
-
-However, this is only true in functions (since functions act both as mixins, or calls with return values). 
-
-For example, the following is fine (and yields the same results as above):
-
-    body
-      padding -5px
-
-Have weird property values that Stylus can't process? `unquote()` can help you out:
-
-    filter unquote('progid:DXImageTransform.Microsoft.BasicImage(rotation=1)')
-
-Yields:
-
-    filter progid:DXImageTransform.Microsoft.BasicImage(rotation=1)
-    

data/vendor/docs/textmate.md

@@ -1,4 +0,0 @@
-
-## TextMate Bundle
-
- Stylus ships with a TextMate bundle, located within `./editors`. To install, simply execute `make install-bundle`, or place `./editors/Stylus.tmbundle` in the appropriate location.

data/vendor/docs/vargs.md

@@ -1,84 +0,0 @@
-
-## Rest Parameters
-
- Stylus supports rest parameters in the form of `name...`. These params consume the remaining arguments passed to a mixin or function. This is useful when utilizing (for example) the implicit function call support to apply vendor prefixes like `-webkit` or `-moz`.
- 
-
-In the example below, we consume all the arguments passed, and simply apply them to multiple properties.
-
-     box-shadow(args...)
-       -webkit-box-shadow args
-       -moz-box-shadow args
-       box-shadow args
-
-     #login
-       box-shadow 1px 2px 5px #eee
-
-Yielding:
-
-      #login {
-        -webkit-box-shadow: 1px 2px 5px #eee;
-        -moz-box-shadow: 1px 2px 5px #eee;
-        box-shadow: 1px 2px 5px #eee;
-      }
-
-If we wanted to peek at a specific argument—say, `x-offset`—we could simply use `args[0]`. Or, we may wish to redefine the mixin:
-
-        box-shadow(offset-x, args...)
-          got-offset-x offset-x
-          -webkit-box-shadow offset-x args
-          -moz-box-shadow offset-x args
-          box-shadow offset-x args
-
-        #login
-          box-shadow 1px 2px 5px #eee
-
-Yielding:
-
-        #login {
-          got-offset-x: 1px;
-          -webkit-box-shadow: 1px 2px 5px #eee;
-          -moz-box-shadow: 1px 2px 5px #eee;
-          box-shadow: 1px 2px 5px #eee;
-        }
-
-### arguments
-
-  The `arguments` variable is injected into mixin and function bodies, containing the exact expression passed. This is useful for several reasons (especially vendor support) as you get the _exact_ expression, commas and all.
-
-  For example, if we use a rest param, the comma is consumed (since it is an expression delimiter):
-  
-      box-shadow(args...)
-        -webkit-box-shadow args
-        -moz-box-shadow args
-        box-shadow args
-
-      #login
-        box-shadow #ddd 1px 1px, #eee 2px 2px 
-
-Yielding undesired results:
-
-      #login {
-        -webkit-box-shadow: #ddd 1px 1px #eee 2px 2px;
-        -moz-box-shadow: #ddd 1px 1px #eee 2px 2px;
-        box-shadow: #ddd 1px 1px #eee 2px 2px;
-      }
-
-Let's redefine the mixin using `arguments`:
-
-      box-shadow()
-        -webkit-box-shadow arguments
-        -moz-box-shadow arguments
-        box-shadow arguments
-
-      body
-        box-shadow #ddd 1px 1px, #eee 2px 2px
-
-Now, yielding the desired result:
-
-      body {
-        -webkit-box-shadow: #ddd 1px 1px, #eee 2px 2px;
-        -moz-box-shadow: #ddd 1px 1px, #eee 2px 2px;
-        box-shadow: #ddd 1px 1px, #eee 2px 2px;
-      }
-