source: trip-planner-front/node_modules/postcss-values-parser/README.md

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

initial commit

  • Property mode set to 100644
File size: 4.2 KB
Line 
1# postcss-values-parser [![Build Status](https://travis-ci.org/shellscape/postcss-values-parser.svg?branch=master)](https://travis-ci.org/shellscape/postcss-values-parser)
2
3<img align="right" width="95" height="95"
4 title="Philosopher’s stone, logo of PostCSS"
5 src="http://postcss.github.io/postcss/logo.svg">
6
7A CSS property value parser for use with [PostCSS](https://github.com/postcss/postcss),
8following the same node, container, and traversal patterns as PostCSS.
9
10## &nbsp;
11<p align="center">
12 <b>:rocket: &nbsp; Are you ready to tackle ES6 and hone your JavaScript Skills?</b> &nbsp; :rocket:<br/>
13 Check out these outstanding <a href="https://es6.io/">ES6 courses</a> by <a href="https://github.com/wesbos">@wesbos</a>
14</p>
15
16---
17
18As with PostCSS and postcss-selector-parser, this parser generates an
19[Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree),
20(aka "AST") which allows for ease of traversal and granular inspection of each
21part of a property's value.
22
23## postcss-values-parser vs. postcss-value-parser
24
25Yeah, it's a tad confusing. The [Lesshint](https://github.com/lesshint/lesshint)
26project needed a parser that would allow detailed inspection of property values
27to the same degree that PostCSS and [postcss-selector-parser](https://github.com/postcss/postcss-selector-parser)
28provided. This was especailly important for the Lesshint project, as it provides
29for very granular rules for linting LESS.
30
31[postcss-value-parser](https://github.com/TrySound/postcss-value-parser)
32makes a lot of assumption about how values should be parsed and how the resulting
33AST should be organized. It was also fairly out of sync with the tokenzing and
34traversal patterns and convenience methods found in PostCSS and
35postcss-selector-parser.
36
37So we needed an alternative, and drew upon all three projects to put together a
38value parser that met and exceeded our needs. The improvements include:
39
40- Written using ES6
41- Uses the same Gulp toolchain as PostCSS
42- Doesn't strip characters; eg. parenthesis
43- Full AST traversal
44- AST traversal based on node type
45- Simple methods to derive strings from the parsed result
46- Follows PostCSS patterns for whitespace between Nodes
47- Provides convenience properties for number units, colors, etc.
48
49## Usage
50
51Please see the [API Documentation](API.md) for full usage information.
52
53As with any NPM module, start with the install:
54
55```
56npm install postcss-values-parser
57```
58
59Using this parser is straightforward and doesn't require callbacks:
60
61```js
62const parser = require('postcss-values-parser');
63const ast = parser('#fff').parse();
64
65let color = ast // the Root node
66 .first // the Value node
67 .first; // a Word node, containing the color value.
68```
69
70## Loose Mode
71
72Loose mode was introduced to support adherence to the W3C CSS Specification as
73well as the ability to parse noncompliant CSS for variants like LESS, SCSS, and
74CSSNext. If you're working with a noncompliant or CSS-like variant, then loose
75mode is for you.
76
77For example, the parser
78will throw an error by default if `calc` parameters [don't adhere to the spec](https://www.w3.org/TR/css-values/#calc-syntax).
79However, with loose mode enabled, the parse will ignore spec rules and succeed.
80
81In-draft features, or CSS features in modules not yet finalized, often cause parser
82errors. eg. `url(var(--somevar))`. Loose mode supports parsing of these features.
83
84Loose Mode is enabled by passing an option of `loose: true` to the `parser` method.
85
86```js
87const less = 'calc(2+2)'; // not valid per spec, but valid in LESS
88const cssnext = 'url(var(--somevar))'; // not valid per spec, but in spec draft
89
90const parser = require('postcss-values-parser');
91const ast = parser(less, { loose: true }).parse();
92
93// parse will succeed
94```
95
96## Acknowledgements
97
98This project was heavily influenced by [postcss-selector-parser](https://github.com/postcss/postcss-selector-parser)
99and utilized many patterns and logical constructs from the project.
100
101Tests and some tokenizing techniques found in [postcss-value-parser](https://github.com/TrySound/postcss-value-parser)
102were used.
103
104## Contributing
105
106- `git fork/clone`
107- `npm i`
108- Before PR'ing, make sure `npm test` still pass. Add test if you're adding features.
109
110When you tweak [API.md](API.md), please run `npm run toc` before PR'ing.
Note: See TracBrowser for help on using the repository browser.