1<img align="right" width="111" height="111"
2     alt="CSSTree logo"
3     src="https://cloud.githubusercontent.com/assets/270491/19243723/6f9136c6-8f21-11e6-82ac-eeeee4c6c452.png"/>
4
5# CSSTree
6
7[![NPM version](https://img.shields.io/npm/v/css-tree.svg)](https://www.npmjs.com/package/css-tree)
8[![Build Status](https://travis-ci.org/csstree/csstree.svg?branch=master)](https://travis-ci.org/csstree/csstree)
9[![Coverage Status](https://coveralls.io/repos/github/csstree/csstree/badge.svg?branch=master)](https://coveralls.io/github/csstree/csstree?branch=master)
10[![NPM Downloads](https://img.shields.io/npm/dm/css-tree.svg)](https://www.npmjs.com/package/css-tree)
11[![Twitter](https://img.shields.io/badge/Twitter-@csstree-blue.svg)](https://twitter.com/csstree)
12
13CSSTree is a tool set to work with CSS, including [fast](https://github.com/postcss/benchmark) detailed parser (string->AST), walker (AST traversal), generator (AST->string) and lexer (validation and matching) based on knowledge of spec and browser implementations. The main goal is to be efficient and W3C spec compliant, with focus on CSS analyzing and source-to-source transforming tasks.
14
15> NOTE: The project is in alpha stage since some parts need further improvements, AST format and API are subjects to change. However it's stable enough and used by packages like [CSSO](https://github.com/css/csso) (CSS minifier) and [SVGO](https://github.com/svg/svgo) (SVG optimizer) in production.
16
17## Features
18
19- **Detailed parsing with an adjustable level of detail**
20
21  By default CSSTree parses CSS as detailed as possible, i.e. each single logical part is representing with its own AST node (see [AST format](docs/ast.md) for all possible node types). The parsing detail level can be changed through [parser options](docs/parsing.md#parsesource-options), for example, you can disable parsing of selectors or declaration values for component parts.
22
23- **Tolerant to errors by design**
24
25  Parser behaves as [spec says](https://www.w3.org/TR/css-syntax-3/#error-handling): "When errors occur in CSS, the parser attempts to recover gracefully, throwing away only the minimum amount of content before returning to parsing as normal". The only thing the parser departs from the specification is that it doesn't throw away bad content, but wraps it in a special node type (`Raw`) that allows processing it later.
26
27- **Fast and efficient**
28
29  CSSTree is created with focus on performance and effective memory consumption. Therefore it's [one of the fastest CSS parsers](https://github.com/postcss/benchmark) at the moment.
30
31- **Syntax validation**
32
33  The build-in lexer can test CSS against syntaxes defined by W3C. CSSTree uses [mdn/data](https://github.com/mdn/data/) as a basis for lexer's dictionaries and extends it with vendor specific and legacy syntaxes. Lexer can only check the declaration values currently, but this feature will be extended to other parts of the CSS in the future.
34
35## Docs
36
37- [AST format](docs/ast.md)
38- [Parsing CSS into AST](docs/parsing.md)
39- [Generate CSS from AST](docs/generate.md)
40- [AST traversal](docs/traversal.md)
41- [Utils for AST](docs/utils.md)
42- [Working with definition syntax](docs/definition-syntax.md)
43
44## Tools
45
46* [AST Explorer](https://astexplorer.net/#/gist/244e2fb4da940df52bf0f4b94277db44/e79aff44611020b22cfd9708f3a99ce09b7d67a8) – explore CSSTree AST format with zero setup
47* [CSS syntax reference](https://csstree.github.io/docs/syntax.html)
48* [CSS syntax validator](https://csstree.github.io/docs/validator.html)
49
50## Related projects
51
52* [csstree-validator](https://github.com/csstree/validator) – NPM package to validate CSS
53* [stylelint-csstree-validator](https://github.com/csstree/stylelint-validator) – plugin for stylelint to validate CSS
54* [Grunt plugin](https://github.com/sergejmueller/grunt-csstree-validator)
55* [Gulp plugin](https://github.com/csstree/gulp-csstree)
56* [Sublime plugin](https://github.com/csstree/SublimeLinter-contrib-csstree)
57* [VS Code plugin](https://github.com/csstree/vscode-plugin)
58* [Atom plugin](https://github.com/csstree/atom-plugin)
59
60## Usage
61
62Install with npm:
63
64
65```
66> npm install css-tree
67```
68
69Basic usage:
70
71```js
72var csstree = require('css-tree');
73
74// parse CSS to AST
75var ast = csstree.parse('.example { world: "!" }');
76
77// traverse AST and modify it
78csstree.walk(ast, function(node) {
79    if (node.type === 'ClassSelector' && node.name === 'example') {
80        node.name = 'hello';
81    }
82});
83
84// generate CSS from AST
85console.log(csstree.generate(ast));
86// .hello{world:"!"}
87```
88
89Syntax matching:
90
91```js
92// parse CSS to AST as a declaration value
93var ast = csstree.parse('red 1px solid', { context: 'value' });
94
95// march to syntax of `border` property
96var matchResult = csstree.lexer.matchProperty('border', ast);
97
98// check first value node is a <color>
99console.log(matchResult.isType(ast.children.first(), 'color'));
100// true
101
102// get a type list matched to a node
103console.log(matchResult.getTrace(ast.children.first()));
104// [ { type: 'Property', name: 'border' },
105//   { type: 'Type', name: 'color' },
106//   { type: 'Type', name: 'named-color' },
107//   { type: 'Keyword', name: 'red' } ]
108```
109
110## Top level API
111
112![API map](https://cdn.rawgit.com/csstree/csstree/master/docs/api-map.svg)
113
114## License
115
116MIT
117