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
functionThis is the module's main entry point.
parser([transform], [options])
parser([transform], [options])
Creates a new processor
instance
Arguments:
transform (function)
: Provide a function to work with the parsed AST.options (object)
: Provide default options for all calls on the returnedProcessor
.
parser.attribute([props])
parser.attribute([props])
Creates a new attribute selector.
Arguments:
props (object)
: The new node's properties.
parser.className([props])
parser.className([props])
Creates a new class selector.
Arguments:
props (object)
: The new node's properties.
parser.combinator([props])
parser.combinator([props])
Creates a new selector combinator.
Arguments:
props (object)
: The new node's properties.
parser.comment([props])
parser.comment([props])
Creates a new comment.
Arguments:
props (object)
: The new node's properties.
parser.id([props])
parser.id([props])
Creates a new id selector.
Arguments:
props (object)
: The new node's properties.
parser.nesting([props])
parser.nesting([props])
Creates a new nesting selector.
Arguments:
props (object)
: The new node's properties.
parser.pseudo([props])
parser.pseudo([props])
Creates a new pseudo selector.
Arguments:
props (object)
: The new node's properties.
parser.root([props])
parser.root([props])
Creates a new root node.
Arguments:
props (object)
: The new node's properties.
parser.selector([props])
parser.selector([props])
Creates a new selector node.
Arguments:
props (object)
: The new node's properties.
parser.string([props])
parser.string([props])
Creates a new string node.
Arguments:
props (object)
: The new node's properties.
parser.tag([props])
parser.tag([props])
Creates a new tag selector.
Arguments:
props (object)
: The new node's properties.
parser.universal([props])
parser.universal([props])
Creates a new universal selector.
Arguments:
props (object)
: The new node's properties.
Node types
node.type
node.type
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
.
node.parent
node.parent
Returns the parent node.
node.toString()
, String(node)
, or '' + node
node.toString()
, String(node)
, or '' + node
Returns a string representation of the node.
node.next()
& node.prev()
node.next()
& node.prev()
Returns the next/previous child of the parent node.
node.replaceWith(node)
node.replaceWith(node)
Replace a node with another.
Arguments:
node
: The node to substitute the original with.
node.remove()
node.remove()
Removes the node from its parent node.
node.clone()
node.clone()
Returns a copy of a node, detached from any parent containers that the original might have had.
node.spaces
node.spaces
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:
However, combinating spaces will form a combinator
node:
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.
node.source
node.source
An object describing the node's start/end, line/column source position.
Within the following CSS, the .bar
class node ...
... will contain the following source
object.
node.sourceIndex
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
.
Container types
The root
, selector
, and pseudo
nodes have some helper methods for working with their children.
container.nodes
container.nodes
An array of the container's children.
container.first
& container.last
container.first
& container.last
The first/last child of the container.
container.at(index)
container.at(index)
Returns the node at position index
.
Arguments:
index
: The index of the node to return.
container.index(node)
container.index(node)
Return the index of the node within its container.
Arguments:
node
: A node within the current container.
container.length
container.length
Proxy to the length of the container's nodes.
container
Array iterators
container
Array iteratorsThe 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
.
container.each(callback)
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.
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 receivesnode
andindex
arguments.
container.walk(callback)
container.walk(callback)
Like container#each
, but will also iterate child nodes as long as they are container
types.
Arguments:
callback (function)
: A function to call for each node, which receivesnode
andindex
arguments.
This iterator is safe to use whilst mutating container.nodes
, like container#each
.
container.walk
proxies
container.walk
proxiesThe 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
container.split(callback)
container.split(callback)
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.
Arguments:
callback (function)
: A function to call for each node, which receivesnode
as an argument.
container.prepend(node)
& container.append(node)
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.
Arguments:
node
: The node to add.
container.insertBefore(old, new)
& container.insertAfter(old, new)
container.insertBefore(old, new)
& container.insertAfter(old, new)
Add a node before or after an existing node in a container:
Arguments:
old
: The existing node in the container.new
: The new node to add before/after the existing node.
container.removeChild(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.
Arguments:
node
: The node to remove.
container.removeAll()
or container.empty()
container.removeAll()
or container.empty()
Remove all children from the container.
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.
root.trailingComma
root.trailingComma
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
attribute.quoted
attribute.quoted
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.
attribute.qualifiedAttribute
attribute.qualifiedAttribute
Returns the attribute name qualified with the namespace if one is given.
attribute.offsetOf(part)
attribute.offsetOf(part)
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
attribute.raws.unquoted
attribute.raws.unquoted
Returns the unquoted content of the attribute's value. Remains undefined
if there is no attribute value.
attribute.spaces
attribute.spaces
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
.
attribute.raws
attribute.raws
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:
Processor
Processor
ProcessorOptions
ProcessorOptions
lossless
- Whentrue
, whitespace is preserved. Defaults totrue
.updateSelector
- Whentrue
, if any processor methods are passed a postcssRule
node instead of a string, then that Rule's selector is updated with the results of the processing. Defaults totrue
.
process|processSync(selectors, [options])
process|processSync(selectors, [options])
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:
Arguments:
selectors (string|postcss.Rule)
: Either a selector string or a PostCSS Rule node.[options] (object)
: Process options
ast|astSync(selectors, [options])
ast|astSync(selectors, [options])
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.
transform|transformSync(selectors, [options])
transform|transformSync(selectors, [options])
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
Synchronous Error Example
Last updated