Skip to content

Latest commit

 

History

History
348 lines (272 loc) · 10.3 KB

traversal.md

File metadata and controls

348 lines (272 loc) · 10.3 KB

AST traversal

walk(ast, options)

Method visits each node of passed AST in a natural way and calls handlers for each one. It takes two arguments: a root node (ast) and an object (options). In simple case, it may take a function (handler) instead of options (walk(ast, fn) is equivalent to walk(ast, { enter: fn })).

import { parse, walk } from '@eslint/css-tree';

const ast = parse('.a { color: red; }');

walk(ast, function(node) {
    console.log(node.type);
});
// StyleSheet
// Rule
// SelectorList
// Selector
// ClassSelector
// Block
// Declaration
// Value
// Identifier

How it works:

  • Method uses structure field value of every node type to define the way how to iterate node's properties:
    • A function-iterator is generating for every node type.
    • Node's properties are iterated in the order as defined in structure (reverse option inverts the order).
    • Properties that are not defined in structure are ignored (won't be iterated over).
    • An exception is possible when a tree is not following to expected structure (e.g. AST was built outside the CSSTree parser or transformed in a wrong way). In case you are not sure about correctness of the tree structure, you may use try/catch or check the tree structure with csstree.lexer.checkStructure(ast) before iterating.
  • Only children field may contain a list of nested nodes. A list of nodes should a List instances. Since List class provides API similar to Array, traversal may work in cases when children is an array, but without any guarantee. Using arrays in AST is not recommended, use it on your own risk.

Walk visitor's function may return special values to control traversal:

  • walk.break or this.break – stops traversal, i.e. no visitor function will be invoked once this value is returned by a visitor;
  • walk.skip or this.skip – prevent current node from being iterated, i.e. no visitor function will be invoked for its properties or children nodes; note that this value only has an effect for enter visitor as leave visitor invokes after iterating over all node's properties and children.

NOTE: walk.break and walk.skip are only possible option for arrow functions, since such functions don't have their own this.

csstree.walk(ast, {
    enter(node) {
        if (node.type === 'Block') {
            return this.skip;
        }

        if (node.name === 'foo') {
            return this.break;
        }
    },
    leave: node => node.name === 'bar' ? csstree.walk.break : false
});

Options:

enter

Type: function or undefined Default: undefined

Handler on node entrance, i.e. before any nested node is processed.

import { parse, walk } from '@eslint/css-tree';

const ast = parse('.a { color: red; }');

walk(ast, {
    enter(node) {
        console.log(node.type);
    }
});
// StyleSheet
// Rule
// SelectorList
// Selector
// ClassSelector
// Block
// Declaration
// Value
// Identifier

In case options has a single enter field, it can be replaced for the handler passed as a value for enter, i.e. walk(ast, { enter: fn }) → walk(ast, fn).

Handler receives three arguments:

  • node – the AST node a walker entering to
  • item – node wrapper, that contains references to prev and next nodes in a list, and data reference for the node
  • list – is a reference for the list; it's useful for list operations like remove() or insert()

NOTE: If children is an array, the last two arguments are index and array, like for Array#forEach() or Array#map() methods.

import { parse, walk, generate } from '@eslint/css-tree';

const ast = parse(`
    .a { foo: 1; bar: 2; }
    .b { bar: 3; baz: 4; }
`);

// remove declarations with `bar` property from the tree
walk(ast, (node, item, list) => {
    if (node.type === 'Declaration' && node.property === 'bar' && list) {
        // remove a declaration from a list it
        list.remove(item);
    }
});

console.log(generate(ast));
// .a{foo:1}.b{baz:4}

NOTE:

  • item and list are not defined for nodes that are not in a list. Even Declaration can be outside any list in case it is a root of tree or a part of @supports prelude, e.g. @supports (bar: 123) { ... }. Therefore, it's recommended to check item or list are defined before using of it (those values both are defined or both are undefined, so it's enough to test one of them)
  • Only List instances are safe for tree transformations such as node removal. In case you perform such operations, you can ensure that all children in a tree is a List instances by calling csstree.fromPlainObject(ast) before traversal.
  • It's better to use visit option when possible to reach better performance

Context (this) for a handler is an object with a references to the closest ancestor nodes:

  • root – refers to AST root node (actually it's a node passed to walk() method)
  • stylesheet – refers to StyleSheet node, usually it's a root node
  • atrule – refers to closest Atrule node if any
  • atrulePrelude – refers to AtrulePrelude node if any
  • rule – refers to closest Rule node if any
  • selector – refers to SelectorList node if any
  • block - refers to closest Block node if any
  • declaration – refers to Declaration node if any
  • function – refers to closest Function, PseudoClassSelector or PseudoElementSelector node if current node inside one of them
import { parse, walk } from '@eslint/css-tree';

const ast = parse(`
    @import url(import.css);
    .foo { background: url('foo.jpg'); }
    .bar { background-image: url(bar.png); }
`);

// collect all urls in declarations
const urls = [];

walk(ast, function(node) {
    if (this.declaration !== null && node.type === 'Url') {
        urls.push(node.value);
    }
});

console.log(urls);
// [ 'foo.jpg', 'bar.png' ]

leave

Type: function or undefined Default: undefined

The same as enter handler but invokes on node exit, i.e. after all nested nodes are processed.

import { parse, walk } from '@eslint/css-tree';

const ast = parse('.a { color: red; }');

walk(ast, {
    leave(node) {
        console.log(node.type);
    }
});
// ClassSelector
// Selector
// SelectorList
// Identifier
// Value
// Declaration
// Block
// Rule
// StyleSheet

visit

Type: string or null Default: null

Invokes a handler for a specified node type only.

import { parse, walk } from '@eslint/css-tree';

const ast = parse('.a { color: red; } .b { color: green; }');

walk(ast, {
    visit: 'ClassSelector',
    enter(node) {
        console.log(node.name);
    }
});

// example above is equivalent to
walk(ast, {
    enter(node) {
        if (node.type === 'ClassSelector') {
            console.log(node.name);
        }
    }
});

The traversal for some node types can perform faster (10-15 times depending on the CSS structure), because some subtrees may to be skipped since they can't contain a node of specified type (e.g. Rule can't be used inside of Declaration, so declaration's subtree can be excluded from traversal path). Fast traversal is supported for node types:

  • Atrule
  • Rule
  • Declaration

NOTE: When fast traversal is applied, some nodes may not be reached in case of an incorrect location in the tree. That's may happen if AST was built outside the CSSTree parser or transformed in a wrong way. If you need to be 100% sure that every node of type will be visited (even in wrong position), don't use visit option and test node type by your own.

reverse

Type: boolean Default: false

Inverts the natural order of node traversing:

  • node's properties are iterated in reverse order to the node's structure definition
  • children nodes are iterated from last to first
import * as csstree from '@eslint/css-tree';

const ast = csstree.parse('.a { color: red; }');

csstree.walk(ast, {
    enter(node) {
        console.log(`enter ${node.type}`);
    },
    leave(node) {
        console.log(`leave ${node.type}`);
    }
});
// enter StyleSheet
// enter Rule
// enter SelectorList
// enter Selector
// enter ClassSelector
// leave ClassSelector
// leave Selector
// leave SelectorList
// enter Block
// enter Declaration
// enter Value
// enter Identifier
// leave Identifier
// leave Value
// leave Declaration
// leave Block
// leave Rule
// leave StyleSheet

csstree.walk(ast, {
    reverse: true,    // !!!
    enter(node) {
        console.log(`enter ${node.type}`);
    },
    leave(node) {
        console.log(`leave ${node.type}`);
    }
});
// enter StyleSheet
// enter Rule
// enter Block
// enter Declaration
// enter Value
// enter Identifier
// leave Identifier
// leave Value
// leave Declaration
// leave Block
// enter SelectorList
// enter Selector
// enter ClassSelector
// leave ClassSelector
// leave Selector
// leave SelectorList
// leave Rule
// leave StyleSheet

find(ast, fn)

Returns the first node in natural order for which fn function returns a truthy value.

import * as csstree from '@eslint/css-tree';

const ast = csstree.parse('.a { color: red; } .b { color: green; }');

const firstColorDeclaration = csstree.find(ast, (node, item, list) =>
    node.type === 'Declaration' && node.property === 'color'
);

console.log(csstree.generate(firstColorDeclaration));
// color:red

findLast(ast, fn)

Returns the first node in reverse order for which fn function returns a truthy value.

import * as csstree from '@eslint/css-tree';

const ast = csstree.parse('.a { color: red; } .b { color: green; }');

const firstColorDeclaration = csstree.findLast(ast, (node, item, list) =>
    node.type === 'Declaration' && node.property === 'color'
);

console.log(csstree.generate(firstColorDeclaration));
// color:green

findAll(ast, fn)

Returns all nodes in natural order for which fn function returns a truthy value.

import * as csstree from '@eslint/css-tree';

const ast = csstree.parse('.a { color: red; } .b { color: green; }');

const colorDeclarations = csstree.findAll(ast, (node, item, list) =>
    node.type === 'Declaration' && node.property === 'color'
);

console.log(colorDeclarations.map(decl => csstree.generate(decl)).join(', '));
// color:red, color:green