stylus-source 0.22.6 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/vendor/docs/gedit.md CHANGED
@@ -12,7 +12,7 @@
12
12
 
13
13
  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
14
14
 
15
- Update the mime database and enjoy Stylus syntax in gedit!
15
+ Update the MIME database and enjoy Stylus syntax in gedit!
16
16
 
17
17
  cd ~/.local/share
18
18
  update-mime-database mime
@@ -4,21 +4,23 @@
4
4
 
5
5
  ### Literal CSS
6
6
 
7
- Any filename with the extension `.css` will become a literal, for example:
7
+ Any filename with the extension `.css` will become a literal. For example:
8
8
 
9
9
  @import "reset.css"
10
10
 
11
- will render to the literal css __@import__ shown below:
11
+ Render the literal CSS __@import__ shown below:
12
12
 
13
13
  @import "reset.css"
14
14
 
15
15
  ### Stylus Import
16
16
 
17
- When using __@import__ without the `.css` extension, it is assumed to be a Stylus sheet, for example `@import "mixins/border-radius"`.
17
+ When using __@import__ without the `.css` extension, it's assumed to be a Stylus sheet (e.g., `@import "mixins/border-radius"`).
18
18
 
19
- __@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/`.
19
+ __@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/`.
20
20
 
21
- __@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:
21
+ __@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.
22
+
23
+ For example, a common lib structure might be:
22
24
 
23
25
  ./tablet
24
26
  |-- index.styl
@@ -26,7 +28,7 @@ will render to the literal css __@import__ shown below:
26
28
  |-- buttons.styl
27
29
  |-- images.styl
28
30
 
29
- 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.
31
+ 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).
30
32
 
31
33
  /**
32
34
  * Module dependencies.
@@ -63,11 +65,11 @@ will render to the literal css __@import__ shown below:
63
65
  console.log(css);
64
66
  });
65
67
 
66
- The following are essentially equivalent:
68
+ The following statement...
67
69
 
68
70
  @import 'mixins/vendor'
69
71
 
70
- and
72
+ ...is equivalent to...
71
73
 
72
74
  .import('mixins/vendor')
73
75
 
@@ -1,7 +1,7 @@
1
1
 
2
2
  ## Interpolation
3
3
 
4
- 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`.
4
+ 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`.
5
5
 
6
6
  A great example use-case for this is expanding properties with vendor prefixes.
7
7
 
@@ -19,7 +19,7 @@
19
19
  button
20
20
  border-radius 1px 2px / 3px 4px
21
21
 
22
- yielding:
22
+ Yields:
23
23
 
24
24
  button {
25
25
  -webkit-border-radius: 1px 2px / 3px 4px;
@@ -29,14 +29,14 @@ yielding:
29
29
 
30
30
  ## Selector Interpolation
31
31
 
32
- 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.
32
+ 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:
33
33
 
34
34
  table
35
35
  for row in 1 2 3 4 5
36
36
  tr:nth-child({row})
37
37
  height: 10px * row
38
38
 
39
- yielding:
39
+ Yields:
40
40
 
41
41
  table tr:nth-child(1) {
42
42
  height: 10px;
@@ -1,17 +1,16 @@
1
1
 
2
2
  ## Introspection API
3
3
 
4
- Stylus supports an introspection API, allowing mixins and functions to reflect relative to the caller etc.
4
+ Stylus supports an introspection API. This allows mixins and functions to reflect relative to the caller, etc.
5
5
 
6
6
 
7
7
  ## mixin
8
8
 
9
- The `mixin` local variable is automatically assigned within function bodies,
10
- containing the string "root" indicating the function is called at the root
11
- level, or "block" indicating otherwise, and finally `false` if the function
12
- is invoked expecting a return value.
9
+ The `mixin` local variable is automatically assigned within function bodies.
10
+ It contains the string `root` if the function was called at the root
11
+ level, or `block` indicating otherwise, and finally `false` if the invoked function expects a return value.
13
12
 
14
- 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.
13
+ 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:
15
14
 
16
15
  reset()
17
16
  if mixin == 'root'
@@ -28,7 +27,7 @@
28
27
  reset()
29
28
  foo reset()
30
29
 
31
- compiles to:
30
+ Compiles to:
32
31
 
33
32
  got {
34
33
  root: true;
@@ -11,7 +11,7 @@ For example:
11
11
  for num in 1 2 3
12
12
  foo num
13
13
 
14
- yields:
14
+ Yields:
15
15
 
16
16
  body {
17
17
  foo: 1;
@@ -26,7 +26,7 @@ The example below shows how to use the `<key-name>`:
26
26
  for font, i in fonts
27
27
  foo i font
28
28
 
29
- yielding:
29
+ Yielding:
30
30
 
31
31
  body {
32
32
  foo: 0 Impact;
@@ -36,7 +36,9 @@ yielding:
36
36
 
37
37
  ### Mixins
38
38
 
39
- 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:
39
+ We can use iteration within mixins to produce powerful functionality. For example, we can apply expression pairs as properties using interpolation and iteration.
40
+
41
+ Below we define `apply()`, conditionally utilizing all the `arguments` so that comma-delimited _and_ expression lists are supported:
40
42
 
41
43
  apply(props)
42
44
  props = arguments if length(arguments) > 1
@@ -52,9 +54,9 @@ yielding:
52
54
 
53
55
  ### Functions
54
56
 
55
- Stylus functions may also contain for-loops, below are some example use-cases:
57
+ Stylus functions may also contain for-loops. Below are some example use-cases:
56
58
 
57
- sum:
59
+ Sum:
58
60
 
59
61
  sum(nums)
60
62
  sum = 0
data/vendor/docs/js.md CHANGED
@@ -1,6 +1,8 @@
1
1
  ## JavaScript API
2
2
 
3
- 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.
3
+ Simply `require` the module, and call `render()` with the given string of Stylus code, and (optional) `options` object.
4
+
5
+ Frameworks utilizing Stylus should pass the `filename` option to provide better error reporting.
4
6
 
5
7
  var stylus = require('stylus');
6
8
 
@@ -28,7 +30,7 @@ We can also do the same thing in a more progressive manner:
28
30
 
29
31
  ### .include(path)
30
32
 
31
- A progressive alternative to setting `paths` via `.set()`, which is ideal when exposing external stylus libraries which expose a path.
33
+ A progressive alternative to `.set('paths',...)` is `.include()`. This is ideal when exposing external Stylus libraries which expose a path.
32
34
 
33
35
  stylus(str)
34
36
  .include(require('nib').path)
@@ -52,12 +54,14 @@ Defer importing of the given `path` until evaluation is performed. The example b
52
54
 
53
55
  ### .define(name, node)
54
56
 
55
- 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:
57
+ 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.
58
+
59
+ However, this is not always available, so Nib may define:
56
60
 
57
61
  .define('has-canvas', stylus.nodes.false);
58
62
  .define('some-setting', new stylus.nodes.String('some value'));
59
63
 
60
- Stylus also casts JavaScript values to their Stylus equivalents when possible, the following are a few examples:
64
+ Stylus also casts JavaScript values to their Stylus equivalents when possible. Here are a few examples:
61
65
 
62
66
  .define('string', 'some string')
63
67
  .define('number', 15.5)
@@ -67,11 +71,17 @@ Defer importing of the given `path` until evaluation is performed. The example b
67
71
  .define('list', { foo: 'bar', bar: 'baz' })
68
72
  .define('families', ['Helvetica Neue', 'Helvetica', 'sans-serif'])
69
73
 
74
+ These same rules apply to return values in js functions as well:
75
+
76
+ .define('get-list', function(){
77
+ return ['foo', 'bar', 'baz'];
78
+ })
79
+
70
80
  ### .define(name, fn)
71
81
 
72
- 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.
82
+ 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!
73
83
 
74
- 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`.
84
+ 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`.
75
85
 
76
86
  var stylus = require('../')
77
87
  , nodes = stylus.nodes
@@ -128,10 +138,10 @@ In our example we define four functions `add()`, `sub()`, `image-width()`, and `
128
138
  console.log(css);
129
139
  });
130
140
 
131
- For further reference until documentation is complete please reference the following files:
141
+ For further reference (until documentation is complete) please see the following files:
132
142
 
133
- - lib/nodes/*
134
- - lib/utils.js
143
+ - `lib/nodes/*`
144
+ - `lib/utils.js`
135
145
 
136
146
  ### .use(fn)
137
147
 
@@ -53,7 +53,9 @@ yielding:
53
53
 
54
54
  ## Expansion
55
55
 
56
- 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
56
+ By using `@keyframes`, your rules are automatically expanded to the vendor prefixes defined by the `vendors` variable (default: `webkit moz official`). This means we can alter it at any time for the expansion to take effect immediately.
57
+
58
+ For example, consider the following:
57
59
 
58
60
  @keyframes foo {
59
61
  from {
@@ -64,7 +66,7 @@ yielding:
64
66
  }
65
67
  }
66
68
 
67
- expands to our two default vendors and the official syntax:
69
+ This expands to our two default vendors, and the official syntax:
68
70
 
69
71
  @-moz-keyframes foo {
70
72
  0% {
@@ -94,7 +96,7 @@ expands to our two default vendors and the official syntax:
94
96
  }
95
97
  }
96
98
 
97
- if we wanted to limit to the official syntax only, simply alter `vendors`:
99
+ If we wanted to limit to the official syntax only, simply alter `vendors`:
98
100
 
99
101
  vendors = official
100
102
 
@@ -107,7 +109,7 @@ if we wanted to limit to the official syntax only, simply alter `vendors`:
107
109
  }
108
110
  }
109
111
 
110
- yielding:
112
+ Yielding:
111
113
 
112
114
  @keyframes foo {
113
115
  0% {
@@ -1,10 +1,9 @@
1
1
 
2
2
  ## Keyword Arguments
3
3
 
4
- Stylus supports keyword arguments, or "kwargs", allowing you to key
5
- arguments by their associated parameter name.
4
+ Stylus supports keyword arguments, or "kwargs". These allow you to reference arguents by their associated parameter name.
6
5
 
7
- The examples shown below are functionally equivalent, however we can
6
+ The examples shown below are functionally equivalent. However, we can
8
7
  place keyword arguments anywhere within the list. The remaining arguments
9
8
  that are _not_ keyed will be applied to the parameters that have not
10
9
  been satisfied.
@@ -16,7 +15,7 @@
16
15
  color: rgba(alpha: 0.5, blue: 100, 255, 200);
17
16
  }
18
17
 
19
- yielding:
18
+ Yielding:
20
19
 
21
20
  body {
22
21
  color: rgba(255,200,100,0.5);
@@ -30,6 +29,6 @@
30
29
 
31
30
  p(rgba)
32
31
 
33
- yielding:
32
+ Yielding:
34
33
 
35
34
  inspect: rgba(red, green, blue, alpha)
@@ -1,6 +1,6 @@
1
1
  ## Literal CSS
2
2
 
3
- If for any reason Stylus cannot accommodate a specific need, you can always resort to literal css via `@css`:
3
+ If for any reason Stylus cannot accommodate a specific need, you can always resort to literal CSS with `@css`:
4
4
 
5
5
 
6
6
  @css {
@@ -9,7 +9,7 @@
9
9
  }
10
10
  }
11
11
 
12
- compiling to:
12
+ Compiling to:
13
13
 
14
14
  body {
15
15
  font: 14px;
data/vendor/docs/media.md CHANGED
@@ -1,14 +1,14 @@
1
1
 
2
2
  ## @media
3
3
 
4
- The `@media` works just as it does within regular css, however with Stylus block notation:
4
+ The `@media` works just as it does within regular CSS, but with Stylus's block notation:
5
5
 
6
6
  @media print
7
7
  #header
8
8
  #footer
9
9
  display none
10
10
 
11
- yielding:
11
+ Yielding:
12
12
 
13
13
  @media print {
14
14
  #header,
@@ -1,7 +1,7 @@
1
1
 
2
2
  ## Connect Middleware
3
3
 
4
- Stylus ships with Connect middleware for auto-compiling Stylus sheets when modified.
4
+ Stylus ships with Connect middleware for auto-compiling Stylus sheets whenever they're modified.
5
5
 
6
6
  ## stylus.middleware(options)
7
7
 
@@ -26,7 +26,7 @@
26
26
  Here we set up the custom compile function so that we may
27
27
  alter the renderer by providing additional settings.
28
28
 
29
- By default the compile function simply sets the `filename`
29
+ By default, the compile function simply sets the `filename`
30
30
  and renders the CSS.
31
31
 
32
32
  function compile(str, path) {
@@ -38,10 +38,10 @@
38
38
  .set('compress', true);
39
39
  }
40
40
 
41
- Pass the middleware to Connect, grabbing .styl files from this directory
42
- and saving .css files to _./public_. Also supplying our custom `compile` function.
41
+ Pass the middleware to Connect, grabbing `.styl` files from this directory
42
+ and saving `.css` files to _./public_. Also supplying our custom `compile` function.
43
43
 
44
- Following that we have a `staticProvider` layer setup to serve the .css
44
+ Following that, we have a `staticProvider` layer setup to serve the `.css`
45
45
  files generated by Stylus.
46
46
 
47
47
  var stylus = require('stylus');
@@ -55,12 +55,11 @@
55
55
  , connect.staticProvider(__dirname + '/public')
56
56
  );
57
57
 
58
- When `force` is used, the styles will be unconditionally re-compiled, however
59
- even without this option the Stylus middleware is smart enough to detect changes in `@import`ed files.
58
+ When `force` is used, the styles will unconditionally be re-compiled. But even without this option, the Stylus middleware is smart enough to detect changes in `@import`ed files.
60
59
 
61
- For development purpose, you can enable the `firebug` option if you want to
60
+ For development purposes, you can enable the `firebug` option if you want to
62
61
  use the [FireStylus extension for Firebug](//github.com/LearnBoost/stylus/blob/master/docs/firebug.md)
63
- and/or the `linenos` option to emit debug infos in the generated css.
62
+ and/or the `linenos` option to emit debug info in the generated CSS.
64
63
 
65
64
  function compile(str, path) {
66
65
  return stylus(str)
@@ -1,7 +1,9 @@
1
1
 
2
2
  ## Mixins
3
3
 
4
- Both mixins and functions are defined in the same manor, however they are applied in different ways. For example we have a `border-radius(n)` function defined below, which is invoked as a _mixin_, aka a statement rather than part of an expression.
4
+ Both mixins and functions are defined in the same manner, but they are applied in different ways.
5
+
6
+ For example, we have a `border-radius(n)` function defined below, which is invoked as a _mixin_ (i.e., invoked as a statement, rather than part of an expression).
5
7
 
6
8
  When `border-radius()` is invoked within a selector, the properties are expanded and copied into the selector.
7
9
 
@@ -13,7 +15,7 @@ When `border-radius()` is invoked within a selector, the properties are expanded
13
15
  form input[type=button]
14
16
  border-radius(5px)
15
17
 
16
- compiles to:
18
+ Compiles to:
17
19
 
18
20
  form input[type=button] {
19
21
  -webkit-border-radius: 5px;
@@ -21,7 +23,7 @@ compiles to:
21
23
  border-radius: 5px;
22
24
  }
23
25
 
24
- When utilizing mixins, we can omit the parens all together, providing is with fantastic transparent vendor property support:
26
+ When using mixins you can omit the parentheses altogether, providing fantastic transparent vendor property support!
25
27
 
26
28
  border-radius(n)
27
29
  -webkit-border-radius n
@@ -31,16 +33,18 @@ When utilizing mixins, we can omit the parens all together, providing is with fa
31
33
  form input[type=button]
32
34
  border-radius 5px
33
35
 
34
- Note that the `border-radius` within our mixin is treated as a property, and not a recursive function invocation. To take this further we we may utilize the automatic `arguments` local variable, containing the expression passed, allowing more than one value to be passed:
36
+ Note that the `border-radius` within our mixin is treated as a property, and not a recursive function invocation.
37
+
38
+ To take this further, we can utilize the automatic `arguments` local variable, containing the expression passed, allowing multiple values to be passed:
35
39
 
36
40
  border-radius()
37
41
  -webkit-border-radius arguments
38
42
  -moz-border-radius arguments
39
43
  border-radius arguments
40
44
 
41
- now allowing us to pass values such as `border-radius 1px 2px / 3px 4px`.
45
+ Now we can pass values like `border-radius 1px 2px / 3px 4px`!
42
46
 
43
- Another great example of this, is adding transparent support for vendor specifics such as `opacity` support for IE:
47
+ Another great use of this is the addition of transparent support for vendor-specificssuch as `opacity` support for IE:
44
48
 
45
49
  support-for-ie ?= true
46
50
 
@@ -53,7 +57,7 @@ Another great example of this, is adding transparent support for vendor specific
53
57
  &:hover
54
58
  opacity 0.5
55
59
 
56
- rendering:
60
+ Rendering:
57
61
 
58
62
  #logo:hover {
59
63
  opacity: 0.5;
@@ -62,7 +66,9 @@ rendering:
62
66
 
63
67
  ### Parent References
64
68
 
65
- Mixins may utilize the parent reference character `&`, acting on the parent instead of further nesting. For example lets say we wish to create a `stripe(even, odd)` mixin for striping table row, we provide both `even` and `odd` with default color values, and assign the `background-color` property on the row. Nested within the `tr` we use `&` to reference the `tr`, providing the `even` color.
69
+ Mixins may utilize the parent reference character `&`, acting on the parent instead of further nesting.
70
+
71
+ For example, let's say we want to create a `stripe(even, odd)` mixin for striping table rows. We provide both `even` and `odd` with default color values, and assign the `background-color` property on the row. Nested within the `tr` we use `&` to reference the `tr`, providing the `even` color.
66
72
 
67
73
  stripe(even = #fff, odd = #eee)
68
74
  tr
@@ -83,7 +89,7 @@ We may then utilize the mixin as shown below:
83
89
  td
84
90
  color white
85
91
 
86
- Another way to define the `stripe()` mixin without parent reference:
92
+ Alternatively, `stripe()` could be defined without parent references:
87
93
 
88
94
  stripe(even = #fff, odd = #eee)
89
95
  tr
@@ -98,7 +104,9 @@ If we wished, we could invoke `stripe()` as if it were a property:
98
104
 
99
105
  ### Mixing Mixins in Mixins
100
106
 
101
- Mixins can of course utilize other mixins, to build up their own selector's and properties. For example, below we create `comma-list()` to inline (via `inline-list()`) and comma-separate an un-ordered list.
107
+ Mixins can (of course!) utilize other mixins, building upon their own selectors and properties.
108
+
109
+ For example, below we create `comma-list()` to inline (via `inline-list()`) and comma-separate an unordered list.
102
110
 
103
111
 
104
112
  inline-list()
@@ -116,7 +124,7 @@ If we wished, we could invoke `stripe()` as if it were a property:
116
124
  ul
117
125
  comma-list()
118
126
 
119
- rendering:
127
+ Rendering:
120
128
 
121
129
  ul li:after {
122
130
  content: ", ";