18
18
* [ Use] ( #use )
19
19
* [ API] ( #api )
20
20
* [ ` visit(tree[, test], visitor[, reverse]) ` ] ( #visittree-test-visitor-reverse )
21
+ * [ ` CONTINUE ` ] ( #continue )
22
+ * [ ` EXIT ` ] ( #exit )
23
+ * [ ` SKIP ` ] ( #skip )
24
+ * [ ` Action ` ] ( #action )
25
+ * [ ` ActionTuple ` ] ( #actiontuple )
26
+ * [ ` BuildVisitor ` ] ( #buildvisitor )
27
+ * [ ` Index ` ] ( #index )
28
+ * [ ` Test ` ] ( #test )
29
+ * [ ` Visitor ` ] ( #visitor )
30
+ * [ ` VisitorResult ` ] ( #visitorresult )
21
31
* [ Types] ( #types )
22
32
* [ Compatibility] ( #compatibility )
23
33
* [ Related] ( #related )
@@ -38,7 +48,7 @@ of parents.
38
48
## Install
39
49
40
50
This package is [ ESM only] [ esm ] .
41
- In Node.js (version 12.20+, 14.14+, 16.0+, 18 .0+), install with [ npm] [ ] :
51
+ In Node.js (version 14.14+ and 16 .0+), install with [ npm] [ ] :
42
52
43
53
``` sh
44
54
npm install unist-util-visit
@@ -47,14 +57,14 @@ npm install unist-util-visit
47
57
In Deno with [ ` esm.sh ` ] [ esmsh ] :
48
58
49
59
``` js
50
- import {visit } from " https://esm.sh/unist-util-visit@4"
60
+ import {visit } from ' https://esm.sh/unist-util-visit@4'
51
61
```
52
62
53
63
In browsers with [ ` esm.sh ` ] [ esmsh ] :
54
64
55
65
``` html
56
66
<script type =" module" >
57
- import {visit } from " https://esm.sh/unist-util-visit@4?bundle"
67
+ import {visit } from ' https://esm.sh/unist-util-visit@4?bundle'
58
68
</script >
59
69
```
60
70
@@ -86,29 +96,102 @@ Yields:
86
96
87
97
## API
88
98
89
- This package exports the identifiers ` visit ` , ` CONTINUE ` , ` SKIP ` , and ` EXIT ` .
99
+ This package exports the identifiers [ ` CONTINUE ` ] [ api-continue ] ,
100
+ [ ` EXIT ` ] [ api-exit ] , [ ` SKIP ` ] [ api-skip ] , and [ ` visit ` ] [ api-visit ] .
90
101
There is no default export.
91
102
92
103
### ` visit(tree[, test], visitor[, reverse]) `
93
104
94
105
This function works exactly the same as [ ` unist-util-visit-parents ` ] [ vp ] ,
95
- but ` visitor ` has a different signature.
106
+ but [ ` Visitor ` ] [ api-visitor ] has a different signature.
96
107
97
- #### ` next? = visitor(node, index, parent) `
108
+ ### ` CONTINUE `
98
109
99
- Instead of being passed an array of ancestors, ` visitor ` is called with the
100
- ` node ` ’s [ ` index ` ] [ index ] and its [ ` parent ` ] [ parent ] .
110
+ Continue traversing as normal (` true ` ).
101
111
102
- Please see [ ` unist-util-visit-parents ` ] [ vp ] .
112
+ ### ` EXIT `
113
+
114
+ Stop traversing immediately (` false ` ).
115
+
116
+ ### ` SKIP `
117
+
118
+ Do not traverse this node’s children (` 'skip' ` ).
119
+
120
+ ### ` Action `
121
+
122
+ Union of the action types (TypeScript type).
123
+ See [ ` Action ` in ` unist-util-visit-parents ` ] [ vp-action ] .
124
+
125
+ ### ` ActionTuple `
126
+
127
+ List with an action and an index (TypeScript type).
128
+ See [ ` ActionTuple ` in ` unist-util-visit-parents ` ] [ vp-actiontuple ] .
129
+
130
+ ### ` BuildVisitor `
131
+
132
+ Build a typed ` Visitor ` function from a tree and a test (TypeScript type).
133
+ See [ ` BuildVisitor ` in ` unist-util-visit-parents ` ] [ vp-buildvisitor ] .
134
+
135
+ ### ` Index `
136
+
137
+ Move to the sibling at ` index ` next (TypeScript type).
138
+ See [ ` Index ` in ` unist-util-visit-parents ` ] [ vp-index ] .
139
+
140
+ ### ` Test `
141
+
142
+ [ ` unist-util-is ` ] [ unist-util-is ] compatible test (TypeScript type).
143
+
144
+ ### ` Visitor `
145
+
146
+ Handle a node (matching ` test ` , if given) (TypeScript type).
147
+
148
+ Visitors are free to transform ` node ` .
149
+ They can also transform ` parent ` .
150
+
151
+ Replacing ` node ` itself, if ` SKIP ` is not returned, still causes its
152
+ descendants to be walked (which is a bug).
153
+
154
+ When adding or removing previous siblings of ` node ` (or next siblings, in
155
+ case of reverse), the ` Visitor ` should return a new ` Index ` to specify the
156
+ sibling to traverse after ` node ` is traversed.
157
+ Adding or removing next siblings of ` node ` (or previous siblings, in case
158
+ of reverse) is handled as expected without needing to return a new ` Index ` .
159
+
160
+ Removing the children property of ` parent ` still results in them being
161
+ traversed.
162
+
163
+ ###### Parameters
164
+
165
+ * ` node ` ([ ` Node ` ] [ node ] )
166
+ — found node
167
+ * ` index ` (` number ` or ` null ` )
168
+ — index of ` node ` in ` parent `
169
+ * ` parent ` ([ ` Node ` ] [ node ] or ` null ` )
170
+ — parent of ` node `
171
+
172
+ ###### Returns
173
+
174
+ What to do next.
175
+
176
+ An ` Index ` is treated as a tuple of ` [CONTINUE, Index] ` .
177
+ An ` Action ` is treated as a tuple of ` [Action] ` .
178
+
179
+ Passing a tuple back only makes sense if the ` Action ` is ` SKIP ` .
180
+ When the ` Action ` is ` EXIT ` , that action can be returned.
181
+ When the ` Action ` is ` CONTINUE ` , ` Index ` can be returned.
182
+
183
+ ### ` VisitorResult `
184
+
185
+ Any value that can be returned from a visitor (TypeScript type).
186
+ See [ ` VisitorResult ` in ` unist-util-visit-parents ` ] [ vp-visitorresult ] .
103
187
104
188
## Types
105
189
106
190
This package is fully typed with [ TypeScript] [ ] .
107
- It exports the additional types ` Test ` , ` VisitorResult ` , and ` Visitor ` .
108
-
109
- It also exports the types `BuildVisitor<Tree extends Node = Node, Check extends
110
- Test = string>` to properly type visitors from a tree and a test, from
111
- ` unist-util-visit-parents/complex-types.d.ts ` .
191
+ It exports the additional types [ ` Action ` ] [ api-action ] ,
192
+ [ ` ActionTuple ` ] [ api-actiontuple ] , [ ` BuildVisitor ` ] [ api-buildvisitor ] ,
193
+ [ ` Index ` ] [ api-index ] , [ ` Test ` ] [ api-test ] , [ ` Visitor ` ] [ api-visitor ] , and
194
+ [ ` VisitorResult ` ] [ api-visitorresult ] .
112
195
113
196
## Compatibility
114
197
@@ -196,8 +279,40 @@ abide by its terms.
196
279
197
280
[ unist ] : https://github.com/syntax-tree/unist
198
281
282
+ [ node ] : https://github.com/syntax-tree/unist#nodes
283
+
284
+ [ unist-util-is ] : https://github.com/syntax-tree/unist-util-is
285
+
199
286
[ vp ] : https://github.com/syntax-tree/unist-util-visit-parents
200
287
201
- [ index ] : https://github.com/syntax-tree/unist#index
288
+ [ vp-action ] : https://github.com/syntax-tree/unist-util-visit-parents#action
289
+
290
+ [ vp-actiontuple ] : https://github.com/syntax-tree/unist-util-visit-parents#actiontuple
291
+
292
+ [ vp-buildvisitor ] : https://github.com/syntax-tree/unist-util-visit-parents#buildvisitor
293
+
294
+ [ vp-index ] : https://github.com/syntax-tree/unist-util-visit-parents#index
295
+
296
+ [ vp-visitorresult ] : https://github.com/syntax-tree/unist-util-visit-parents#visitorresult
297
+
298
+ [ api-visit ] : #visittree-test-visitor-reverse
299
+
300
+ [ api-continue ] : #continue
301
+
302
+ [ api-exit ] : #exit
303
+
304
+ [ api-skip ] : #skip
305
+
306
+ [ api-action ] : #action
307
+
308
+ [ api-actiontuple ] : #actiontuple
309
+
310
+ [ api-buildvisitor ] : #buildvisitor
311
+
312
+ [ api-index ] : #index
313
+
314
+ [ api-test ] : #test
315
+
316
+ [ api-visitor ] : #visitor
202
317
203
- [ parent ] : https://github.com/syntax-tree/unist#parent-1
318
+ [ api-visitorresult ] : #visitorresult
0 commit comments