1 | # unist-util-visit
|
2 |
|
3 | [![Build][build-badge]][build]
|
4 | [![Coverage][coverage-badge]][coverage]
|
5 | [![Downloads][downloads-badge]][downloads]
|
6 | [![Size][size-badge]][size]
|
7 | [![Sponsors][sponsors-badge]][collective]
|
8 | [![Backers][backers-badge]][collective]
|
9 | [![Chat][chat-badge]][chat]
|
10 |
|
11 | [unist][] utility to walk the tree.
|
12 |
|
13 | ## Contents
|
14 |
|
15 | * [What is this?](#what-is-this)
|
16 | * [When should I use this?](#when-should-i-use-this)
|
17 | * [Install](#install)
|
18 | * [Use](#use)
|
19 | * [API](#api)
|
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)
|
31 | * [Types](#types)
|
32 | * [Compatibility](#compatibility)
|
33 | * [Related](#related)
|
34 | * [Contribute](#contribute)
|
35 | * [License](#license)
|
36 |
|
37 | ## What is this?
|
38 |
|
39 | This is a very important utility for working with unist as it lets you walk the
|
40 | tree.
|
41 |
|
42 | ## When should I use this?
|
43 |
|
44 | You can use this utility when you want to walk the tree.
|
45 | You can use [`unist-util-visit-parents`][vp] if you care about the entire stack
|
46 | of parents.
|
47 |
|
48 | ## Install
|
49 |
|
50 | This package is [ESM only][esm].
|
51 | In Node.js (version 16+), install with [npm][]:
|
52 |
|
53 | ```sh
|
54 | npm install unist-util-visit
|
55 | ```
|
56 |
|
57 | In Deno with [`esm.sh`][esmsh]:
|
58 |
|
59 | ```js
|
60 | import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5'
|
61 | ```
|
62 |
|
63 | In browsers with [`esm.sh`][esmsh]:
|
64 |
|
65 | ```html
|
66 | <script type="module">
|
67 | import {CONTINUE, EXIT, SKIP, visit} from 'https://esm.sh/unist-util-visit@5?bundle'
|
68 | </script>
|
69 | ```
|
70 |
|
71 | ## Use
|
72 |
|
73 | ```js
|
74 | import {fromMarkdown} from 'mdast-util-from-markdown'
|
75 | import {visit} from 'unist-util-visit'
|
76 |
|
77 | const tree = fromMarkdown('Some *emphasis*, **strong**, and `code`.')
|
78 |
|
79 | visit(tree, 'text', function (node, index, parent) {
|
80 | console.log([node.value, parent ? parent.type : index])
|
81 | })
|
82 | ```
|
83 |
|
84 | Yields:
|
85 |
|
86 | ```js
|
87 | [ 'Some ', 'paragraph' ]
|
88 | [ 'emphasis', 'emphasis' ]
|
89 | [ ', ', 'paragraph' ]
|
90 | [ 'strong', 'strong' ]
|
91 | [ ', and ', 'paragraph' ]
|
92 | [ '.', 'paragraph' ]
|
93 | ```
|
94 |
|
95 | ## API
|
96 |
|
97 | This package exports the identifiers [`CONTINUE`][api-continue],
|
98 | [`EXIT`][api-exit], [`SKIP`][api-skip], and [`visit`][api-visit].
|
99 | There is no default export.
|
100 |
|
101 | ### `visit(tree[, test], visitor[, reverse])`
|
102 |
|
103 | This function works exactly the same as [`unist-util-visit-parents`][vp],
|
104 | but [`Visitor`][api-visitor] has a different signature.
|
105 |
|
106 | ### `CONTINUE`
|
107 |
|
108 | Continue traversing as normal (`true`).
|
109 |
|
110 | ### `EXIT`
|
111 |
|
112 | Stop traversing immediately (`false`).
|
113 |
|
114 | ### `SKIP`
|
115 |
|
116 | Do not traverse this node’s children (`'skip'`).
|
117 |
|
118 | ### `Action`
|
119 |
|
120 | Union of the action types (TypeScript type).
|
121 | See [`Action` in `unist-util-visit-parents`][vp-action].
|
122 |
|
123 | ### `ActionTuple`
|
124 |
|
125 | List with an action and an index (TypeScript type).
|
126 | See [`ActionTuple` in `unist-util-visit-parents`][vp-action-tuple].
|
127 |
|
128 | ### `BuildVisitor`
|
129 |
|
130 | Build a typed `Visitor` function from a tree and a test (TypeScript type).
|
131 | See [`BuildVisitor` in `unist-util-visit-parents`][vp-build-visitor].
|
132 |
|
133 | ### `Index`
|
134 |
|
135 | Move to the sibling at `index` next (TypeScript type).
|
136 | See [`Index` in `unist-util-visit-parents`][vp-index].
|
137 |
|
138 | ### `Test`
|
139 |
|
140 | [`unist-util-is`][unist-util-is] compatible test (TypeScript type).
|
141 |
|
142 | ### `Visitor`
|
143 |
|
144 | Handle a node (matching `test`, if given) (TypeScript type).
|
145 |
|
146 | Visitors are free to transform `node`.
|
147 | They can also transform `parent`.
|
148 |
|
149 | Replacing `node` itself, if `SKIP` is not returned, still causes its
|
150 | descendants to be walked (which is a bug).
|
151 |
|
152 | When adding or removing previous siblings of `node` (or next siblings, in
|
153 | case of reverse), the `Visitor` should return a new `Index` to specify the
|
154 | sibling to traverse after `node` is traversed.
|
155 | Adding or removing next siblings of `node` (or previous siblings, in case
|
156 | of reverse) is handled as expected without needing to return a new `Index`.
|
157 |
|
158 | Removing the children property of `parent` still results in them being
|
159 | traversed.
|
160 |
|
161 | ###### Parameters
|
162 |
|
163 | * `node` ([`Node`][node])
|
164 | — found node
|
165 | * `index` (`number` or `undefined`)
|
166 | — index of `node` in `parent`
|
167 | * `parent` ([`Node`][node] or `undefined`)
|
168 | — parent of `node`
|
169 |
|
170 | ###### Returns
|
171 |
|
172 | What to do next.
|
173 |
|
174 | An `Index` is treated as a tuple of `[CONTINUE, Index]`.
|
175 | An `Action` is treated as a tuple of `[Action]`.
|
176 |
|
177 | Passing a tuple back only makes sense if the `Action` is `SKIP`.
|
178 | When the `Action` is `EXIT`, that action can be returned.
|
179 | When the `Action` is `CONTINUE`, `Index` can be returned.
|
180 |
|
181 | ### `VisitorResult`
|
182 |
|
183 | Any value that can be returned from a visitor (TypeScript type).
|
184 | See [`VisitorResult` in `unist-util-visit-parents`][vp-visitor-result].
|
185 |
|
186 | ## Types
|
187 |
|
188 | This package is fully typed with [TypeScript][].
|
189 | It exports the additional types [`Action`][api-action],
|
190 | [`ActionTuple`][api-action-tuple], [`BuildVisitor`][api-build-visitor],
|
191 | [`Index`][api-index], [`Test`][api-test], [`Visitor`][api-visitor], and
|
192 | [`VisitorResult`][api-visitor-result].
|
193 |
|
194 | ## Compatibility
|
195 |
|
196 | Projects maintained by the unified collective are compatible with maintained
|
197 | versions of Node.js.
|
198 |
|
199 | When we cut a new major release, we drop support for unmaintained versions of
|
200 | Node.
|
201 | This means we try to keep the current release line, `unist-util-visit@^5`,
|
202 | compatible with Node.js 16.
|
203 |
|
204 | ## Related
|
205 |
|
206 | * [`unist-util-visit-parents`][vp]
|
207 | — walk the tree with a stack of parents
|
208 | * [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
|
209 | — create a new tree with all nodes that pass a test
|
210 | * [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
|
211 | — create a new tree with all nodes mapped by a given function
|
212 | * [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
|
213 | — create a new tree by mapping (to an array) with the given function
|
214 | * [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
|
215 | — remove nodes from a tree that pass a test
|
216 | * [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
|
217 | — select nodes with CSS-like selectors
|
218 |
|
219 | ## Contribute
|
220 |
|
221 | See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
|
222 | ways to get started.
|
223 | See [`support.md`][support] for ways to get help.
|
224 |
|
225 | This project has a [code of conduct][coc].
|
226 | By interacting with this repository, organization, or community you agree to
|
227 | abide by its terms.
|
228 |
|
229 | ## License
|
230 |
|
231 | [MIT][license] © [Titus Wormer][author]
|
232 |
|
233 |
|
234 |
|
235 | [build-badge]: https://github.com/syntax-tree/unist-util-visit/workflows/main/badge.svg
|
236 |
|
237 | [build]: https://github.com/syntax-tree/unist-util-visit/actions
|
238 |
|
239 | [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit.svg
|
240 |
|
241 | [coverage]: https://codecov.io/github/syntax-tree/unist-util-visit
|
242 |
|
243 | [downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit.svg
|
244 |
|
245 | [downloads]: https://www.npmjs.com/package/unist-util-visit
|
246 |
|
247 | [size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=unist-util-visit
|
248 |
|
249 | [size]: https://bundlejs.com/?q=unist-util-visit
|
250 |
|
251 | [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
|
252 |
|
253 | [backers-badge]: https://opencollective.com/unified/backers/badge.svg
|
254 |
|
255 | [collective]: https://opencollective.com/unified
|
256 |
|
257 | [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
|
258 |
|
259 | [chat]: https://github.com/syntax-tree/unist/discussions
|
260 |
|
261 | [npm]: https://docs.npmjs.com/cli/install
|
262 |
|
263 | [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
|
264 |
|
265 | [esmsh]: https://esm.sh
|
266 |
|
267 | [typescript]: https://www.typescriptlang.org
|
268 |
|
269 | [license]: license
|
270 |
|
271 | [author]: https://wooorm.com
|
272 |
|
273 | [health]: https://github.com/syntax-tree/.github
|
274 |
|
275 | [contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
|
276 |
|
277 | [support]: https://github.com/syntax-tree/.github/blob/main/support.md
|
278 |
|
279 | [coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
|
280 |
|
281 | [unist]: https://github.com/syntax-tree/unist
|
282 |
|
283 | [node]: https://github.com/syntax-tree/unist#nodes
|
284 |
|
285 | [unist-util-is]: https://github.com/syntax-tree/unist-util-is
|
286 |
|
287 | [vp]: https://github.com/syntax-tree/unist-util-visit-parents
|
288 |
|
289 | [vp-action]: https://github.com/syntax-tree/unist-util-visit-parents#action
|
290 |
|
291 | [vp-action-tuple]: https://github.com/syntax-tree/unist-util-visit-parents#actiontuple
|
292 |
|
293 | [vp-build-visitor]: https://github.com/syntax-tree/unist-util-visit-parents#buildvisitor
|
294 |
|
295 | [vp-index]: https://github.com/syntax-tree/unist-util-visit-parents#index
|
296 |
|
297 | [vp-visitor-result]: https://github.com/syntax-tree/unist-util-visit-parents#visitorresult
|
298 |
|
299 | [api-visit]: #visittree-test-visitor-reverse
|
300 |
|
301 | [api-continue]: #continue
|
302 |
|
303 | [api-exit]: #exit
|
304 |
|
305 | [api-skip]: #skip
|
306 |
|
307 | [api-action]: #action
|
308 |
|
309 | [api-action-tuple]: #actiontuple
|
310 |
|
311 | [api-build-visitor]: #buildvisitor
|
312 |
|
313 | [api-index]: #index
|
314 |
|
315 | [api-test]: #test
|
316 |
|
317 | [api-visitor]: #visitor
|
318 |
|
319 | [api-visitor-result]: #visitorresult
|