|
| 1 | +import type acorn from './acorn.d.ts'; |
| 2 | + |
| 3 | +export type FullWalkerCallback<TState> = ( |
| 4 | + node: acorn.AnyNode, |
| 5 | + state: TState, |
| 6 | + type: string, |
| 7 | +) => void; |
| 8 | + |
| 9 | +export type FullAncestorWalkerCallback<TState> = ( |
| 10 | + node: acorn.AnyNode, |
| 11 | + state: TState, |
| 12 | + ancestors: acorn.AnyNode[], |
| 13 | + type: string, |
| 14 | +) => void; |
| 15 | + |
| 16 | +type AggregateType = { |
| 17 | + Expression: acorn.Expression; |
| 18 | + Statement: acorn.Statement; |
| 19 | + Pattern: acorn.Pattern; |
| 20 | + ForInit: acorn.VariableDeclaration | acorn.Expression; |
| 21 | +}; |
| 22 | + |
| 23 | +export type SimpleVisitors<TState> = |
| 24 | + & { |
| 25 | + [type in acorn.AnyNode['type']]?: (node: Extract<acorn.AnyNode, { type: type }>, state: TState) => void; |
| 26 | + } |
| 27 | + & { |
| 28 | + [type in keyof AggregateType]?: (node: AggregateType[type], state: TState) => void; |
| 29 | + }; |
| 30 | + |
| 31 | +export type AncestorVisitors<TState> = |
| 32 | + & { |
| 33 | + [type in acorn.AnyNode['type']]?: (node: Extract<acorn.AnyNode, { type: type }>, state: TState, ancestors: acorn.Node[]) => void; |
| 34 | + } |
| 35 | + & { |
| 36 | + [type in keyof AggregateType]?: (node: AggregateType[type], state: TState, ancestors: acorn.Node[]) => void; |
| 37 | + }; |
| 38 | + |
| 39 | +export type WalkerCallback<TState> = (node: acorn.Node, state: TState) => void; |
| 40 | + |
| 41 | +export type RecursiveVisitors<TState> = |
| 42 | + & { |
| 43 | + [type in acorn.AnyNode['type']]?: (node: Extract<acorn.AnyNode, { type: type }>, state: TState, callback: WalkerCallback<TState>) => void; |
| 44 | + } |
| 45 | + & { |
| 46 | + [type in keyof AggregateType]?: (node: AggregateType[type], state: TState, callback: WalkerCallback<TState>) => void; |
| 47 | + }; |
| 48 | + |
| 49 | +export type FindPredicate = (type: string, node: acorn.Node) => boolean; |
| 50 | + |
| 51 | +export interface Found<TState> { |
| 52 | + node: acorn.Node; |
| 53 | + state: TState; |
| 54 | +} |
| 55 | + |
| 56 | +/** |
| 57 | + * does a 'simple' walk over a tree |
| 58 | + * @param node the AST node to walk |
| 59 | + * @param visitors an object with properties whose names correspond to node types in the {@link https://github.com/estree/estree | ESTree spec}. The properties should contain functions that will be called with the node object and, if applicable the state at that point. |
| 60 | + * @param base a walker algorithm |
| 61 | + * @param state a start state. The default walker will simply visit all statements and expressions and not produce a meaningful state. (An example of a use of state is to track scope at each point in the tree.) |
| 62 | + */ |
| 63 | +export function simple<TState>( |
| 64 | + node: acorn.Node, |
| 65 | + visitors: SimpleVisitors<TState>, |
| 66 | + base?: RecursiveVisitors<TState>, |
| 67 | + state?: TState, |
| 68 | +): void; |
| 69 | + |
| 70 | +/** |
| 71 | + * does a 'simple' walk over a tree, building up an array of ancestor nodes (including the current node) and passing the array to the callbacks as a third parameter. |
| 72 | + * @param node |
| 73 | + * @param visitors |
| 74 | + * @param base |
| 75 | + * @param state |
| 76 | + */ |
| 77 | +export function ancestor<TState>( |
| 78 | + node: acorn.Node, |
| 79 | + visitors: AncestorVisitors<TState>, |
| 80 | + base?: RecursiveVisitors<TState>, |
| 81 | + state?: TState, |
| 82 | +): void; |
| 83 | + |
| 84 | +/** |
| 85 | + * does a 'recursive' walk, where the walker functions are responsible for continuing the walk on the child nodes of their target node. |
| 86 | + * @param node |
| 87 | + * @param state the start state |
| 88 | + * @param functions contain an object that maps node types to walker functions |
| 89 | + * @param base provides the fallback walker functions for node types that aren't handled in the {@link functions} object. If not given, the default walkers will be used. |
| 90 | + */ |
| 91 | +export function recursive<TState>( |
| 92 | + node: acorn.Node, |
| 93 | + state: TState, |
| 94 | + functions: RecursiveVisitors<TState>, |
| 95 | + base?: RecursiveVisitors<TState>, |
| 96 | +): void; |
| 97 | + |
| 98 | +/** |
| 99 | + * does a 'full' walk over a tree, calling the {@link callback} with the arguments (node, state, type) for each node |
| 100 | + * @param node |
| 101 | + * @param callback |
| 102 | + * @param base |
| 103 | + * @param state |
| 104 | + */ |
| 105 | +export function full<TState>( |
| 106 | + node: acorn.Node, |
| 107 | + callback: FullWalkerCallback<TState>, |
| 108 | + base?: RecursiveVisitors<TState>, |
| 109 | + state?: TState, |
| 110 | +): void; |
| 111 | + |
| 112 | +/** |
| 113 | + * does a 'full' walk over a tree, building up an array of ancestor nodes (including the current node) and passing the array to the callbacks as a third parameter. |
| 114 | + * @param node |
| 115 | + * @param callback |
| 116 | + * @param base |
| 117 | + * @param state |
| 118 | + */ |
| 119 | +export function fullAncestor<TState>( |
| 120 | + node: acorn.AnyNode, |
| 121 | + callback: FullAncestorWalkerCallback<TState>, |
| 122 | + base?: RecursiveVisitors<TState>, |
| 123 | + state?: TState, |
| 124 | +): void; |
| 125 | + |
| 126 | +/** |
| 127 | + * builds a new walker object by using the walker functions in {@link functions} and filling in the missing ones by taking defaults from {@link base}. |
| 128 | + * @param functions |
| 129 | + * @param base |
| 130 | + */ |
| 131 | +export function make<TState>( |
| 132 | + functions: RecursiveVisitors<TState>, |
| 133 | + base?: RecursiveVisitors<TState>, |
| 134 | +): RecursiveVisitors<TState>; |
| 135 | + |
| 136 | +/** |
| 137 | + * tries to locate a node in a tree at the given start and/or end offsets, which satisfies the predicate test. {@link start} and {@link end} can be either `null` (as wildcard) or a `number`. {@link test} may be a string (indicating a node type) or a function that takes (nodeType, node) arguments and returns a boolean indicating whether this node is interesting. {@link base} and {@link state} are optional, and can be used to specify a custom walker. Nodes are tested from inner to outer, so if two nodes match the boundaries, the inner one will be preferred. |
| 138 | + * @param node |
| 139 | + * @param start |
| 140 | + * @param end |
| 141 | + * @param type |
| 142 | + * @param base |
| 143 | + * @param state |
| 144 | + */ |
| 145 | +export function findNodeAt<TState>( |
| 146 | + node: acorn.AnyNode, |
| 147 | + start: number | undefined, |
| 148 | + end?: number | undefined, |
| 149 | + type?: FindPredicate | string, |
| 150 | + base?: RecursiveVisitors<TState>, |
| 151 | + state?: TState, |
| 152 | +): Found<TState> | undefined; |
| 153 | + |
| 154 | +/** |
| 155 | + * like {@link findNodeAt}, but will match any node that exists 'around' (spanning) the given position. |
| 156 | + * @param node |
| 157 | + * @param start |
| 158 | + * @param type |
| 159 | + * @param base |
| 160 | + * @param state |
| 161 | + */ |
| 162 | +export function findNodeAround<TState>( |
| 163 | + node: acorn.AnyNode, |
| 164 | + start: number | undefined, |
| 165 | + type?: FindPredicate | string, |
| 166 | + base?: RecursiveVisitors<TState>, |
| 167 | + state?: TState, |
| 168 | +): Found<TState> | undefined; |
| 169 | + |
| 170 | +/** |
| 171 | + * similar to {@link findNodeAround}, but will match all nodes after the given position (testing outer nodes before inner nodes). |
| 172 | + */ |
| 173 | +export const findNodeAfter: typeof findNodeAround; |
| 174 | + |
| 175 | +export const base: RecursiveVisitors<unknown>; |
0 commit comments