You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use `--input-map` option to specify input source map if needed. Possible values for option:
80
-
81
-
-`auto` (default) - attempt to fetch input source map by follow steps:
82
-
- try to fetch inline map from input
83
-
- try to fetch source map filename from input and read its content
84
-
- (when `--input` is specified) check file with same name as input file but with `.map` extension exists and read its content
85
-
-`none` - don't use input source map; actually it's using to disable `auto`-fetching
86
-
- any other values treat as filename for input source map
87
-
88
-
Generally you shouldn't care about the input source map since defaults behaviour (`auto`) covers most use cases.
89
-
90
-
> NOTE: Input source map is using only if output source map is generating.
91
-
92
-
### Usage data
93
-
94
-
`CSSO` can use data about how `CSS` is using for better compression. File with this data (`JSON` format) can be set using `--usage` option. Usage data may contain follow sections:
95
-
96
-
-`tags` – white list of tags
97
-
-`ids` – white list of ids
98
-
-`classes` – white list of classes
99
-
-`scopes` – groups of classes which never used with classes from other groups on single element
100
-
101
-
All sections are optional. Value of `tags`, `ids` and `classes` should be array of strings, value of `scopes` should be an array of arrays of strings. Other values are ignoring.
102
-
103
-
#### Selector filtering
104
-
105
-
`tags`, `ids` and `classes` are using on clean stage to filter selectors that contains something that not in list. Selectors are filtering only by those kind of simple selector which white list is specified. For example, if only `tags` list is specified then type selectors are checking, and if selector hasn't any type selector (or even any type selector) it isn't filter.
106
-
107
-
> `ids` and `classes` names are case sensitive, `tags` – is not.
108
-
109
-
Input CSS:
110
-
111
-
```css
112
-
* { color: green; }
113
-
ul, ol, li { color: blue; }
114
-
UL.foo, span.bar { color: red; }
115
-
```
116
-
117
-
Usage data:
118
-
119
-
```json
120
-
{
121
-
"tags": ["ul", "LI"]
122
-
}
123
-
```
124
-
125
-
Result CSS:
126
-
127
-
```css
128
-
*{color:green}ul,li{color:blue}ul.foo{color:red}
129
-
```
130
-
131
-
#### Scopes
132
-
133
-
Scopes is designed for CSS scope isolation solutions such as [css-modules](https://github.com/css-modules/css-modules). Scopes are similar to namespaces and defines lists of class names that exclusively used on some markup. This information allows the optimizer to move rulesets more agressive. Since it assumes selectors from different scopes can't to be matched on the same element. That leads to better ruleset merging.
It can be assumed that first two rules are never used with the second two on the same markup. But we can't know that for sure without markup. The optimizer doesn't know it either and will perform safe transformations only. The result will be the same as input but with no spaces and some semicolons:
If class name doesn't specified in `scopes` it belongs to default "scope". `scopes` doesn't affect `classes`. If class name presents in `scopes` but missed in `classes` (both sections specified) it will be filtered.
169
-
170
-
Note that class name can't be specified in several scopes. Also selector can't has classes from different scopes. In both cases an exception throws.
171
-
172
-
Currently the optimizer doesn't care about out-of-bounds selectors order changing safety (i.e. selectors that may be matched to elements with no class name of scope, e.g. `.scope div` or `.scope ~ :last-child`) since assumes scoped CSS modules doesn't relay on it's order. It may be fix in future if to be an issue.
The same as `minify()` but for style block. Usually it's a `style` attribute content.
244
115
@@ -249,44 +120,7 @@ console.log(result.css);
249
120
// > color:red
250
121
```
251
122
252
-
#### parse(source[, options])
253
-
254
-
Parse CSS to AST.
255
-
256
-
> NOTE: Currenly parser omit redundant separators, spaces and comments (except exclamation comments, i.e. `/*! comment */`) on AST build, since those things are removing by compressor anyway.
257
-
258
-
Options:
259
-
260
-
- context `String` – parsing context, useful when some part of CSS is parsing (see below)
261
-
- positions `Boolean` – should AST contains node position or not, store data in `info` property of nodes (`false` by default)
262
-
- filename `String` – filename of source that adds to info when `positions` is true, uses for source map generation (`<unknown>` by default)
263
-
- line `Number` – initial line number, useful when parse fragment of CSS to compute correct positions
264
-
- column `Number` – initial column number, useful when parse fragment of CSS to compute correct positions
265
-
266
-
Contexts:
267
-
268
-
-`stylesheet` (default) – regular stylesheet, should be suitable in most cases
-`declaration` – declaration (`color: red` or `border: 1px solid black` for ruleset example)
276
-
-`value` – declaration value (`red` or `1px solid black` for ruleset example)
277
-
278
-
```js
279
-
// simple parsing with no options
280
-
var ast =csso.parse('.example { color: red }');
281
-
282
-
// parse with options
283
-
var ast =csso.parse('.foo.bar', {
284
-
context:'simpleSelector',
285
-
positions:true
286
-
});
287
-
```
288
-
289
-
#### compress(ast[, options])
123
+
### compress(ast[, options])
290
124
291
125
Does the main task – compress AST.
292
126
@@ -303,104 +137,95 @@ Options:
303
137
- usage `Object` - usage data for advanced optimisations (see [Usage data](#usage-data) for details)
304
138
- logger `Function` - function to track every step of transformations
305
139
306
-
#### clone(ast)
140
+
###Source maps
307
141
308
-
Make an AST node deep copy.
142
+
> TODO
309
143
310
-
```js
311
-
var orig =csso.parse('.test { color: red }');
312
-
var copy =csso.clone(orig);
144
+
### Usage data
313
145
314
-
csso.walk(copy, function(node) {
315
-
if (node.type==='Class') {
316
-
node.name='replaced';
317
-
}
318
-
});
146
+
`CSSO` can use data about how `CSS` is using for better compression. File with this data (`JSON` format) can be set using `usage` option. Usage data may contain follow sections:
319
147
320
-
console.log(csso.translate(orig));
321
-
// .test{color:red}
322
-
console.log(csso.translate(copy));
323
-
// .replaced{color:red}
324
-
```
148
+
-`tags` – white list of tags
149
+
-`ids` – white list of ids
150
+
-`classes` – white list of classes
151
+
-`scopes` – groups of classes which never used with classes from other groups on single element
325
152
326
-
#### translate(ast)
153
+
All sections are optional. Value of `tags`, `ids` and `classes` should be array of strings, value of `scopes` should be an array of arrays of strings. Other values are ignoring.
327
154
328
-
Converts AST to string.
155
+
#### Selector filtering
329
156
330
-
```js
331
-
var ast =csso.parse('.test { color: red }');
332
-
console.log(csso.translate(ast));
333
-
// > .test{color:red}
157
+
`tags`, `ids` and `classes` are using on clean stage to filter selectors that contains something that not in list. Selectors are filtering only by those kind of simple selector which white list is specified. For example, if only `tags` list is specified then type selectors are checking, and if selector hasn't any type selector (or even any type selector) it isn't filter.
158
+
159
+
> `ids` and `classes` names are case sensitive, `tags` – is not.
160
+
161
+
Input CSS:
162
+
163
+
```css
164
+
* { color: green; }
165
+
ul, ol, li { color: blue; }
166
+
UL.foo, span.bar { color: red; }
334
167
```
335
168
336
-
#### translateWithSourceMap(ast)
169
+
Usage data:
337
170
338
-
The same as `translate()` but also generates source map (nodes should contain positions in `info` property).
Scopes is designed for CSS scope isolation solutions such as [css-modules](https://github.com/css-modules/css-modules). Scopes are similar to namespaces and defines lists of class names that exclusively used on some markup. This information allows the optimizer to move rulesets more agressive. Since it assumes selectors from different scopes can't to be matched on the same element. That leads to better ruleset merging.
186
+
187
+
Suppose we have a file:
350
188
351
-
Visit all nodes of AST and call handler for each one. `handler` receives three arguments:
Context for handler an object, that contains references to some parent nodes:
197
+
It can be assumed that first two rules are never used with the second two on the same markup. But we can't know that for sure without markup. The optimizer doesn't know it either and will perform safe transformations only. The result will be the same as input but with no spaces and some semicolons:
358
198
359
-
- root – refers to `ast` or root node
360
-
- stylesheet – refers to closest `StyleSheet` node, it may be a top-level or at-rule block stylesheet
361
-
- atruleExpression – refers to `AtruleExpression` node if current node inside at-rule expression
362
-
- ruleset – refers to `Rule` node if current node inside a ruleset
363
-
- selector – refers to `Selector` node if current node inside a selector
364
-
- declaration – refers to `Declaration` node if current node inside a declaration
365
-
- function – refers to closest `Function` or `FunctionalPseudo` node if current node inside one of them
Same as `walk()` but visits `Rule` and `Atrule` nodes only.
220
+
If class name doesn't specified in `scopes` it belongs to default "scope". `scopes` doesn't affect `classes`. If class name presents in `scopes` but missed in `classes` (both sections specified) it will be filtered.
396
221
397
-
#### walkRulesRight(ast, handler)
222
+
Note that class name can't be specified in several scopes. Also selector can't has classes from different scopes. In both cases an exception throws.
398
223
399
-
Same as `walkRules()` but visits nodes in reverse order (from last to first).
224
+
Currently the optimizer doesn't care about out-of-bounds selectors order changing safety (i.e. selectors that may be matched to elements with no class name of scope, e.g. `.scope div` or `.scope ~ :last-child`) since assumes scoped CSS modules doesn't relay on it's order. It may be fix in future if to be an issue.
0 commit comments