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