| 1 | 'use strict';
|
|---|
| 2 |
|
|---|
| 3 | var identity = require('./nodes/identity.js');
|
|---|
| 4 |
|
|---|
| 5 | const BREAK = Symbol('break visit');
|
|---|
| 6 | const SKIP = Symbol('skip children');
|
|---|
| 7 | const REMOVE = Symbol('remove node');
|
|---|
| 8 | /**
|
|---|
| 9 | * Apply a visitor to an AST node or document.
|
|---|
| 10 | *
|
|---|
| 11 | * Walks through the tree (depth-first) starting from `node`, calling a
|
|---|
| 12 | * `visitor` function with three arguments:
|
|---|
| 13 | * - `key`: For sequence values and map `Pair`, the node's index in the
|
|---|
| 14 | * collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
|
|---|
| 15 | * `null` for the root node.
|
|---|
| 16 | * - `node`: The current node.
|
|---|
| 17 | * - `path`: The ancestry of the current node.
|
|---|
| 18 | *
|
|---|
| 19 | * The return value of the visitor may be used to control the traversal:
|
|---|
| 20 | * - `undefined` (default): Do nothing and continue
|
|---|
| 21 | * - `visit.SKIP`: Do not visit the children of this node, continue with next
|
|---|
| 22 | * sibling
|
|---|
| 23 | * - `visit.BREAK`: Terminate traversal completely
|
|---|
| 24 | * - `visit.REMOVE`: Remove the current node, then continue with the next one
|
|---|
| 25 | * - `Node`: Replace the current node, then continue by visiting it
|
|---|
| 26 | * - `number`: While iterating the items of a sequence or map, set the index
|
|---|
| 27 | * of the next step. This is useful especially if the index of the current
|
|---|
| 28 | * node has changed.
|
|---|
| 29 | *
|
|---|
| 30 | * If `visitor` is a single function, it will be called with all values
|
|---|
| 31 | * encountered in the tree, including e.g. `null` values. Alternatively,
|
|---|
| 32 | * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
|
|---|
| 33 | * `Alias` and `Scalar` node. To define the same visitor function for more than
|
|---|
| 34 | * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
|
|---|
| 35 | * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
|
|---|
| 36 | * specific defined one will be used for each node.
|
|---|
| 37 | */
|
|---|
| 38 | function visit(node, visitor) {
|
|---|
| 39 | const visitor_ = initVisitor(visitor);
|
|---|
| 40 | if (identity.isDocument(node)) {
|
|---|
| 41 | const cd = visit_(null, node.contents, visitor_, Object.freeze([node]));
|
|---|
| 42 | if (cd === REMOVE)
|
|---|
| 43 | node.contents = null;
|
|---|
| 44 | }
|
|---|
| 45 | else
|
|---|
| 46 | visit_(null, node, visitor_, Object.freeze([]));
|
|---|
| 47 | }
|
|---|
| 48 | // Without the `as symbol` casts, TS declares these in the `visit`
|
|---|
| 49 | // namespace using `var`, but then complains about that because
|
|---|
| 50 | // `unique symbol` must be `const`.
|
|---|
| 51 | /** Terminate visit traversal completely */
|
|---|
| 52 | visit.BREAK = BREAK;
|
|---|
| 53 | /** Do not visit the children of the current node */
|
|---|
| 54 | visit.SKIP = SKIP;
|
|---|
| 55 | /** Remove the current node */
|
|---|
| 56 | visit.REMOVE = REMOVE;
|
|---|
| 57 | function visit_(key, node, visitor, path) {
|
|---|
| 58 | const ctrl = callVisitor(key, node, visitor, path);
|
|---|
| 59 | if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
|
|---|
| 60 | replaceNode(key, path, ctrl);
|
|---|
| 61 | return visit_(key, ctrl, visitor, path);
|
|---|
| 62 | }
|
|---|
| 63 | if (typeof ctrl !== 'symbol') {
|
|---|
| 64 | if (identity.isCollection(node)) {
|
|---|
| 65 | path = Object.freeze(path.concat(node));
|
|---|
| 66 | for (let i = 0; i < node.items.length; ++i) {
|
|---|
| 67 | const ci = visit_(i, node.items[i], visitor, path);
|
|---|
| 68 | if (typeof ci === 'number')
|
|---|
| 69 | i = ci - 1;
|
|---|
| 70 | else if (ci === BREAK)
|
|---|
| 71 | return BREAK;
|
|---|
| 72 | else if (ci === REMOVE) {
|
|---|
| 73 | node.items.splice(i, 1);
|
|---|
| 74 | i -= 1;
|
|---|
| 75 | }
|
|---|
| 76 | }
|
|---|
| 77 | }
|
|---|
| 78 | else if (identity.isPair(node)) {
|
|---|
| 79 | path = Object.freeze(path.concat(node));
|
|---|
| 80 | const ck = visit_('key', node.key, visitor, path);
|
|---|
| 81 | if (ck === BREAK)
|
|---|
| 82 | return BREAK;
|
|---|
| 83 | else if (ck === REMOVE)
|
|---|
| 84 | node.key = null;
|
|---|
| 85 | const cv = visit_('value', node.value, visitor, path);
|
|---|
| 86 | if (cv === BREAK)
|
|---|
| 87 | return BREAK;
|
|---|
| 88 | else if (cv === REMOVE)
|
|---|
| 89 | node.value = null;
|
|---|
| 90 | }
|
|---|
| 91 | }
|
|---|
| 92 | return ctrl;
|
|---|
| 93 | }
|
|---|
| 94 | /**
|
|---|
| 95 | * Apply an async visitor to an AST node or document.
|
|---|
| 96 | *
|
|---|
| 97 | * Walks through the tree (depth-first) starting from `node`, calling a
|
|---|
| 98 | * `visitor` function with three arguments:
|
|---|
| 99 | * - `key`: For sequence values and map `Pair`, the node's index in the
|
|---|
| 100 | * collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
|
|---|
| 101 | * `null` for the root node.
|
|---|
| 102 | * - `node`: The current node.
|
|---|
| 103 | * - `path`: The ancestry of the current node.
|
|---|
| 104 | *
|
|---|
| 105 | * The return value of the visitor may be used to control the traversal:
|
|---|
| 106 | * - `Promise`: Must resolve to one of the following values
|
|---|
| 107 | * - `undefined` (default): Do nothing and continue
|
|---|
| 108 | * - `visit.SKIP`: Do not visit the children of this node, continue with next
|
|---|
| 109 | * sibling
|
|---|
| 110 | * - `visit.BREAK`: Terminate traversal completely
|
|---|
| 111 | * - `visit.REMOVE`: Remove the current node, then continue with the next one
|
|---|
| 112 | * - `Node`: Replace the current node, then continue by visiting it
|
|---|
| 113 | * - `number`: While iterating the items of a sequence or map, set the index
|
|---|
| 114 | * of the next step. This is useful especially if the index of the current
|
|---|
| 115 | * node has changed.
|
|---|
| 116 | *
|
|---|
| 117 | * If `visitor` is a single function, it will be called with all values
|
|---|
| 118 | * encountered in the tree, including e.g. `null` values. Alternatively,
|
|---|
| 119 | * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
|
|---|
| 120 | * `Alias` and `Scalar` node. To define the same visitor function for more than
|
|---|
| 121 | * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
|
|---|
| 122 | * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
|
|---|
| 123 | * specific defined one will be used for each node.
|
|---|
| 124 | */
|
|---|
| 125 | async function visitAsync(node, visitor) {
|
|---|
| 126 | const visitor_ = initVisitor(visitor);
|
|---|
| 127 | if (identity.isDocument(node)) {
|
|---|
| 128 | const cd = await visitAsync_(null, node.contents, visitor_, Object.freeze([node]));
|
|---|
| 129 | if (cd === REMOVE)
|
|---|
| 130 | node.contents = null;
|
|---|
| 131 | }
|
|---|
| 132 | else
|
|---|
| 133 | await visitAsync_(null, node, visitor_, Object.freeze([]));
|
|---|
| 134 | }
|
|---|
| 135 | // Without the `as symbol` casts, TS declares these in the `visit`
|
|---|
| 136 | // namespace using `var`, but then complains about that because
|
|---|
| 137 | // `unique symbol` must be `const`.
|
|---|
| 138 | /** Terminate visit traversal completely */
|
|---|
| 139 | visitAsync.BREAK = BREAK;
|
|---|
| 140 | /** Do not visit the children of the current node */
|
|---|
| 141 | visitAsync.SKIP = SKIP;
|
|---|
| 142 | /** Remove the current node */
|
|---|
| 143 | visitAsync.REMOVE = REMOVE;
|
|---|
| 144 | async function visitAsync_(key, node, visitor, path) {
|
|---|
| 145 | const ctrl = await callVisitor(key, node, visitor, path);
|
|---|
| 146 | if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
|
|---|
| 147 | replaceNode(key, path, ctrl);
|
|---|
| 148 | return visitAsync_(key, ctrl, visitor, path);
|
|---|
| 149 | }
|
|---|
| 150 | if (typeof ctrl !== 'symbol') {
|
|---|
| 151 | if (identity.isCollection(node)) {
|
|---|
| 152 | path = Object.freeze(path.concat(node));
|
|---|
| 153 | for (let i = 0; i < node.items.length; ++i) {
|
|---|
| 154 | const ci = await visitAsync_(i, node.items[i], visitor, path);
|
|---|
| 155 | if (typeof ci === 'number')
|
|---|
| 156 | i = ci - 1;
|
|---|
| 157 | else if (ci === BREAK)
|
|---|
| 158 | return BREAK;
|
|---|
| 159 | else if (ci === REMOVE) {
|
|---|
| 160 | node.items.splice(i, 1);
|
|---|
| 161 | i -= 1;
|
|---|
| 162 | }
|
|---|
| 163 | }
|
|---|
| 164 | }
|
|---|
| 165 | else if (identity.isPair(node)) {
|
|---|
| 166 | path = Object.freeze(path.concat(node));
|
|---|
| 167 | const ck = await visitAsync_('key', node.key, visitor, path);
|
|---|
| 168 | if (ck === BREAK)
|
|---|
| 169 | return BREAK;
|
|---|
| 170 | else if (ck === REMOVE)
|
|---|
| 171 | node.key = null;
|
|---|
| 172 | const cv = await visitAsync_('value', node.value, visitor, path);
|
|---|
| 173 | if (cv === BREAK)
|
|---|
| 174 | return BREAK;
|
|---|
| 175 | else if (cv === REMOVE)
|
|---|
| 176 | node.value = null;
|
|---|
| 177 | }
|
|---|
| 178 | }
|
|---|
| 179 | return ctrl;
|
|---|
| 180 | }
|
|---|
| 181 | function initVisitor(visitor) {
|
|---|
| 182 | if (typeof visitor === 'object' &&
|
|---|
| 183 | (visitor.Collection || visitor.Node || visitor.Value)) {
|
|---|
| 184 | return Object.assign({
|
|---|
| 185 | Alias: visitor.Node,
|
|---|
| 186 | Map: visitor.Node,
|
|---|
| 187 | Scalar: visitor.Node,
|
|---|
| 188 | Seq: visitor.Node
|
|---|
| 189 | }, visitor.Value && {
|
|---|
| 190 | Map: visitor.Value,
|
|---|
| 191 | Scalar: visitor.Value,
|
|---|
| 192 | Seq: visitor.Value
|
|---|
| 193 | }, visitor.Collection && {
|
|---|
| 194 | Map: visitor.Collection,
|
|---|
| 195 | Seq: visitor.Collection
|
|---|
| 196 | }, visitor);
|
|---|
| 197 | }
|
|---|
| 198 | return visitor;
|
|---|
| 199 | }
|
|---|
| 200 | function callVisitor(key, node, visitor, path) {
|
|---|
| 201 | if (typeof visitor === 'function')
|
|---|
| 202 | return visitor(key, node, path);
|
|---|
| 203 | if (identity.isMap(node))
|
|---|
| 204 | return visitor.Map?.(key, node, path);
|
|---|
| 205 | if (identity.isSeq(node))
|
|---|
| 206 | return visitor.Seq?.(key, node, path);
|
|---|
| 207 | if (identity.isPair(node))
|
|---|
| 208 | return visitor.Pair?.(key, node, path);
|
|---|
| 209 | if (identity.isScalar(node))
|
|---|
| 210 | return visitor.Scalar?.(key, node, path);
|
|---|
| 211 | if (identity.isAlias(node))
|
|---|
| 212 | return visitor.Alias?.(key, node, path);
|
|---|
| 213 | return undefined;
|
|---|
| 214 | }
|
|---|
| 215 | function replaceNode(key, path, node) {
|
|---|
| 216 | const parent = path[path.length - 1];
|
|---|
| 217 | if (identity.isCollection(parent)) {
|
|---|
| 218 | parent.items[key] = node;
|
|---|
| 219 | }
|
|---|
| 220 | else if (identity.isPair(parent)) {
|
|---|
| 221 | if (key === 'key')
|
|---|
| 222 | parent.key = node;
|
|---|
| 223 | else
|
|---|
| 224 | parent.value = node;
|
|---|
| 225 | }
|
|---|
| 226 | else if (identity.isDocument(parent)) {
|
|---|
| 227 | parent.contents = node;
|
|---|
| 228 | }
|
|---|
| 229 | else {
|
|---|
| 230 | const pt = identity.isAlias(parent) ? 'alias' : 'scalar';
|
|---|
| 231 | throw new Error(`Cannot replace node with ${pt} parent`);
|
|---|
| 232 | }
|
|---|
| 233 | }
|
|---|
| 234 |
|
|---|
| 235 | exports.visit = visit;
|
|---|
| 236 | exports.visitAsync = visitAsync;
|
|---|
