postcss-values-parser

What is postcss-values-parser?

The postcss-values-parser package is a tool for parsing CSS values, allowing developers to analyze and manipulate CSS strings in JavaScript. It provides a detailed AST (Abstract Syntax Tree) for CSS values, making it easier to understand and modify CSS properties programmatically.

What are postcss-values-parser's main functionalities?

Parsing CSS values

This feature allows you to parse any string representing CSS values into a structured AST. The code sample demonstrates parsing a simple CSS value string.

const parse = require('postcss-values-parser').parse;
let root = parse('10px solid black');
console.log(root.nodes);

Walking through the AST

After parsing CSS values into an AST, this feature enables walking through the AST nodes. This can be useful for analyzing or modifying specific parts of the CSS value.

const parse = require('postcss-values-parser').parse;
let root = parse('10px solid black');
root.walk((node) => console.log(node));

Modifying CSS values

This feature demonstrates how to modify CSS values after parsing. In the code sample, the size value of a CSS property is changed from '10px' to '15px'.

const parse = require('postcss-values-parser').parse;
let root = parse('10px solid black');
root.nodes[0].value = '15px';
console.log(root.toString());

Other packages similar to postcss-values-parser

css-tree

css-tree is a CSS parser that produces an AST for CSS documents. It offers similar functionality for parsing CSS but is more focused on entire stylesheets rather than individual values. Compared to postcss-values-parser, css-tree provides a broader scope of CSS parsing capabilities.

css-what

css-what is a package for parsing CSS selectors. It provides functionality to parse selector strings into an understandable format but does not focus on CSS properties or values. While it offers parsing capabilities, its focus is different from that of postcss-values-parser, which is more centered on CSS values.

README

postcss-values-parser

A CSS property value parser for use with PostCSS, following the same node, container, and traversal patterns as PostCSS.

As with PostCSS and postcss-selector-parser, this parser generates an Abstract Syntax Tree, (aka "AST") which allows for ease of traversal and granular inspection of each part of a property's value.

postcss-values-parser vs. postcss-value-parser

Yeah, it's a tad confusing. The Lesshint project needed a parser that would allow detailed inspection of property values to the same degree that PostCSS and postcss-selector-parser provided. This was especailly important for the Lesshint project, as it provides for very granular rules for linting LESS.

postcss-value-parser makes a lot of assumption about how values should be parsed and how the resulting AST should be organized. It was also fairly out of sync with the tokenzing and traversal patterns and convenience methods found in PostCSS and postcss-selector-parser.

So we needed an alternative, and drew upon all three projects to put together a value parser that met and exceeded our needs. The improvements include:

• Written using ES6
• Uses the same Gulp toolchain as PostCSS
• Doesn't strip characters; eg. parenthesis
• Full AST traversal
• AST traversal based on node type
• Simple methods to derive strings from the parsed result
• Follows PostCSS patterns for whitespace between Nodes
• Provides convenience properties for number units, colors, etc.

Usage

Please see the API Documentation for full usage information.

As with any NPM module, start with the install:

npm install postcss-values-parser

Using this parser is straightforward and doesn't require callbacks:

// ES6
let parser = require('postcss-values-parser');
let ast = parser('#fff').parse();

let color = ast       // the Root node
              .first  // the Value node
              .first; // a Word node, containing the color value.

// ES5
var parser = require('postcss-values-parser');
var ast = parser('#fff').parse();

var color = ast       // the Root node
              .first  // the Value node
              .first; // a Word node, containing the color value.

Acknowledgements

This project was heavily influenced by postcss-selector-parser and utilized many patterns and logical constructs from the project.

Tests and some tokenizing techniques found in postcss-value-parser and were used.