.config/coc/extensions/node_modules/coc-prettier/node_modules/postcss-value-parser/README.md

   1 # postcss-value-parser
   2
   3 [![Travis CI](https://travis-ci.org/TrySound/postcss-value-parser.svg)](https://travis-ci.org/TrySound/postcss-value-parser)
   4
   5 Transforms CSS declaration values and at-rule parameters into a tree of nodes, and provides a simple traversal API.
   6
   7 ## Usage
   8
   9 ```js
  10 var valueParser = require('postcss-value-parser');
  11 var cssBackgroundValue = 'url(foo.png) no-repeat 40px 73%';
  12 var parsedValue = valueParser(cssBackgroundValue);
  13 // parsedValue exposes an API described below,
  14 // e.g. parsedValue.walk(..), parsedValue.toString(), etc.
  15 ```
  16
  17 For example, parsing the value `rgba(233, 45, 66, .5)` will return the following:
  18
  19 ```js
  20 {
  21   nodes: [
  22     {
  23       type: 'function',
  24       value: 'rgba',
  25       before: '',
  26       after: '',
  27       nodes: [
  28         { type: 'word', value: '233' },
  29         { type: 'div', value: ',', before: '', after: ' ' },
  30         { type: 'word', value: '45' },
  31         { type: 'div', value: ',', before: '', after: ' ' },
  32         { type: 'word', value: '66' },
  33         { type: 'div', value: ',', before: ' ', after: '' },
  34         { type: 'word', value: '.5' }
  35       ]
  36     }
  37   ]
  38 }
  39 ```
  40
  41 If you wanted to convert each `rgba()` value in `sourceCSS` to a hex value, you could do so like this:
  42
  43 ```js
  44 var valueParser = require('postcss-value-parser');
  45
  46 var parsed = valueParser(sourceCSS);
  47
  48 // walk() will visit all the of the nodes in the tree,
  49 // invoking the callback for each.
  50 parsed.walk(function (node) {
  51
  52   // Since we only want to transform rgba() values,
  53   // we can ignore anything else.
  54   if (node.type !== 'function' && node.value !== 'rgba') return;
  55
  56   // We can make an array of the rgba() arguments to feed to a
  57   // convertToHex() function
  58   var color = node.nodes.filter(function (node) {
  59     return node.type === 'word';
  60   }).map(function (node) {
  61     return Number(node.value);
  62   }); // [233, 45, 66, .5]
  63
  64   // Now we will transform the existing rgba() function node
  65   // into a word node with the hex value
  66   node.type = 'word';
  67   node.value = convertToHex(color);
  68 })
  69
  70 parsed.toString(); // #E92D42
  71 ```
  72
  73 ## Nodes
  74
  75 Each node is an object with these common properties:
  76
  77 - **type**: The type of node (`word`, `string`, `div`, `space`, `comment`, or `function`).
  78   Each type is documented below.
  79 - **value**: Each node has a `value` property; but what exactly `value` means
  80   is specific to the node type. Details are documented for each type below.
  81 - **sourceIndex**: The starting index of the node within the original source
  82   string. For example, given the source string `10px 20px`, the `word` node
  83   whose value is `20px` will have a `sourceIndex` of `5`.
  84
  85 ### word
  86
  87 The catch-all node type that includes keywords (e.g. `no-repeat`),
  88 quantities (e.g. `20px`, `75%`, `1.5`), and hex colors (e.g. `#e6e6e6`).
  89
  90 Node-specific properties:
  91
  92 - **value**: The "word" itself.
  93
  94 ### string
  95
  96 A quoted string value, e.g. `"something"` in `content: "something";`.
  97
  98 Node-specific properties:
  99
 100 - **value**: The text content of the string.
 101 - **quote**: The quotation mark surrounding the string, either `"` or `'`.
 102 - **unclosed**: `true` if the string was not closed properly. e.g. `"unclosed string  `.
 103
 104 ### div
 105
 106 A divider, for example
 107
 108 - `,` in `animation-duration: 1s, 2s, 3s`
 109 - `/` in `border-radius: 10px / 23px`
 110 - `:` in `(min-width: 700px)`
 111
 112 Node-specific properties:
 113
 114 - **value**: The divider character. Either `,`, `/`, or `:` (see examples above).
 115 - **before**: Whitespace before the divider.
 116 - **after**: Whitespace after the divider.
 117
 118 ### space
 119
 120 Whitespace used as a separator, e.g. ` ` occurring twice in `border: 1px solid black;`.
 121
 122 Node-specific properties:
 123
 124 - **value**: The whitespace itself.
 125
 126 ### comment
 127
 128 A CSS comment starts with `/*` and ends with `*/`
 129
 130 Node-specific properties:
 131
 132 - **value**: The comment value without `/*` and `*/`
 133 - **unclosed**: `true` if the comment was not closed properly. e.g. `/* comment without an end  `.
 134
 135 ### function
 136
 137 A CSS function, e.g. `rgb(0,0,0)` or `url(foo.bar)`.
 138
 139 Function nodes have nodes nested within them: the function arguments.
 140
 141 Additional properties:
 142
 143 - **value**: The name of the function, e.g. `rgb` in `rgb(0,0,0)`.
 144 - **before**: Whitespace after the opening parenthesis and before the first argument,
 145   e.g. `  ` in `rgb(  0,0,0)`.
 146 - **after**: Whitespace before the closing parenthesis and after the last argument,
 147   e.g. `  ` in `rgb(0,0,0  )`.
 148 - **nodes**: More nodes representing the arguments to the function.
 149 - **unclosed**: `true` if the parentheses was not closed properly. e.g. `( unclosed-function  `.
 150
 151 Media features surrounded by parentheses are considered functions with an
 152 empty value. For example, `(min-width: 700px)` parses to these nodes:
 153
 154 ```js
 155 [
 156   {
 157     type: 'function', value: '', before: '', after: '',
 158     nodes: [
 159       { type: 'word', value: 'min-width' },
 160       { type: 'div', value: ':', before: '', after: ' ' },
 161       { type: 'word', value: '700px' }
 162     ]
 163   }
 164 ]
 165 ```
 166
 167 `url()` functions can be parsed a little bit differently depending on
 168 whether the first character in the argument is a quotation mark.
 169
 170 `url( /gfx/img/bg.jpg )` parses to:
 171
 172 ```js
 173 { type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
 174     { type: 'word', sourceIndex: 5, value: '/gfx/img/bg.jpg' }
 175 ] }
 176 ```
 177
 178 `url( "/gfx/img/bg.jpg" )`, on the other hand, parses to:
 179
 180 ```js
 181 { type: 'function', sourceIndex: 0, value: 'url', before: ' ', after: ' ', nodes: [
 182      type: 'string', sourceIndex: 5, quote: '"', value: '/gfx/img/bg.jpg' },
 183 ] }
 184 ```
 185
 186 ## API
 187
 188 ```
 189 var valueParser = require('postcss-value-parser');
 190 ```
 191
 192 ### valueParser.unit(quantity)
 193
 194 Parses `quantity`, distinguishing the number from the unit. Returns an object like the following:
 195
 196 ```js
 197 // Given 2rem
 198 {
 199   number: '2',
 200   unit: 'rem'
 201 }
 202 ```
 203
 204 If the `quantity` argument cannot be parsed as a number, returns `false`.
 205
 206 *This function does not parse complete values*: you cannot pass it `1px solid black` and expect `px` as
 207 the unit. Instead, you should pass it single quantities only. Parse `1px solid black`, then pass it
 208 the stringified `1px` node (a `word` node) to parse the number and unit.
 209
 210 ### valueParser.stringify(nodes[, custom])
 211
 212 Stringifies a node or array of nodes.
 213
 214 The `custom` function is called for each `node`; return a string to override the default behaviour.
 215
 216 ### valueParser.walk(nodes, callback[, bubble])
 217
 218 Walks each provided node, recursively walking all descendent nodes within functions.
 219
 220 Returning `false` in the `callback` will prevent traversal of descendent nodes (within functions).
 221 You can use this feature to for shallow iteration, walking over only the *immediate* children.
 222 *Note: This only applies if `bubble` is `false` (which is the default).*
 223
 224 By default, the tree is walked from the outermost node inwards.
 225 To reverse the direction, pass `true` for the `bubble` argument.
 226
 227 The `callback` is invoked with three arguments: `callback(node, index, nodes)`.
 228
 229 - `node`: The current node.
 230 - `index`: The index of the current node.
 231 - `nodes`: The complete nodes array passed to `walk()`.
 232
 233 Returns the `valueParser` instance.
 234
 235 ### var parsed = valueParser(value)
 236
 237 Returns the parsed node tree.
 238
 239 ### parsed.nodes
 240
 241 The array of nodes.
 242
 243 ### parsed.toString()
 244
 245 Stringifies the node tree.
 246
 247 ### parsed.walk(callback[, bubble])
 248
 249 Walks each node inside `parsed.nodes`. See the documentation for `valueParser.walk()` above.
 250
 251 # License
 252
 253 MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)