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, and returns a new Parser
.
parser.atword([props])
parser.atword([props])
Creates a new AtWord value.
Arguments:
props (object)
: The new node's properties.
parser.colon([props])
parser.colon([props])
Creates a new colon Node.
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])
parser.comma([props])
Creates a new comma Node.
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])
parser.comment([props])
Creates a new comment.
Arguments:
props (object)
: The new node's properties.
parser.func([props])
parser.func([props])
Creates a new function value Container node.
Arguments:
props (object)
: The new node's properties.
parser.number([props])
parser.number([props])
Creates a new number Node.
Arguments:
props (object)
: The new node's properties.
parser.operator([props])
parser.operator([props])
Creates a new operator Node.
Arguments:
props (object)
: The new node's properties.
parser.paren([props])
parser.paren([props])
Creates a new parenthesis Node.
Arguments:
props (object)
: The new node's properties. If no value is specified, the default value of(
will be used.
parser.string([props])
parser.string([props])
Creates a new string node.
Arguments:
props (object)
: The new node's properties. Note: If noquote
property is specified, the default value of'
will be used.
parser.value([props])
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])
parser.word([props])
Creates a new word Node. A Word
is anything that doesn't fall into one of the other node types.
Arguments:
props (object)
: The new node's properties.
parser.unicodeRange([props])
parser.unicodeRange([props])
Creates a new unicode range Node.
Arguments:
props (object)
: The new node's properties.
Node types
node.type
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
.
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.raws
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:
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.
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:
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
, node
, 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.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 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)
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 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.
Last updated