suroh
/
work.suroh.tk
0
0
Fork 0
Code Pull Requests Actions Activity
work.suroh.tk/node_modules/postcss-values-parser/API.md

13 KiB
Raw Blame History

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.

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.