Merge pull request #20 from davidtheclark/documentation-improvements

Documentation improvements

Author: TrySound

README.md

@@ -1,16 +1,25 @@
-[![Travis CI](https://travis-ci.org/TrySound/postcss-value-parser.svg)](https://travis-ci.org/TrySound/postcss-value-parser)
-
 # postcss-value-parser
 
-Transforms css values and at-rule params into the tree.
+[![Travis CI](https://travis-ci.org/TrySound/postcss-value-parser.svg)](https://travis-ci.org/TrySound/postcss-value-parser)
+
+Transforms CSS declaration values and at-rule parameters into a tree of nodes, and provides a simple traversal API.
 
 ## Usage
 
 ```js
-var parser = require('postcss-value-parser');
+var valueParser = require('postcss-value-parser');
+var cssBackgroundValue = 'url(foo.png) no-repeat 40px 73%';
+var parsedValue = valueParser(cssBackgroundValue);
+// parsedValue exposes an API described below,
+// e.g. parsedValue.walk(..), parsedValue.toString(), etc.
+```
 
-/*{
-    nodes: [
+For example, parsing the value `rgba(233, 45, 66, .5)` will return the following:
+
+```js
+{
+  nodes: [
+    {
       type: 'function',
       value: 'rgba',
       before: '',
@@ -24,116 +33,207 @@ var parser = require('postcss-value-parser');
         { type: 'div', value: ',', before: ' ', after: '' },
         { type: 'word', value: '.5' }
       ]
-    ]
-  }*/
-parser('rgba(233, 45, 66 ,.5)').walk(function (node) {
-  if (node.type === 'function' && node.value === 'rgba') {
-    var color = node.nodes.filter(function (node) {
-      return node.type === 'word';
-    }).map(function (node) {
-      return Number(node.value);
-    }); // [233, 45, 66, .5]
-
-    node.type = 'word';
-    node.value = convertToHex(color);
-  }
-}).toString(); // #E92D42
+    }
+  ]
+}
 ```
 
-### Prevent walking into function
+If you wanted to convert each `rgba()` value in `sourceCSS` to a hex value, you could do so like this:
 
 ```js
-parser('url(some url) 50% 50%')
-  .walk(function (node) {
-    // Your code
+var valueParser = require('postcss-value-parser');
 
-    if (node.type === 'function' && node.value === 'url') {
-      return false;
-    }
-  })
-  .toString();
-```
+var parsed = valueParser(sourceCSS);
+
+// walk() will visit all the of the nodes in the tree,
+// invoking the callback for each.
+parsed.walk(function (node) {
 
-### Url node
+  // Since we only want to transform rgba() values,
+  // we can ignore anything else.
+  if (node.type !== 'function' && node.value !== 'rgba') return;
 
+  // We can make an array of the rgba() arguments to feed to a
+  // convertToHex() function
+  var color = node.nodes.filter(function (node) {
+    return node.type === 'word';
+  }).map(function (node) {
+    return Number(node.value);
+  }); // [233, 45, 66, .5]
+
+  // Now we will transform the existing rgba() function node
+  // into a word node with the hex value
+  node.type = 'word';
+  node.value = convertToHex(color);
+})
+
+parsed.toString(); // #E92D42
 ```
-url( /path/to/image )
+
+## Nodes
+
+Each node is an object with these common properties:
+
+- **type**: The type of node (`word`, `string`, `div`, `space`, or `function`).
+  Each type is documented below.
+- **value**: Each node has a `value` property; but what exactly `value` means
+  is specific to the node type. Details are documented for each type below.
+- **sourceIndex**: The starting index of the node within the original source
+  string. For example, given the source string `10px 20px`, the `word` node
+  whose value is `20px` will have a `sourceIndex` of `5`.
+
+### word
+
+The catch-all node type that includes keywords (e.g. `no-repeat`),
+quantities (e.g. `20px`, `75%`, `1.5`), and hex colors (e.g. `#e6e6e6`).
+
+Node-specific properties:
+
+- **value**: The "word" itself.
+
+### string
+
+A quoted string value, e.g. `"something"` in `content: "something";`.
+
+Node-specific properties:
+
+- **value**: The text content of the string.
+- **quote**: The quotation mark surrounding the string, either `"` or `'`.
+
+### div
+
+A divider, for example
+
+- `,` in `animation-duration: 1s, 2s, 3s`
+- `/` in `border-radius: 10px / 23px`
+- `:` in `(min-width: 700px)`
+
+Node-specific properties:
+
+- **value**: The divider character. Either `,`, `/`, or `:` (see examples above).
+- **before**: Whitespace before the divider.
+- **after**: Whitespace after the divider.
+
+### space
+
+Whitespace used as a separator, e.g. ` ` occurring twice in `border: 1px solid black;`.
+
+Node-specific properties:
+
+- **value**: The whitespace itself.
+
+### function
+
+A CSS function, e.g. `rgb(0,0,0)` or `url(foo.bar)`.
+
+Function nodes have nodes nested within them: the function arguments.
+
+Additional properties:
+
+- **value**: The name of the function, e.g. `rgb` in `rgb(0,0,0)`.
+- **before**: Whitespace after the opening parenthesis and before the first argument,
+  e.g. `  ` in `rgb(  0,0,0)`.
+- **after**: Whitespace before the closing parenthesis and after the last argument,
+  e.g. `  ` in `rgb(0,0,0  )`.
+- **nodes**: More nodes representing the arguments to the function.
+
+Media features surrounded by parentheses are considered functions with an
+empty value. For example, `(min-width: 700px)` parses to these nodes:
+
+```js
+[
+  {
+    type: 'function', value: '', before: '', after: '',
+    nodes: [
+      { type: 'word', value: 'min-width' },
+      { type: 'div', value: ':', before: '', after: ' ' },
+      { type: 'word', value: '700px' }
+    ]
+  }
+]
 ```
 
-will be parsed to
+`url()` functions can be parsed a little bit differently depending on
+whether the first character in the argument is a quotation mark.
+
+`url( /gfx/img/bg.jpg )` parses to:
 
 ```js
-[{
-  type: 'function',
-  value: 'url',
-  before: ' ',
-  after: ' ',
-  nodes: [
-    { type: 'word', value: '/path/to/image' }
-  ]
-}]
+{ type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
+    { type: 'word', sourceIndex: 5, value: '/gfx/img/bg.jpg' }
+] }
 ```
 
-## Node types
+`url( "/gfx/img/bg.jpg" )`, on the other hand, parses to:
 
-- `{ type: 'word', value: 'any' }`
-- `{ type: 'string', value: 'string', quote: '"' }`
-- `{ type: 'string', value: 'string', quote: '\'' }`
-- `{ type: 'div', value: '/' , before: ' ', after: ' ' }`
-- `{ type: 'div', value: ',', before: ' ', after: ' ' }`
-- `{ type: 'div', value: ':', before: ' ', after: ' ' }`
-- `{ type: 'space', value: ' ' }` space as a separator
-- `{ type: 'function', value: 'name', before: '', after: '', nodes: [] }`
+```js
+{ type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
+     type: 'string', sourceIndex: 5, quote: '"', value: '/gfx/img/bg.jpg' },
+] }
+```
 
 ## API
 
 ```
 var valueParser = require('postcss-value-parser');
 ```
 
-### valueParser.unit(value)
+### valueParser.unit(quantity)
 
-Returns parsed value.
+Parses `quantity`, distinguishing the number from the unit. Returns an object like the following:
 
 ```js
-// .2rem
+// Given 2rem
 {
-  number: '.2',
+  number: '2',
   unit: 'rem'
 }
 ```
 
+If the `quantity` argument cannot be parsed as a number, returns `false`.
+
+*This function does not parse complete values*: you cannot pass it `1px solid black` and expect `px` as
+the unit. Instead, you should pass it single quantities only. Parse `1px solid black`, then pass it
+the stringified `1px` node (a `word` node) to parse the number and unit.
+
 ### valueParser.stringify(nodes)
 
-Stringifies node and array of nodes.
+Stringifies a node or array of nodes.
+
+### valueParser.walk(nodes, callback[, bubble])
+
+Walks each provided node, recursively walking all descendent nodes within functions.
 
-### valueParser.walk(nodes, cb[, bubble])
+Returning `false` in the `callback` will prevent traversal of descendent nodes (within functions).
+You can use this feature to for shallow iteration, walking over only the *immediate* children.
+*Note: This only applies if `bubble` is `false` (which is the default).*
 
-Walks each provided node, recursively for each node in a function.
+By default, the tree is walked from the outermost node inwards.
+To reverse the direction, pass `true` for the `bubble` argument.
 
-Returning `false` in the callback will prevent traversal of deeper, nested nodes(inside a function). You can use this to walk over only the immediate children. *note: This only applies if `bubble` is `false`(default).*
+The `callback` is invoked with three arguments: `callback(node, index, nodes)`.
 
-Returns `this` instance.
+- `node`: The current node.
+- `index`: The index of the current node.
+- `nodes`: The complete nodes array passed to `walk()`.
 
-- `nodes`: array - `value-parser` nodes
-- `cb(node, index, nodes)`: function - Function to execute for each node
-- `bubble`: boolean - Walk from the deepest nodes upwards
+Returns the `valueParser` instance.
 
-### var p = valueParser(value)
+### var parsed = valueParser(value)
 
-Returns parsed tree.
+Returns the parsed node tree.
 
-### p.nodes
+### parsed.nodes
 
-Root nodes list.
+The array of nodes.
 
-### p.toString()
+### parsed.toString()
 
-Stringify tree to the value.
+Stringifies the node tree.
 
-### p.walk(cb[, bubble])
+### parsed.walk(callback[, bubble])
 
-Walks each node since `p.nodes`.
+Walks each node inside `parsed.nodes`. See the documentation for `valueParser.walk()` above.
 
 # License