stylus-source 0.22.6 → 0.23.0
Sign up to get free protection for your applications and to get access to all the features.
- data/VERSION +1 -1
- data/vendor/History.md +6 -0
- data/vendor/docs/comments.md +3 -3
- data/vendor/docs/conditionals.md +8 -8
- data/vendor/docs/css-style.md +4 -4
- data/vendor/docs/error-reporting.md +4 -4
- data/vendor/docs/escape.md +4 -2
- data/vendor/docs/executable.md +23 -19
- data/vendor/docs/extend.md +14 -7
- data/vendor/docs/firebug.md +7 -8
- data/vendor/docs/font-face.md +2 -2
- data/vendor/docs/functions.md +28 -23
- data/vendor/docs/functions.url.md +6 -4
- data/vendor/docs/gedit.md +1 -1
- data/vendor/docs/import.md +10 -8
- data/vendor/docs/interpolation.md +4 -4
- data/vendor/docs/introspection.md +6 -7
- data/vendor/docs/iteration.md +7 -5
- data/vendor/docs/js.md +19 -9
- data/vendor/docs/keyframes.md +6 -4
- data/vendor/docs/kwargs.md +4 -5
- data/vendor/docs/literal.md +2 -2
- data/vendor/docs/media.md +2 -2
- data/vendor/docs/middleware.md +8 -9
- data/vendor/docs/mixins.md +19 -11
- data/vendor/docs/operators.md +32 -26
- data/vendor/docs/selectors.md +18 -16
- data/vendor/docs/textmate.md +1 -1
- data/vendor/docs/vargs.md +9 -9
- data/vendor/docs/variables.md +7 -7
- data/vendor/lib/nodes/extend.js +11 -0
- data/vendor/lib/renderer.js +17 -4
- data/vendor/lib/stylus.js +1 -1
- data/vendor/lib/visitor/evaluator.js +1 -1
- data/vendor/package.json +1 -1
- data/vendor/test/cases/dumb.css +10 -0
- data/vendor/test/cases/dumb.styl +11 -0
- data/vendor/testing/test.js +5 -1
- data/vendor/testing/test.styl +2 -0
- metadata +4 -2
data/VERSION
CHANGED
@@ -1 +1 @@
|
|
1
|
-
0.
|
1
|
+
0.23.0
|
data/vendor/History.md
CHANGED
data/vendor/docs/comments.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
|
2
2
|
## Comments
|
3
3
|
|
4
|
-
Stylus supports three kinds of comments
|
4
|
+
Stylus supports three kinds of comments: single-line, and multi-line comments, and multi-line buffered comments.
|
5
5
|
|
6
6
|
## Single-line
|
7
7
|
|
@@ -13,7 +13,7 @@
|
|
13
13
|
|
14
14
|
## Multi-line
|
15
15
|
|
16
|
-
Multi-line comments look identical to regular CSS comments,
|
16
|
+
Multi-line comments look identical to regular CSS comments. However, they only output when the `compress` option is not enabled.
|
17
17
|
|
18
18
|
/*
|
19
19
|
* Adds the given numbers together.
|
@@ -24,7 +24,7 @@
|
|
24
24
|
|
25
25
|
## Multi-line buffered
|
26
26
|
|
27
|
-
Multi-line comments which are not suppressed start with
|
27
|
+
Multi-line comments which are not suppressed start with `/*!`. This tells Stylus to output the comment regardless of compression.
|
28
28
|
|
29
29
|
/*!
|
30
30
|
* Adds the given numbers together.
|
data/vendor/docs/conditionals.md
CHANGED
@@ -7,7 +7,7 @@
|
|
7
7
|
|
8
8
|
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.
|
9
9
|
|
10
|
-
The example below would conditionally overload the `padding` property, swapping it for margin
|
10
|
+
The example below would conditionally overload the `padding` property, swapping it for `margin`.
|
11
11
|
|
12
12
|
overload-padding = true
|
13
13
|
|
@@ -38,9 +38,9 @@ Another `box()` helper:
|
|
38
38
|
|
39
39
|
### unless
|
40
40
|
|
41
|
-
For users familiar with the
|
41
|
+
For users familiar with the Ruby programming language, we have the `unless` conditional. It’s basically the opposite of `if`—essentially `if (!(expr))`.
|
42
42
|
|
43
|
-
In the example below, if `disable-padding-override` is undefined or `false`
|
43
|
+
In the example below, if `disable-padding-override` is `undefined` or `false`, `padding` will be overridden, displaying `margin` instead. But if it’s `true`, `padding` will continue outputting `padding 5px 10px` as expected.
|
44
44
|
|
45
45
|
disable-padding-override = true
|
46
46
|
|
@@ -53,10 +53,10 @@ In the example below, if `disable-padding-override` is undefined or `false` padd
|
|
53
53
|
|
54
54
|
### Postfix Conditionals
|
55
55
|
|
56
|
-
Stylus supports postfix conditionals
|
56
|
+
Stylus supports postfix conditionals. This means that `if` and `unless` act as operators; they evaluate the left-hand operand when the right-hand expression is truthy.
|
57
57
|
|
58
58
|
|
59
|
-
For example let's define `negative()
|
59
|
+
For example let's define `negative()` to perform some basic type checking. Below we use block-style conditionals:
|
60
60
|
|
61
61
|
negative(n)
|
62
62
|
unless n is a 'unit'
|
@@ -66,16 +66,16 @@ In the example below, if `disable-padding-override` is undefined or `false` padd
|
|
66
66
|
else
|
67
67
|
no
|
68
68
|
|
69
|
-
Next we utilize postfix conditionals to keep our function terse.
|
69
|
+
Next, we utilize postfix conditionals to keep our function terse.
|
70
70
|
|
71
71
|
negative(n)
|
72
72
|
error('invalid number') unless n is a 'unit'
|
73
73
|
return yes if n < 0
|
74
74
|
no
|
75
75
|
|
76
|
-
Of course we could take this further,
|
76
|
+
Of course, we could take this further. For example, we could write `n < 0 ? yes : no`, or simply stick with booleans: `n < 0`.
|
77
77
|
|
78
|
-
Postfix conditionals may be applied to most single-line statements
|
78
|
+
Postfix conditionals may be applied to most single-line statements. For example, `@import`, `@charset`, mixins—and of course, properties as shown below:
|
79
79
|
|
80
80
|
|
81
81
|
pad(types = margin padding, n = 5px)
|
data/vendor/docs/css-style.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
|
2
2
|
## CSS Style
|
3
3
|
|
4
|
-
Stylus transparently supports a regular
|
4
|
+
Stylus transparently supports a regular CSS-style syntax. This means you don't need an alternative parser, or specify that a certain file uses a specific style.
|
5
5
|
|
6
6
|
### Example
|
7
7
|
|
@@ -22,7 +22,7 @@
|
|
22
22
|
border 1px solid
|
23
23
|
border-radius 5px
|
24
24
|
|
25
|
-
Since braces, colons, and semi-colons are optional, we could write this example just as we would with normal
|
25
|
+
Since braces, colons, and semi-colons are optional, we could write this example just as we would with normal CSS:
|
26
26
|
|
27
27
|
border-radius() {
|
28
28
|
-webkit-border-radius: arguments;
|
@@ -60,7 +60,7 @@
|
|
60
60
|
border: 1px solid;
|
61
61
|
border-radius: 5px;
|
62
62
|
|
63
|
-
Variables, functions, mixins, and all
|
63
|
+
Variables, functions, mixins, and all the other features provided by Stylus still work as expected:
|
64
64
|
|
65
65
|
main-color = white
|
66
66
|
main-hover-color = black
|
@@ -72,6 +72,6 @@
|
|
72
72
|
|
73
73
|
body a { color: main-color; &:hover { color: main-hover-color; }}
|
74
74
|
|
75
|
-
There are
|
75
|
+
There are a few caveats 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 with zero modification, this feature allows those who prefer CSS syntax to continue doing so while leveraging Stylus' other powerful features.
|
76
76
|
|
77
77
|
|
@@ -1,7 +1,7 @@
|
|
1
1
|
|
2
2
|
## Error Reporting
|
3
3
|
|
4
|
-
Stylus has fantastic error reporting built
|
4
|
+
Stylus has fantastic error reporting built-in for syntax, parse, and evaluation errors—complete with stack traces, line numbers, and filenames.
|
5
5
|
|
6
6
|
### Parse Error
|
7
7
|
|
@@ -11,7 +11,7 @@ Parse error example:
|
|
11
11
|
form input
|
12
12
|
== padding 5px
|
13
13
|
|
14
|
-
|
14
|
+
Yielding:
|
15
15
|
|
16
16
|
Error: /Users/tj/Projects/stylus/testing/test.styl:4
|
17
17
|
3: ' form input'
|
@@ -21,7 +21,7 @@ yielding:
|
|
21
21
|
|
22
22
|
### Evaluation Error
|
23
23
|
|
24
|
-
This "runtime" or evaluation error is caused
|
24
|
+
This "runtime" or evaluation error is caused by passing a string to `border-radius()`, instead of the expected `Unit` (by using our helper `ensure(n, 'unit')`).
|
25
25
|
|
26
26
|
ensure(val, type)
|
27
27
|
unless val is a type
|
@@ -36,7 +36,7 @@ yielding:
|
|
36
36
|
body
|
37
37
|
border-radius '5px'
|
38
38
|
|
39
|
-
|
39
|
+
Yielding:
|
40
40
|
|
41
41
|
Error: /Users/tj/Projects/stylus/examples/error.styl:12
|
42
42
|
11: ''
|
data/vendor/docs/escape.md
CHANGED
@@ -1,11 +1,13 @@
|
|
1
1
|
## Escaping
|
2
2
|
|
3
|
-
Stylus
|
3
|
+
Stylus lets you escape characters. This effectively turns them into identifiers, allowing them to be rendered as literals.
|
4
|
+
|
5
|
+
For example:
|
4
6
|
|
5
7
|
body
|
6
8
|
padding 1 \+ 2
|
7
9
|
|
8
|
-
|
10
|
+
Compiles to:
|
9
11
|
|
10
12
|
body {
|
11
13
|
padding: 1 + 2;
|
data/vendor/docs/executable.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
|
2
2
|
## Stylus Executable
|
3
3
|
|
4
|
-
Stylus ships with the `stylus` executable for converting
|
4
|
+
Stylus ships with the `stylus` executable for converting Stylus to CSS.
|
5
5
|
|
6
6
|
Usage: stylus [options] [command] [< in [> out]]
|
7
7
|
[file|dir ...]
|
@@ -9,7 +9,7 @@ Stylus ships with the `stylus` executable for converting stylus to css.
|
|
9
9
|
Commands:
|
10
10
|
|
11
11
|
help <prop> Opens help info for <prop> in
|
12
|
-
your default browser. (
|
12
|
+
your default browser. (OS X only)
|
13
13
|
|
14
14
|
Options:
|
15
15
|
|
@@ -17,15 +17,15 @@ Stylus ships with the `stylus` executable for converting stylus to css.
|
|
17
17
|
-i, --interactive Start interactive REPL
|
18
18
|
-w, --watch Watch file(s) for changes and re-compile
|
19
19
|
-o, --out <dir> Output to <dir> when passing files
|
20
|
-
-C, --css <src> [dest] Convert
|
20
|
+
-C, --css <src> [dest] Convert CSS input to Stylus
|
21
21
|
-I, --include <path> Add <path> to lookup paths
|
22
|
-
-c, --compress Compress
|
22
|
+
-c, --compress Compress CSS output
|
23
23
|
-d, --compare Display input along with output
|
24
24
|
-f, --firebug Emits debug infos in the generated css that
|
25
25
|
can be used by the FireStylus Firebug plugin
|
26
|
-
-l, --line-numbers Emits comments in the generated
|
27
|
-
indicating the corresponding
|
28
|
-
-V, --version Display the version of
|
26
|
+
-l, --line-numbers Emits comments in the generated CSS
|
27
|
+
indicating the corresponding Stylus line
|
28
|
+
-V, --version Display the version of Stylus
|
29
29
|
-h, --help Display help information
|
30
30
|
|
31
31
|
### STDIO Compilation Example
|
@@ -34,7 +34,7 @@ Stylus ships with the `stylus` executable for converting stylus to css.
|
|
34
34
|
|
35
35
|
$ stylus --compress < some.styl > some.css
|
36
36
|
|
37
|
-
Try
|
37
|
+
Try Stylus some in the terminal! Type below and press `CTRL-D` for `__EOF__`:
|
38
38
|
|
39
39
|
$ stylus
|
40
40
|
body
|
@@ -43,7 +43,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
43
43
|
|
44
44
|
### Compiling Files Example
|
45
45
|
|
46
|
-
`stylus` also accepts files and directories
|
46
|
+
`stylus` also accepts files and directories. For example, a directory named `css` will compile and output `.css` files in the same directory.
|
47
47
|
|
48
48
|
$ stylus css
|
49
49
|
|
@@ -55,8 +55,8 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
55
55
|
|
56
56
|
$ stylus one.styl two.styl
|
57
57
|
|
58
|
-
For development
|
59
|
-
the Stylus filename and line number in the generated
|
58
|
+
For development purposes, you can use the `linenos` option to emit comments indicating
|
59
|
+
the Stylus filename and line number in the generated CSS:
|
60
60
|
|
61
61
|
$ stylus --line-numbers <path>
|
62
62
|
|
@@ -67,7 +67,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
67
67
|
|
68
68
|
### Converting CSS
|
69
69
|
|
70
|
-
If
|
70
|
+
If you wish to convert CSS to the terse Stylus syntax, use the `--css` flag.
|
71
71
|
|
72
72
|
Via stdio:
|
73
73
|
|
@@ -83,14 +83,16 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
83
83
|
|
84
84
|
### CSS Property Help
|
85
85
|
|
86
|
-
On
|
86
|
+
On OS X, `stylus help <prop>` will open your default browser and display help documentation for the given `<prop>`.
|
87
87
|
|
88
88
|
$ stylus help box-shadow
|
89
89
|
|
90
90
|
### Interactive Shell
|
91
91
|
|
92
92
|
The Stylus REPL (Read-Eval-Print-Loop) or "interactive shell" allows you to
|
93
|
-
play around with Stylus expressions directly from your terminal.
|
93
|
+
play around with Stylus expressions directly from your terminal.
|
94
|
+
|
95
|
+
**Note that this works only for expressions**—not selectors, etc. To use simple add the `-i`, or `--interactive` flag:
|
94
96
|
|
95
97
|
$ stylus -i
|
96
98
|
> color = white
|
@@ -108,7 +110,9 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
108
110
|
|
109
111
|
### Utilizing Plugins
|
110
112
|
|
111
|
-
For
|
113
|
+
For this example we'l use the [nib](https://github.com/visionmedia/nib) Stylus plugin to illustrate its CLI usage.
|
114
|
+
|
115
|
+
Suppose we have the following Stylus, which imports nib to use its `linear-gradient()` function.
|
112
116
|
|
113
117
|
@import 'nib'
|
114
118
|
|
@@ -119,7 +123,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
119
123
|
|
120
124
|
$ stylus < test.styl
|
121
125
|
|
122
|
-
Which would yield the following error because
|
126
|
+
Which would yield the following error (because Stylus doesn't know where to find nib).
|
123
127
|
|
124
128
|
Error: stdin:3
|
125
129
|
1|
|
@@ -129,11 +133,11 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
129
133
|
5| body
|
130
134
|
6| background: linear-gradient(20px top, white, black)
|
131
135
|
|
132
|
-
For plugins that simply supply
|
136
|
+
For plugins that simply supply Stylus APIs, we could add the path to the Stylus lookup paths. We do so by using the `--include` or `-I` flag:
|
133
137
|
|
134
138
|
$ stylus < test.styl --include ../nib/lib
|
135
139
|
|
136
|
-
Now yielding the
|
140
|
+
Now yielding the output below. (As you might notice, calls to `gradient-data-uri()` and `create-gradient-image()` output as literals. This is because exposing the library path isn't enough when a plugin provides a JavaScript API. However, if we only wanted to use pure-Stylus nib functions, we'd be fine.)
|
137
141
|
|
138
142
|
body {
|
139
143
|
background: url(gradient-data-uri(create-gradient-image(20px, top)));
|
@@ -143,7 +147,7 @@ Try stylus some in the terminal, type below and press CTRL-D for __EOF__:
|
|
143
147
|
background: linear-gradient(top, #fff 0%, #000 100%);
|
144
148
|
}
|
145
149
|
|
146
|
-
So, what we need to do is
|
150
|
+
So, what we need to do is use the `--use`, or `-u` flag. It 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 expose the plugin (defining its js functions, etc.).
|
147
151
|
|
148
152
|
$ stylus < test.styl --use ../nib/lib/nib
|
149
153
|
|
data/vendor/docs/extend.md
CHANGED
@@ -1,9 +1,14 @@
|
|
1
1
|
|
2
2
|
## Extend
|
3
3
|
|
4
|
-
The Stylus __@extend__ directive is inspired by
|
4
|
+
The Stylus __@extend__ directive is inspired by (and essentially the same as) the [SASS Implementation](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#extend), with few subtle differences. This feature significantly simplifies maintenance of semantic rulesets that inherit from other semantic rulesets.
|
5
5
|
|
6
|
-
|
6
|
+
|
7
|
+
### “Extending” with mixins
|
8
|
+
|
9
|
+
Although you can use mixins to achieve a similar effect, this can lead to duplicate CSS. A typical pattern is to define several classes as shown below, then combine them on the element such as "warning message".
|
10
|
+
|
11
|
+
While this technique works just fine, it's difficult to maintain.
|
7
12
|
|
8
13
|
.message,
|
9
14
|
.warning {
|
@@ -16,7 +21,9 @@
|
|
16
21
|
}
|
17
22
|
|
18
23
|
|
19
|
-
|
24
|
+
### Using `__@extend__`
|
25
|
+
|
26
|
+
To produce this same output with `__@extend__`, simply pass it the desired selector. Stylus will then append the `.warning` selector to the existing `.message` ruleset. The `.warning` class then inherits properties from `.message`.
|
20
27
|
|
21
28
|
.message {
|
22
29
|
padding: 10px;
|
@@ -29,7 +36,7 @@
|
|
29
36
|
}
|
30
37
|
|
31
38
|
|
32
|
-
|
39
|
+
Here's a more complex example, demonstrating how `__@extend__` cascades:
|
33
40
|
|
34
41
|
red = #E33E1E
|
35
42
|
yellow = #E2E21E
|
@@ -78,7 +85,7 @@
|
|
78
85
|
color: #e33e1e;
|
79
86
|
}
|
80
87
|
|
81
|
-
Where Stylus currently differs from SASS is
|
88
|
+
Where Stylus currently differs from SASS is, SASS won't allow `__@extend__` nested selectors:
|
82
89
|
|
83
90
|
form
|
84
91
|
button
|
@@ -90,7 +97,7 @@
|
|
90
97
|
on line 6 of standard input
|
91
98
|
Use --trace for backtrace.
|
92
99
|
|
93
|
-
With Stylus as long as the selectors match it
|
100
|
+
With Stylus, as long as the selectors match, it works!
|
94
101
|
|
95
102
|
form
|
96
103
|
input[type=text]
|
@@ -102,7 +109,7 @@
|
|
102
109
|
@extends form input[type=text]
|
103
110
|
padding: 10px
|
104
111
|
|
105
|
-
|
112
|
+
Yielding:
|
106
113
|
|
107
114
|
form input[type=text],
|
108
115
|
form textarea {
|
data/vendor/docs/firebug.md
CHANGED
@@ -12,14 +12,14 @@ the Stylus-generated CSS styles rather than those of the generated CSS.
|
|
12
12
|
First, you need to install [Firebug](https://addons.mozilla.org/firefox/downloads/latest/1843/addon-1843-latest.xpi?src=addondetail)
|
13
13
|
and the [FireStylus extension](//github.com/parallel/firestylus)
|
14
14
|
|
15
|
-
Then
|
15
|
+
Then simply enable the Stylus's `firebug` option when generating CSS.
|
16
16
|
|
17
|
-
Command line
|
17
|
+
Command line usage:
|
18
18
|
|
19
19
|
$ stylus -f <path>
|
20
20
|
$ stylus --firebug <path>
|
21
21
|
|
22
|
-
Javascript
|
22
|
+
Javascript usage:
|
23
23
|
|
24
24
|
var stylus = require('stylus');
|
25
25
|
|
@@ -29,7 +29,7 @@ Javascript API
|
|
29
29
|
// logic
|
30
30
|
});
|
31
31
|
|
32
|
-
Connect / Express
|
32
|
+
Connect / Express:
|
33
33
|
|
34
34
|
var stylus = require('stylus');
|
35
35
|
|
@@ -44,8 +44,7 @@ Connect / Express
|
|
44
44
|
|
45
45
|
### Compatibility
|
46
46
|
|
47
|
-
FireStylus should work with
|
48
|
-
and including 3.0, and all Firebug versions after and including 1.4
|
47
|
+
FireStylus should work with Firefox versions 3.0 and up, and with Firebug versions 1.4 and up.
|
49
48
|
|
50
49
|
- Firefox 3+ (also works with version 5)
|
51
50
|
- Firebug 1.4+
|
@@ -55,6 +54,6 @@ Connect / Express
|
|
55
54
|
FireStylus and FireSass are incompatible. You cannot enable them
|
56
55
|
simultaneously.
|
57
56
|
|
58
|
-
FireStylus (like FireSass) only works in the
|
59
|
-
such as the
|
57
|
+
FireStylus (like FireSass) only works in the HTML pane of Firebug. The others
|
58
|
+
(such as the CSS pane) won't work due to Firebug limitations.
|
60
59
|
|
data/vendor/docs/font-face.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
|
2
2
|
## @font-face
|
3
3
|
|
4
|
-
The `@font-face` at-rule expects as you would expect
|
4
|
+
The `@font-face` at-rule expects as you would expect. Simply add a block of properties after it, like so:
|
5
5
|
|
6
6
|
|
7
7
|
@font-face
|
@@ -12,7 +12,7 @@
|
|
12
12
|
.ingeo
|
13
13
|
font-family Geo
|
14
14
|
|
15
|
-
|
15
|
+
Yielding:
|
16
16
|
|
17
17
|
|
18
18
|
@font-face {
|
data/vendor/docs/functions.md
CHANGED
@@ -1,21 +1,21 @@
|
|
1
1
|
|
2
2
|
## Functions
|
3
3
|
|
4
|
-
Stylus features powerful in-language function
|
4
|
+
Stylus features powerful in-language function definitions. Function definitions appear identical to mixins; however, functions may return a value.
|
5
5
|
|
6
6
|
### Return Values
|
7
7
|
|
8
|
-
Let's try a trivial example
|
8
|
+
Let's try a trivial example: creating a function that adds two numbers.
|
9
9
|
|
10
10
|
add(a, b)
|
11
11
|
a + b
|
12
12
|
|
13
|
-
We
|
13
|
+
We can then use this function in conditions, in property values, etc.
|
14
14
|
|
15
15
|
body
|
16
16
|
padding add(10px, 5)
|
17
17
|
|
18
|
-
Rendering
|
18
|
+
Rendering:
|
19
19
|
|
20
20
|
body {
|
21
21
|
padding: 15px;
|
@@ -23,7 +23,9 @@
|
|
23
23
|
|
24
24
|
### Argument Defaults
|
25
25
|
|
26
|
-
Optional arguments may default to a given expression. With Stylus we may even default arguments to
|
26
|
+
Optional arguments may default to a given expression. With Stylus we may even default arguments to earlier arguments!
|
27
|
+
|
28
|
+
For example:
|
27
29
|
|
28
30
|
|
29
31
|
add(a, b = a)
|
@@ -35,14 +37,14 @@
|
|
35
37
|
add(10)
|
36
38
|
// => 20
|
37
39
|
|
38
|
-
|
40
|
+
**Note:** Since argument defaults are assignments, we can also use function calls for defaults:
|
39
41
|
|
40
42
|
add(a, b = unit(a, px))
|
41
43
|
a + b
|
42
44
|
|
43
45
|
### Function Bodies
|
44
46
|
|
45
|
-
We can take our simple `add()` function further
|
47
|
+
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.
|
46
48
|
|
47
49
|
add(a, b = a)
|
48
50
|
a = unit(a, px)
|
@@ -54,14 +56,16 @@ note that since argument defaults are assignments, we can also utilize function
|
|
54
56
|
|
55
57
|
### Multiple Return Values
|
56
58
|
|
57
|
-
Stylus functions can return several values
|
59
|
+
Stylus functions can return several values—just as you can assign several values to a variable.
|
60
|
+
|
61
|
+
For example, the following is a valid assignment:
|
58
62
|
|
59
63
|
sizes = 15px 10px
|
60
64
|
|
61
65
|
sizes[0]
|
62
66
|
// => 15px
|
63
67
|
|
64
|
-
Similarly we may return several values:
|
68
|
+
Similarly, we may return several values:
|
65
69
|
|
66
70
|
sizes()
|
67
71
|
15px 10px
|
@@ -69,12 +73,12 @@ Similarly we may return several values:
|
|
69
73
|
sizes()[0]
|
70
74
|
// => 15px
|
71
75
|
|
72
|
-
One slight exception is when return values are identifiers
|
76
|
+
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):
|
73
77
|
|
74
78
|
swap(a, b)
|
75
79
|
b a
|
76
80
|
|
77
|
-
To disambiguate we
|
81
|
+
To disambiguate, we can either wrap with parentheses, or use the `return` keyword:
|
78
82
|
|
79
83
|
swap(a, b)
|
80
84
|
(b a)
|
@@ -84,7 +88,7 @@ To disambiguate we may either wrap in parens, or utilize the `return` keyword.
|
|
84
88
|
|
85
89
|
### Conditionals
|
86
90
|
|
87
|
-
Let's say we want to create a function named `stringish()` to
|
91
|
+
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`):
|
88
92
|
|
89
93
|
|
90
94
|
stringish(val)
|
@@ -93,7 +97,7 @@ To disambiguate we may either wrap in parens, or utilize the `return` keyword.
|
|
93
97
|
else
|
94
98
|
no
|
95
99
|
|
96
|
-
|
100
|
+
Usage:
|
97
101
|
|
98
102
|
stringish('yay') == yes
|
99
103
|
// => true
|
@@ -104,11 +108,10 @@ usage:
|
|
104
108
|
stringish(0) == no
|
105
109
|
// => true
|
106
110
|
|
107
|
-
__note__: `yes` and `no` are not boolean literals
|
111
|
+
__note__: `yes` and `no` are not boolean literals. They are simply undefined identifiers in this case.
|
108
112
|
|
109
113
|
Another example:
|
110
114
|
|
111
|
-
|
112
115
|
compare(a, b)
|
113
116
|
if a > b
|
114
117
|
higher
|
@@ -117,7 +120,7 @@ Another example:
|
|
117
120
|
else
|
118
121
|
equal
|
119
122
|
|
120
|
-
|
123
|
+
Usage:
|
121
124
|
|
122
125
|
compare(5, 2)
|
123
126
|
// => higher
|
@@ -130,7 +133,7 @@ usage:
|
|
130
133
|
|
131
134
|
### Aliasing
|
132
135
|
|
133
|
-
To alias a function
|
136
|
+
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:
|
134
137
|
|
135
138
|
plus = add
|
136
139
|
|
@@ -139,7 +142,7 @@ usage:
|
|
139
142
|
|
140
143
|
### Variable Functions
|
141
144
|
|
142
|
-
In the same way that we can "alias" a function, we can pass a function as well,
|
145
|
+
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()`.
|
143
146
|
|
144
147
|
invoke(a, b, fn)
|
145
148
|
fn(a, b)
|
@@ -151,7 +154,7 @@ usage:
|
|
151
154
|
padding invoke(5, 10, add)
|
152
155
|
padding invoke(5, 10, sub)
|
153
156
|
|
154
|
-
|
157
|
+
Yielding:
|
155
158
|
|
156
159
|
body {
|
157
160
|
padding: 15;
|
@@ -160,7 +163,9 @@ yielding:
|
|
160
163
|
|
161
164
|
### arguments
|
162
165
|
|
163
|
-
The `arguments` local is available to all function bodies, and contains all the arguments passed.
|
166
|
+
The `arguments` local is available to all function bodies, and contains all the arguments passed.
|
167
|
+
|
168
|
+
For example:
|
164
169
|
|
165
170
|
sum()
|
166
171
|
n = 0
|
@@ -172,13 +177,13 @@ yielding:
|
|
172
177
|
|
173
178
|
### Hash Example
|
174
179
|
|
175
|
-
Below we define the `get(hash, key)` function, which
|
176
|
-
value of `key
|
180
|
+
Below we define the `get(hash, key)` function, which returns the
|
181
|
+
value of `key` (or `null`). We iterate each `pair` in `hash`, returning the pair's second node when the first (the `key`) matches.
|
177
182
|
|
178
183
|
get(hash, key)
|
179
184
|
return pair[1] if pair[0] == key for pair in hash
|
180
185
|
|
181
|
-
As
|
186
|
+
As demonstrated below, in-language functions—paired with robust Stylus expressions—can provide great flexibility:
|
182
187
|
|
183
188
|
hash = (one 1) (two 2) (three 3)
|
184
189
|
|
@@ -1,12 +1,12 @@
|
|
1
1
|
## Data URI Image Inlining
|
2
2
|
|
3
|
-
Stylus is bundled with an optional function named `url()`, which replaces the literal `url()` calls
|
3
|
+
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)).
|
4
4
|
|
5
5
|
### Example
|
6
6
|
|
7
|
-
The function itself is available via `require('stylus').url
|
7
|
+
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()`.
|
8
8
|
|
9
|
-
The `.define(name, callback)` method assigned a JavaScript function that can be called from
|
9
|
+
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:
|
10
10
|
|
11
11
|
stylus(str)
|
12
12
|
.set('filename', __dirname + '/css/test.styl')
|
@@ -15,7 +15,9 @@ The `.define(name, callback)` method assigned a JavaScript function that can be
|
|
15
15
|
|
16
16
|
});
|
17
17
|
|
18
|
-
For example
|
18
|
+
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.
|
19
|
+
|
20
|
+
Likewise, if instead we wanted `url(tobi.png)`, we could pass `paths: [__dirname + '/public/images']`.
|
19
21
|
|
20
22
|
stylus(str)
|
21
23
|
.set('filename', __dirname + '/css/test.styl')
|