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
  • parser.atword([props])
  • parser.colon([props])
  • parser.comma([props])
  • parser.comment([props])
  • parser.func([props])
  • parser.number([props])
  • parser.operator([props])
  • parser.paren([props])
  • parser.string([props])
  • parser.value([props])
  • parser.word([props])
  • parser.unicodeRange([props])
• Node types
  • node.type
  • node.parent
  • node.toString(), String(node), or '' + node
  • node.next() & node.prev()
  • node.replaceWith(node)
  • node.remove()
  • node.clone()
  • node.raws
  • node.source
  • node.sourceIndex
• Container types
  • container.nodes
  • container.first & container.last
  • container.at(index)
  • container.index(node)
  • container.length
  • container.each(callback)
  • container.walk(callback)
  • container.walk proxies
  • container.prepend(node) & container.append(node)
  • container.insertBefore(old, new) & container.insertAfter(old, new)
  • container.removeChild(node)
  • container.removeAll() or container.empty()
• Root nodes`
• Value nodes

parser function

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

  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.

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

Arguments:

• props (object): The new node's properties.

parser.colon([props])

Creates a new colon Node.

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

Arguments:

• props (object): The new node's properties. If no properties are specified, the default value of : will be used. It's not recommended to deviate from this.

parser.comma([props])

Creates a new comma Node.

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

Arguments:

• props (object): The new node's properties. If no properties are specified, the default value of , will be used. It's not recommended to deviate from this.

parser.comment([props])

Creates a new comment.

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

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

Arguments:

• props (object): The new node's properties.

parser.func([props])

Creates a new function value Container node.

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

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

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

Arguments:

• props (object): The new node's properties.

parser.number([props])

Creates a new number Node.

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

Arguments:

• props (object): The new node's properties.

parser.operator([props])

Creates a new operator Node.

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

Arguments:

• props (object): The new node's properties.

parser.paren([props])

Creates a new parenthesis Node.

  parser.paren();
  // → (

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

Arguments:

• props (object): The new node's properties. If no value is specified, the default value of ( will be used.

parser.string([props])

Creates a new string node.

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

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

Arguments:

• props (object): The new node's properties. Note: If no quote property is specified, the default value of ' will be used.

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.

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

  word.isHex;
  // → true

  word.isColor;
  // → true

Arguments:

• props (object): The new node's properties.

parser.unicodeRange([props])

Creates a new unicode range Node.

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

Arguments:

• props (object): The new node's properties.

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.

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

node.parent

Returns the parent node.

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

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

Returns a string representation of the node.

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

node.next() & node.prev()

Returns the next/previous child of the parent node.

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

node.replaceWith(node)

Replace a node with another.

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

  word.replaceWith(atword);

Arguments:

• node: The node to substitute the original with.

node.remove()

Removes the node from its parent node.

  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.

  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:

    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.

  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:

  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 ...

.foo,
  .bar {}

... will contain the following source object.

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.

.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.

  // 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.

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

container.at(index)

Returns the node at position index.

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

Arguments:

• index: The index of the node to return.

container.index(node)

Return the index of the node within its container.

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

Arguments:

• node: A node within the current container.

container.length

Proxy to the length of the container's nodes.

  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.

  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:

• callback (function): A function to call for each node, which receives node and index arguments.

container.walk(callback)

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

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

Arguments:

• callback (function): A function to call for each node, which receives node and index 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.walkAtWords
• container.walkColons
• container.walkCommas
• container.walkComments
• container.walkFunctionNodes
• container.walkNumberNodes
• container.walkOperators
• container.walkParenthesis
• container.walkStringNodes
• container.walkUnicodeRanges
• container.walkWords

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.

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

Arguments:

• node: The node to add.

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

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

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

Arguments:

• old: The existing node in the container.
• new: The new node to add before/after the existing node.

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.

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

Arguments:

• node: The node to remove.

container.removeAll() or container.empty()

Remove all children from the container.

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.