1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
# unist-util-visit-parents
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
[![Sponsors][sponsors-badge]][collective]
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]
[**unist**][unist] utility to visit nodes, with ancestral information.
## Install
[npm][]:
```sh
npm install unist-util-visit-parents
```
## Usage
```js
var remark = require('remark')
var visit = require('unist-util-visit-parents')
var tree = remark.parse('Some _emphasis_, **importance**, and `code`.')
visit(tree, 'strong', visitor)
function visitor(node, ancestors) {
console.log(ancestors)
}
```
Yields:
```js
[ { type: 'root', children: [ [Object] ] },
{ type: 'paragraph',
children:
[ [Object],
[Object],
[Object],
[Object],
[Object],
[Object],
[Object] ] } ]
```
## API
### `visit(tree[, test], visitor[, reverse])`
Visit nodes ([**inclusive descendants**][descendant] of [`tree`][tree]), with
ancestral information. Optionally filtering nodes. Optionally in reverse.
###### Parameters
* `tree` ([`Node`][node]) — [Tree][] to traverse
* `test` ([`Test`][is], optional) — [`is`][is]-compatible test (such as a
[type][])
* `visitor` ([Function][visitor]) — Function invoked when a node is found
that passes `test`
* `reverse` (`boolean`, default: `false`) — The tree is walked in [preorder][]
(NLR), visiting the node itself, then its [head][], etc.
When `reverse` is passed, the tree is stilled walked in preorder, but now
in NRL (the node itself, then its [tail][], etc.)
#### `next? = visitor(node, ancestors)`
Invoked when a node (matching `test`, if given) is found.
Visitors are free to transform `node`.
They can also transform the [parent][] of node (the last of `ancestors`).
Replacing `node` itself, if `visit.SKIP` is not returned, still causes its
[descendant][]s to be visited.
If adding or removing previous [sibling][]s (or next siblings, in case of
`reverse`) of `node`, `visitor` should return a new [`index`][index] (`number`)
to specify the sibling to traverse after `node` is traversed.
Adding or removing next siblings of `node` (or previous siblings, in case of
reverse) is handled as expected without needing to return a new `index`.
Removing the `children` property of parent still results in them being
traversed.
###### Parameters
* `node` ([`Node`][node]) — Found node
* `ancestors` (`Array.<Node>`) — [Ancestor][]s of `node`
##### Returns
The return value can have the following forms:
* [`index`][index] (`number`) — Treated as a tuple of `[CONTINUE, index]`
* `action` (`*`) — Treated as a tuple of `[action]`
* `tuple` (`Array.<*>`) — List with one or two values, the first an `action`,
the second and `index`.
Note that passing a tuple only makes sense if the `action` is `SKIP`.
If the `action` is `EXIT`, that action can be returned.
If the `action` is `CONTINUE`, `index` can be returned.
###### `action`
An action can have the following values:
* `visit.EXIT` (`false`) — Stop traversing immediately
* `visit.CONTINUE` (`true`) — Continue traversing as normal (same behaviour
as not returning anything)
* `visit.SKIP` (`'skip'`) — Do not traverse this node’s children; continue
with the specified index
###### `index`
[`index`][index] (`number`) — Move to the sibling at `index` next (after `node`
itself is completely traversed).
Useful if mutating the tree, such as removing the node the visitor is currently
on, or any of its previous siblings (or next siblings, in case of `reverse`)
Results less than `0` or greater than or equal to `children.length` stop
traversing the parent
## Related
* [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
— Like `visit-parents`, but with one parent
* [`unist-util-filter`](https://github.com/eush77/unist-util-filter)
— Create a new tree with all nodes that pass a test
* [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
— Create a new tree with all nodes mapped by a given function
* [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
— Create a new tree by mapping (to an array) with the provided function and
then flattening
* [`unist-util-remove`](https://github.com/eush77/unist-util-remove)
— Remove nodes from a tree that pass a test
* [`unist-util-select`](https://github.com/eush77/unist-util-select)
— Select nodes with CSS-like selectors
## Contribute
See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`support.md`][support] for ways to get help.
This project has a [Code of Conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.
## License
[MIT][license] © [Titus Wormer][author]
<!-- Definition -->
[build-badge]: https://img.shields.io/travis/syntax-tree/unist-util-visit-parents.svg
[build]: https://travis-ci.org/syntax-tree/unist-util-visit-parents
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit-parents.svg
[coverage]: https://codecov.io/github/syntax-tree/unist-util-visit-parents
[downloads-badge]: https://img.shields.io/npm/dm/unist-util-visit-parents.svg
[downloads]: https://www.npmjs.com/package/unist-util-visit-parents
[size-badge]: https://img.shields.io/bundlephobia/minzip/unist-util-visit-parents.svg
[size]: https://bundlephobia.com/result?p=unist-util-visit-parents
[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
[backers-badge]: https://opencollective.com/unified/backers/badge.svg
[collective]: https://opencollective.com/unified
[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
[chat]: https://spectrum.chat/unified/syntax-tree
[npm]: https://docs.npmjs.com/cli/install
[license]: license
[author]: https://wooorm.com
[unist]: https://github.com/syntax-tree/unist
[node]: https://github.com/syntax-tree/unist#node
[visitor]: #next--visitornode-ancestors
[contributing]: https://github.com/syntax-tree/.github/blob/master/contributing.md
[support]: https://github.com/syntax-tree/.github/blob/master/support.md
[coc]: https://github.com/syntax-tree/.github/blob/master/code-of-conduct.md
[is]: https://github.com/syntax-tree/unist-util-is
[preorder]: https://www.geeksforgeeks.org/tree-traversals-inorder-preorder-and-postorder/
[descendant]: https://github.com/syntax-tree/unist#descendant
[head]: https://github.com/syntax-tree/unist#head
[tail]: https://github.com/syntax-tree/unist#tail
[parent]: https://github.com/syntax-tree/unist#parent-1
[sibling]: https://github.com/syntax-tree/unist#sibling
[index]: https://github.com/syntax-tree/unist#index
[ancestor]: https://github.com/syntax-tree/unist#ancestor
[tree]: https://github.com/syntax-tree/unist#tree
[type]: https://github.com/syntax-tree/unist#type
|
