Arena

append a single child node. faster than appendChildren()

append children. same as appendChildren with an array

append tokens to a structured token field

append a single token. faster than appendTokens()

append tokens. same as appendTokens with an array

number of children

child node ids

drop the nodes that are not reachable from the root and renumber the remaining nodes in document order. the node ids change: ids obtained before the call (from visitors for instance) are no longer valid. the unused strings are dropped too

drop the interned strings that are no longer referenced by any node

copy the packed location of a node

detach a node from its parent

first token of a structured token field (single token fields: l and r of binary expressions, op, ...)

list node holding the tokens of a structured token field. created when missing

tokens of a structured token field

Search the ast subtree and return the first match, in document order

// find the first declaration which name is 'aspect-ratio'
import { EnumToken, transform } from "@tbela99/css-parser";

const result = await transform(css);
const arena = result.arena;

const node = arena.find(result.ast, (arena, node) =>
    arena.getType(node) == EnumToken.DeclarationNodeType && arena.getName(node) == 'aspect-ratio');

console.log(node == null ? null : arena.toObject(node));
Copy

Search the ast subtree and return all matches, in document order

Search the value tokens of the ast subtree and return the first match: the node that owns the token and the token

// find the first node which contains the length token '30px'
import { EnumToken, transform } from "@tbela99/css-parser";

const result = await transform(css);
const {node, value} = result.arena.findByValue(result.ast, (arena, value) =>
    arena.getType(value) == EnumToken.LengthTokenType && arena.getNumericValue(value) == 30 && arena.getUnit(value) == 'px') ?? {};
Copy

Search the ast subtree in reverse order and return the first match (the last node in document order)

find a token in the token list

Search a token and its descendants, or the value tokens of a node and their descendants, and return the first match

number of nodes the columns can hold before the arena grows. see getLastId for the last allocated id

first child of a node. 0 when the node has no children

first token of the token list of a node or of a token (declaration value, selector / prelude tokens, function arguments). 0 when the list is empty

last allocated node id. the ids of the arena are in the range 1 ... getLastId(), the detached nodes included

last token of the token list of a node or of a token. 0 when the list is empty

next sibling of a node or of a token. 0 for the last node / token of the list

previous sibling of a node or of a token. 0 for the first node / token of the list

number of interned strings

token at the given position of the token list

node that owns a value token: the declaration, the rule or the at-rule. 0 when the token is detached

parent of a value token: the node or the token that owns the token list, or the structured token that owns the field (the field list token is skipped). 0 when the token is detached

true if the field exists and is not empty

Interns a string and returns its unique ID. If the string has already been interned, it returns the existing ID.

true if the node is marked, see mark

mark nodes to be released or trimmed later, see release and trim. the library never releases nor trims the arena by itself

move the children of a node into another node, in order

prepend tokens to the token list

recycle a detached leaf node (no parent, no children, no tokens) that is no longer referenced: its id is reused by the next allocation. the record is zeroed, so a stale reference reads an empty node

release nodes: detach them and drop their data (interned strings, errors). node ids are never reused: the memory is reclaimed by trim

set node data for a given id. The first argument is the id, the second is the type, the third is the string value, the fourth is the numeric value, and the fifth is the unit.

set node data for a given id. The first argument is the id, the second is the type, the third is the string value, the fourth is the numeric value, and the fifth is the unit.

set node data for a given id. The first argument is the id, the second is the type, the third is the string value, and the fourth is the numeric value.

set node data for a given id. The first argument is the id, the second is the type, the third is the string value, the fourth is the numeric value, and the fifth is the unit.

replace the child at the given index. the node is appended when the index is out of range

replace the children. same as setChildren with an array

set the tokens of a structured token field

replace the first child

replace the first token

replace the last child

insert a node after another one

insert a node before another one

replace the token list. same as setTokens with an array

the children of the parent of a node, the node included

direct value tokens of a node or a token: the token list, then the tokens of the structured fields and the child tokens (fractions, unary expressions)

number of tokens in the token list

token ids of the token list: the declaration values, the selector / prelude tokens, the function arguments

reclaim the memory: release the marked nodes, then drop the nodes that are not reachable from the root and renumber the remaining ones, see compact. the ids obtained before the call are no longer valid

type of a node or a token. null when the id is null

call the visitor for the tokens and their children, in the order of walkValues (the children of a token are read after the visitor returns). no iterator or stack is created: use it when the visitor is not a closure

Walk the ast nodes: the node and its descendants, in document order. The iterator returns node ids (and value tokens when attributes is set). The children of a node are read when the next node is requested: the current node can be modified or detached by the caller.

import {EnumToken, transform, WalkerOptionEnum} from '@tbela99/css-parser';

const result = await transform(css);
const arena = result.arena;

for (const node of arena.walk(result.ast)) {

    console.log(EnumToken[arena.getType(node)], arena.getParent(node));
}

// the filter controls the walk, see WalkerOptionEnum
function filter(arena: AstArena, node: number) {

    if (arena.getType(node) == EnumToken.RuleNodeType && arena.getSelector(node).includes('html')) {

        // skip the children of the current node
        return WalkerOptionEnum.IgnoreChildren;
    }
}

for (const node of arena.walk(result.ast, filter)) {

    console.log(EnumToken[arena.getType(node)]);
}
Copy

Walk value tokens and their descendants (function arguments, structured token fields, ...), in document order. The iterator returns token ids. The children of a token are read when the next token is requested: the current token can be modified or replaced by the caller.

import {EnumToken, transform} from '@tbela99/css-parser';

const css = `
body { color:    color(from var(--base-color) display-p3 r calc(g + 0.24) calc(b + 0.15)); }
`;

const result = await transform(css);
const arena = result.arena;
const declaration = arena.getFirstChild(arena.getFirstChild(result.ast));

// walk the value tokens of the declaration in reverse order
for (const value of arena.walkValues(declaration, null, true)) {

    console.error([EnumToken[arena.getType(value)], arena.getValue(value)]);
}
Copy

Create an arena from the objects produced by Arena.toTransferableArenaObject. The column buffers are used as is (zero copy): the typed arrays are views on the given buffers.

Export the arena as a structured-cloneable object and the list of its column buffers, to send an arena to a worker (or back to the main thread) without copying the node data.

The properties (strings, errors, ...) are cloned by postMessage(), the column buffers are moved when they are passed as the transfer list: the source arena must not be used afterwards (its columns are detached). The buffers are copied instead when the transfer list is omitted.

// main thread
const [properties, transferables] = AstArena.toTransferableArenaObject(result.arena);

worker.postMessage({ ast: result.ast, properties, transferables }, transferables);

// worker
const { ast, properties, transferables } = event.data;
const arena = AstArena.fromTransferableArenaObjects(properties, transferables);
Copy