sfcode An Online Competing and Development Environment

API Documentation

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

# <tt>parser</tt> function

This is the module's main entry point.

const parser = require('postcss-selector-parser');

## <tt>parser([transform], [options])</tt>

Creates a new `processor` instance

const processor = parser();
// or, with optional transform function
const transform = selectors => {
selectors.walkUniversals(selector => {
selector.remove();
});
};
const processor = parser(transform)
// Example
const result = processor.processSync('*.class');
// => .class

See processor documentation

Arguments:

- `transform (function)`: Provide a function to work with the parsed AST.
- `options (object)`: Provide default options for all calls on the returned `Processor`.

## <tt>parser.attribute([props])</tt>

Creates a new attribute selector.

parser.attribute({attribute: 'href'});
// => [href]

Arguments:

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

## <tt>parser.className([props])</tt>

Creates a new class selector.

parser.className({value: 'button'});
// => .button

Arguments:

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

## <tt>parser.combinator([props])</tt>

Creates a new selector combinator.

parser.combinator({value: '+'});
// => +

Arguments:

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

## <tt>parser.comment([props])</tt>

Creates a new comment.

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

Arguments:

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

## <tt>parser.id([props])</tt>

Creates a new id selector.

parser.id({value: 'search'});
// => #search

Arguments:

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

## <tt>parser.nesting([props])</tt>

Creates a new nesting selector.

parser.nesting();
// => &

Arguments:

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

## <tt>parser.pseudo([props])</tt>

Creates a new pseudo selector.

parser.pseudo({value: '::before'});
// => ::before

Arguments:

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

## <tt>parser.root([props])</tt>

Creates a new root node.

parser.root();
// => (empty)

Arguments:

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

## <tt>parser.selector([props])</tt>

Creates a new selector node.

parser.selector();
// => (empty)

Arguments:

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

## <tt>parser.string([props])</tt>

Creates a new string node.

parser.string();
// => (empty)

Arguments:

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

## <tt>parser.tag([props])</tt>

Creates a new tag selector.

parser.tag({value: 'button'});
// => button

Arguments:

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

## <tt>parser.universal([props])</tt>

Creates a new universal selector.

parser.universal();
// => *

Arguments:

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

# Node types

## <tt>node.type</tt>

A string representation of the selector type. It can be one of the following; `attribute`, `class`, `combinator`, `comment`, `id`, `nesting`, `pseudo`, `root`, `selector`, `string`, `tag`, or `universal`. Note that for convenience, these constants are exposed on the main `parser` as uppercased keys. So for example you can get `id` by querying `parser.ID`.

parser.attribute({attribute: 'href'}).type;
// => 'attribute'

## <tt>node.parent</tt>

Returns the parent node.

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

## <tt>node.toString()</tt>, <tt>String(node)</tt>, or ‘’' + node`

Returns a string representation of the node.

const id = parser.id({value: 'search'});
console.log(String(id));
// => #search

## <tt>node.next()</tt> & <tt>node.prev()</tt>

Returns the next/previous child of the parent node.

const next = id.next();
if (next && next.type !== 'combinator') {
throw new Error('Qualified IDs are not allowed!');
}

## <tt>node.replaceWith(node)</tt>

Replace a node with another.

const attr = selectors.first.first;
const className = parser.className({value: 'test'});
attr.replaceWith(className);

Arguments:

- `node`: The node to substitute the original with.

## <tt>node.remove()</tt>

Removes the node from its parent node.

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

## <tt>node.clone()</tt>

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

const cloned = parser.id({value: 'search'});
String(cloned);
// => #search

## <tt>node.spaces</tt>

Extra whitespaces around the node will be moved into `node.spaces.before` and `node.spaces.after`. So for example, these spaces will be moved as they have no semantic meaning:

h1 , h2 {}

However, combinating spaces will form a `combinator` node:

h1 h2 {}

A `combinator` node may only have the `spaces` property set if the combinator value is a non-whitespace character, such as `+`, `~` or `>`. Otherwise, the combinator value will contain all of the spaces between selectors.

## <tt>node.source</tt>

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

## <tt>node.sourceIndex</tt>

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`, `selector`, and `pseudo` nodes have some helper methods for working with their children.

## <tt>container.nodes</tt>

An array of the container's children.

// Input: h1 h2
selectors.at(0).nodes.length // => 3
selectors.at(0).nodes[0].value // => 'h1'
selectors.at(0).nodes[1].value // => ' '

## <tt>container.first</tt> & <tt>container.last</tt>

The first/last child of the container.

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

## <tt>container.at(index)</tt>

Returns the node at position `index`.

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

Arguments:

- `index`: The index of the node to return.

## <tt>container.index(node)</tt>

Return the index of the node within its container.

selector.index(selector.nodes[2]) // => 2

Arguments:

- `node`: A node within the current container.

## <tt>container.length</tt>

Proxy to the length of the container's nodes.

container.length === container.nodes.length

## <tt>container</tt> Array iterators

The container class provides proxies to certain Array methods; these are:

- `container.map === container.nodes.map`
- `container.reduce === container.nodes.reduce`
- `container.every === container.nodes.every`
- `container.some === container.nodes.some`
- `container.filter === container.nodes.filter`
- `container.sort === container.nodes.sort`

Note that these methods only work on a container's immediate children; recursive iteration is provided by `container.walk`.

## <tt>container.each(callback)</tt>

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

let className;
selectors.each((selector, index) => {
if (selector.type === 'class') {
className = selector.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.

## <tt>container.walk(callback)</tt>

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

selectors.walk((selector, 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`.

## <tt>container.walk</tt> proxies

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

- `container.walkAttributes`
- `container.walkClasses`
- `container.walkCombinators`
- `container.walkComments`
- `container.walkIds`
- `container.walkNesting`
- `container.walkPseudos`
- `container.walkTags`
- `container.walkUniversals`

## <tt>container.split(callback)</tt>

This method allows you to split a group of nodes by returning `true` from a callback. It returns an array of arrays, where each inner array corresponds to the groups that you created via the callback.

// (input) => h1 h2>>h3
const list = selectors.first.split(selector => {
return selector.type === 'combinator';
});
// (node values) => [['h1', ' '], ['h2', '>>'], ['h3']]

Arguments:

- `callback (function)`: A function to call for each node, which receives `node` as an argument.

## <tt>container.prepend(node)</tt> & <tt>container.append(node)</tt>

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.

const id = parser.id({value: 'search'});
selector.append(id);

Arguments:

- `node`: The node to add.

## <tt>container.insertBefore(old, new)</tt> & <tt>container.insertAfter(old, new)</tt>

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

selectors.walk(selector => {
if (selector.type !== 'class') {
const className = parser.className({value: 'theme-name'});
selector.parent.insertAfter(selector, className);
}
});

Arguments:

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

## <tt>container.removeChild(node)</tt>

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

selector.length // => 2
selector.remove(id)
selector.length // => 1;
id.parent // undefined

Arguments:

- `node`: The node to remove.

## <tt>container.removeAll()</tt> or <tt>container.empty()</tt>

Remove all children from the container.

selector.removeAll();
selector.length // => 0

# Root nodes

A root node represents a comma separated list of selectors. Indeed, all a root's `toString()` method does is join its selector children with a ','. Other than this, it has no special functionality and acts like a container.

## <tt>root.trailingComma</tt>

This will be set to `true` if the input has a trailing comma, in order to support parsing of legacy CSS hacks.

# Selector nodes

A selector node represents a single compound selector. For example, this selector string `h1 h2 h3, [href] > p`, is represented as two selector nodes. It has no special functionality of its own.

# Pseudo nodes

A pseudo selector extends a container node; if it has any parameters of its own (such as `h1:not(h2, h3)`), they will be its children. Note that the pseudo `value` will always contain the colons preceding the pseudo identifier. This is so that both `:before` and `::before` are properly represented in the AST.

# Attribute nodes

## <tt>attribute.quoted</tt>

Returns `true` if the attribute's value is wrapped in quotation marks, false if it is not. Remains `undefined` if there is no attribute value.

[href=foo] /* false */
[href='foo'] /* true */
[href="foo"] /* true */
[href] /* undefined */

## <tt>attribute.qualifiedAttribute</tt>

Returns the attribute name qualified with the namespace if one is given.

## <tt>attribute.offsetOf(part)</tt>

Returns the offset of the attribute part specified relative to the start of the node of the output string. This is useful in raising error messages about a specific part of the attribute, especially in combination with `attribute.sourceIndex`.

Returns `-1` if the name is invalid or the value doesn't exist in this attribute.

The legal values for `part` are:

- `"ns"` - alias for "namespace"
- `"namespace"` - the namespace if it exists.
- `"attribute"` - the attribute name
- `"attributeNS"` - the start of the attribute or its namespace
- `"operator"` - the match operator of the attribute
- `"value"` - The value (string or identifier)
- `"insensitive"` - the case insensitivity flag

## <tt>attribute.raws.unquoted</tt>

Returns the unquoted content of the attribute's value. Remains `undefined` if there is no attribute value.

[href=foo] /* foo */
[href='foo'] /* foo */
[href="foo"] /* foo */
[href] /* undefined */

## <tt>attribute.spaces</tt>

Like `node.spaces` with the `before` and `after` values containing the spaces around the element, the parts of the attribute can also have spaces before and after them. The for each of `attribute`, `operator`, `value` and `insensitive` there is corresponding property of the same nam in `node.spaces` that has an optional `before` or `after` string containing only whitespace.

Note that corresponding values in `attributes.raws.spaces` contain values including any comments. If set, these values will override the `attribute.spaces` value. Take care to remove them if changing `attribute.spaces`.

## <tt>attribute.raws</tt>

The raws object stores comments and other information necessary to re-render the node exactly as it was in the source.

If a comment is embedded within the identifiers for the `namespace`, `attribute` or `value` then a property is placed in the raws for that value containing the full source of the propery including comments.

If a comment is embedded within the space between parts of the attribute then the raw for that space is set accordingly.

Setting an attribute's property `raws` value to be deleted.

For now, changing the spaces required also updating or removing any of the raws values that override them.

Example: `[ /*before*/ href /* after-attr */ = /* after-operator */ te/*inside-value*/st/* wow */ /*omg*/i/*bbq*/ /*whodoesthis*/]` would parse as:

{
attribute: "href",
operatator: "=",
value: "test",
spaces: {
before: '',
after: '',
attribute: { before: ' ', after: ' ' },
operator: { after: ' ' },
value: { after: ' ' },
insensitive: { after: ' ' }
},
raws: {
spaces: {
attribute: { before: ' /*before*/ ', after: ' /* after-attr */ ' },
operator: { after: ' /* after-operator */ ' },
value: { after: '/* wow */ /*omg*/' },
insensitive: { after: '/*bbq*/ /*whodoesthis*/' }
},
unquoted: 'test',
value: 'te/*inside-value*/st'
}
}

# <tt>Processor</tt>

## <tt>ProcessorOptions</tt>

- `lossless` - When `true`, whitespace is preserved. Defaults to `true`.
- `updateSelector` - When `true`, if any processor methods are passed a postcss `Rule` node instead of a string, then that Rule's selector is updated with the results of the processing. Defaults to `true`.

## <tt>process|processSync(selectors, [options])</tt>

Processes the `selectors`, returning a string from the result of processing.

Note: when the `updateSelector` option is set, the rule's selector will be updated with the resulting string.

Example:

const parser = require("postcss-selector-parser");
const processor = parser();
let result = processor.processSync(' .class');
console.log(result);
// => .class
// Asynchronous operation
let promise = processor.process(' .class').then(result => {
console.log(result)
// => .class
});
// To have the parser normalize whitespace values, utilize the options
result = processor.processSync(' .class ', {lossless: false});
console.log(result);
// => .class
// For better syntax errors, pass a PostCSS Rule node.
const postcss = require('postcss');
rule = postcss.rule({selector: ' #foo > a, .class '});
processor.process(rule, {lossless: false, updateSelector: true}).then(result => {
console.log(result);
// => #foo>a,.class
console.log("rule:", rule.selector);
// => rule: #foo>a,.class
})

Arguments:

- `selectors (string|postcss.Rule)`: Either a selector string or a PostCSS Rule node.
- `[options] (object)`: Process options

## <tt>ast|astSync(selectors, [options])</tt>

Like `process()` and `processSync()` but after processing the `selectors` these methods return the `Root` node of the result instead of a string.

Note: when the `updateSelector` option is set, the rule's selector will be updated with the resulting string.

## <tt>transform|transformSync(selectors, [options])</tt>

Like `process()` and `processSync()` but after processing the `selectors` these methods return the value returned by the processor callback.

Note: when the `updateSelector` option is set, the rule's selector will be updated with the resulting string.

## Error Handling Within Selector Processors

The root node passed to the selector processor callback has a method `error(message, options)` that returns an error object. This method should always be used to raise errors relating to the syntax of selectors. The options to this method are passed to postcss's error constructor (documentation).

### Async Error Example

let processor = (root) => {
return new Promise((resolve, reject) => {
root.walkClasses((classNode) => {
if (/^(.*)[-_]/.test(classNode.value)) {
let msg = "classes may not have underscores or dashes in them";
reject(root.error(msg, {
index: classNode.sourceIndex + RegExp.$1.length + 1,
word: classNode.value
}));
}
});
resolve();
});
};
const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
return (root) => {
let promises = [];
root.walkRules(rule => {
promises.push(selectorProcessor.process(rule));
});
return Promise.all(promises);
};
});
postcss(plugin()).process(`
.foo-bar {
color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));
// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
// | ^
// 2 | color: red;
// 3 | }

### Synchronous Error Example

let processor = (root) => {
root.walkClasses((classNode) => {
if (/.*[-_]/.test(classNode.value)) {
let msg = "classes may not have underscores or dashes in them";
throw root.error(msg, {
index: classNode.sourceIndex,
word: classNode.value
});
}
});
};
const postcss = require("postcss");
const parser = require("postcss-selector-parser");
const selectorProcessor = parser(processor);
const plugin = postcss.plugin('classValidator', (options) => {
return (root) => {
root.walkRules(rule => {
selectorProcessor.processSync(rule);
});
};
});
postcss(plugin()).process(`
.foo-bar {
color: red;
}
`.trim(), {from: 'test.css'}).catch((e) => console.error(e.toString()));
// CssSyntaxError: classValidator: ./test.css:1:5: classes may not have underscores or dashes in them
//
// > 1 | .foo-bar {
// | ^
// 2 | color: red;
// 3 | }