API Documentation

Please use only this documented API when working with the parser. Methods not documented here are subject to change at any point.

parser function

This is the module's main entry point, and returns a new Parser.

```js let parser = require('postcss-values-parser');

let ast = parser(source) // tokenizes the source string .parse(); // parses the tokens and returns an AST ```

parser.atword([props])

Creates a new AtWord value.

js parser.atword({ value: '@foo' }); // → @foo

Arguments:

parser.colon([props])

Creates a new colon Node.

js parser.colon({ value: ':' }); // → :

Arguments:

parser.comma([props])

Creates a new comma Node.

js parser.comma({ value: ',' }); // → ,

Arguments:

parser.comment([props])

Creates a new comment.

js parser.comment({ value: 'Affirmative, Dave. I read you.' }); // → /* Affirmative, Dave. I read you. */

js parser.comment({ value: 'Affirmative, Dave. I read you.', inline: true }); // → // Affirmative, Dave. I read you.

Arguments:

parser.func([props])

Creates a new function value Container node.

```js let func = parser.func({ value: 'calc' });

func.append(parser.paren()); func.append(parser.paren({ value: ')' }));

func.toString(); // → calc() ```

Arguments:

parser.number([props])

Creates a new number Node.

js parser.number({ value: 10, unit: 'px' }); // → 10px

Arguments:

parser.operator([props])

Creates a new operator Node.

js parser.operator({ value: '+' }); // → +

Arguments:

parser.paren([props])

Creates a new parenthesis Node.

```js parser.paren(); // → (

parser.paren({ value: ')' }); // → ) ```

Arguments:

parser.string([props])

Creates a new string node.

```js parser.string(); // → (empty)

parser.string({ value: 'hello', quote: '"' }); // → "hello" ```

Arguments:

parser.value([props])

Creates a new value Node. This node acts as the container for all values within the Root node, but can be created for convenience.

parser.word([props])

Creates a new word Node. A Word is anything that doesn't fall into one of the other node types.

```js let word = parser.word({ value: '#fff' }); // → #fff

word.isHex; // → true

word.isColor; // → true ```

Arguments:

parser.unicodeRange([props])

Creates a new unicode range Node.

js parser.unicodeRange({ value: 'U+26' }); // → U+26

Arguments:

Node types

node.type

A string representation of the node type. It can be one of the following; atword, colon, comma, comment, func, number, operator, paren, string, unicoderange, value, word.

js parser.word({ value: '#fff' }).type; // → 'word'

node.parent

Returns the parent node.

js root.nodes[0].parent === root;

node.toString(), String(node), or '' + node

Returns a string representation of the node.

js let color = parser.word({ value: '#fff' }); console.log(String(color)); // → #fff

node.next() & node.prev()

Returns the next/previous child of the parent node.

js let next = func.next(); if (next && next.type !== 'paren') { throw new Error('Unclosed function parenthesis!'); }

node.replaceWith(node)

Replace a node with another.

```js let ast = parser('#fff').parse(); let word = ast.first.first; let atword = parser.atword({ value: '@purple' });

word.replaceWith(atword); ```

Arguments:

node.remove()

Removes the node from its parent node.

js if (node.type === 'word') { node.remove(); }

node.clone()

Returns a copy of a node, detached from any parent containers that the original might have had.

```js let word = parser.word({ value: '#fff' }); let cloned = word.clone();

cloned.value = '#fff'; String(cloned); // → #000

String(word); // → #fff ```

node.raws

Extra whitespaces around the node will be assigned to node.raws.before and node.raws.after. Spaces in this context have no semantic meaning, but may be useful for inspection:

css 1px solid black

Any space following a node/segement is assigned to the next node's raws.before property, unless the node with the trailing space is the only node in the set.

```js let source = 'calc(something about mary)'; let ast = parser(source).parse(); let func = ast.first.first;

let something = func.first.next(); let about = something.next();

something.raws.after; // → (empty)

about.raws.before; // → ' ' ```

Additionally, any space remaining after the last node in a set will be assigned to the last non-symbol child's raws.after property. For example:

```js let source = 'calc(something )'; let ast = parser(source).parse(); let func = ast.first.first;

let something = func.first.next(); something.raws.after; // → ' ' ```

node.source

An object describing the node's start/end, line/column source position.

Within the following CSS, the .bar class node ...

css .foo, .bar {}

... will contain the following source object.

js source: { start: { line: 2, column: 3 }, end: { line: 2, column: 6 } }

node.sourceIndex

The zero-based index of the node within the original source string.

Within the following CSS, the .baz class node will have a sourceIndex of 12.

css .foo, .bar, .baz {}

Container types

The root, node, and pseudo nodes have some helper methods for working with their children.

container.nodes

An array of the container's children.

js // Input: h1 h2 nodes.at(0).nodes.length // → 3 nodes.at(0).nodes[0].value // → 'h1' nodes.at(0).nodes[1].value // → ' '

container.first & container.last

The first/last child of the container.

js node.first === node.nodes[0]; node.last === node.nodes[node.nodes.length - 1];

container.at(index)

Returns the node at position index.

js node.at(0) === node.first; node.at(0) === node.nodes[0];

Arguments:

container.index(node)

Return the index of the node within its container.

js node.index(node.nodes[2]) // → 2

Arguments:

container.length

Proxy to the length of the container's nodes.

js container.length === container.nodes.length

container.each(callback)

Iterate the container's immediate children, calling callback for each child. You may return false within the callback to break the iteration.

js let className; nodes.each(function (node, index) { if (node.type === 'class') { className = node.value; return false; } });

Note that unlike Array#forEach(), this iterator is safe to use whilst adding or removing nodes from the container.

Arguments:

container.walk(callback)

Like container#each, but will also iterate child nodes as long as they are container types.

js nodes.walk(function (node, index) { // all nodes });

Arguments:

This iterator is safe to use whilst mutating container.nodes, like container#each.

container.walk proxies

The container class provides proxy methods for iterating over types of nodes, so that it is easier to write modules that target specific nodes. Those methods are:

container.prepend(node) & container.append(node)

Add a node to the start/end of the container. Note that doing so will set the parent property of the node to this container.

js let color = parser.word({ value: '#fff' }); node.append(color);

Arguments:

container.insertBefore(old, new) & container.insertAfter(old, new)

Add a node before or after an existing node in a container:

js nodes.walk(function (node) { if (node.type !== 'word') { let colon = parser.colon(); node.parent.insertAfter(node, colon); } });

Arguments:

container.removeChild(node)

Remove the node from the container. Note that you can also use node.remove() if you would like to remove just a single node.

js node.length // → 2 node.remove(word) node.length // → 1; word.parent // undefined

Arguments:

container.removeAll() or container.empty()

Remove all children from the container.

js node.removeAll(); node.length // → 0

Root nodes`

A root node represents the top-level Container for Value nodes. Indeed, all a root's toString() method does is join its node children with a ','. Other than this, it has no special functionality and acts like a container.

Value nodes

A Value node represents a single compound node. For example, this node string 1px solid black, is represented as three distinct nodes. It has no special functionality of its own.