source: trip-planner-front/node_modules/postcss-value-parser/README.md@ 6fe77af

Last change on this file since 6fe77af was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 7.5 KB
Line 
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
5Transforms CSS declaration values and at-rule parameters into a tree of nodes, and provides a simple traversal API.
6
7## Usage
8
9```js
10var valueParser = require('postcss-value-parser');
11var cssBackgroundValue = 'url(foo.png) no-repeat 40px 73%';
12var parsedValue = valueParser(cssBackgroundValue);
13// parsedValue exposes an API described below,
14// e.g. parsedValue.walk(..), parsedValue.toString(), etc.
15```
16
17For 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
41If you wanted to convert each `rgba()` value in `sourceCSS` to a hex value, you could do so like this:
42
43```js
44var valueParser = require('postcss-value-parser');
45
46var parsed = valueParser(sourceCSS);
47
48// walk() will visit all the of the nodes in the tree,
49// invoking the callback for each.
50parsed.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
70parsed.toString(); // #E92D42
71```
72
73## Nodes
74
75Each 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
87The catch-all node type that includes keywords (e.g. `no-repeat`),
88quantities (e.g. `20px`, `75%`, `1.5`), and hex colors (e.g. `#e6e6e6`).
89
90Node-specific properties:
91
92- **value**: The "word" itself.
93
94### string
95
96A quoted string value, e.g. `"something"` in `content: "something";`.
97
98Node-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
106A divider, for example
107
108- `,` in `animation-duration: 1s, 2s, 3s`
109- `/` in `border-radius: 10px / 23px`
110- `:` in `(min-width: 700px)`
111
112Node-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
120Whitespace used as a separator, e.g. ` ` occurring twice in `border: 1px solid black;`.
121
122Node-specific properties:
123
124- **value**: The whitespace itself.
125
126### comment
127
128A CSS comment starts with `/*` and ends with `*/`
129
130Node-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
137A CSS function, e.g. `rgb(0,0,0)` or `url(foo.bar)`.
138
139Function nodes have nodes nested within them: the function arguments.
140
141Additional 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
151Media features surrounded by parentheses are considered functions with an
152empty 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
168whether 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### unicode-range
187
188The unicode-range CSS descriptor sets the specific range of characters to be
189used from a font defined by @font-face and made available
190for use on the current page (`unicode-range: U+0025-00FF`).
191
192Node-specific properties:
193
194- **value**: The "unicode-range" itself.
195
196## API
197
198```
199var valueParser = require('postcss-value-parser');
200```
201
202### valueParser.unit(quantity)
203
204Parses `quantity`, distinguishing the number from the unit. Returns an object like the following:
205
206```js
207// Given 2rem
208{
209 number: '2',
210 unit: 'rem'
211}
212```
213
214If the `quantity` argument cannot be parsed as a number, returns `false`.
215
216*This function does not parse complete values*: you cannot pass it `1px solid black` and expect `px` as
217the unit. Instead, you should pass it single quantities only. Parse `1px solid black`, then pass it
218the stringified `1px` node (a `word` node) to parse the number and unit.
219
220### valueParser.stringify(nodes[, custom])
221
222Stringifies a node or array of nodes.
223
224The `custom` function is called for each `node`; return a string to override the default behaviour.
225
226### valueParser.walk(nodes, callback[, bubble])
227
228Walks each provided node, recursively walking all descendent nodes within functions.
229
230Returning `false` in the `callback` will prevent traversal of descendent nodes (within functions).
231You can use this feature to for shallow iteration, walking over only the *immediate* children.
232*Note: This only applies if `bubble` is `false` (which is the default).*
233
234By default, the tree is walked from the outermost node inwards.
235To reverse the direction, pass `true` for the `bubble` argument.
236
237The `callback` is invoked with three arguments: `callback(node, index, nodes)`.
238
239- `node`: The current node.
240- `index`: The index of the current node.
241- `nodes`: The complete nodes array passed to `walk()`.
242
243Returns the `valueParser` instance.
244
245### var parsed = valueParser(value)
246
247Returns the parsed node tree.
248
249### parsed.nodes
250
251The array of nodes.
252
253### parsed.toString()
254
255Stringifies the node tree.
256
257### parsed.walk(callback[, bubble])
258
259Walks each node inside `parsed.nodes`. See the documentation for `valueParser.walk()` above.
260
261# License
262
263MIT © [Bogdan Chadkin](mailto:trysound@yandex.ru)
Note: See TracBrowser for help on using the repository browser.