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
|
# unist-util-visit [![Build Status][build-badge]][build-page] [![Coverage Status][coverage-badge]][coverage-page]
[unist][] node visitor. Useful when working with [**remark**][remark],
[**retext**][retext], or [**rehype**][rehype].
## Installation
[npm][]:
```bash
npm install unist-util-visit
```
## Usage
```javascript
var remark = require('remark');
var visit = require('unist-util-visit');
var tree = remark().parse('Some _emphasis_, **importance**, and `code`.');
visit(tree, 'text', visitor);
function visitor(node) {
console.log(node);
}
```
Yields:
```js
{type: 'text', value: 'Some '}
{type: 'text', value: 'emphasis'}
{type: 'text', value: ', '}
{type: 'text', value: 'importance'}
{type: 'text', value: ', and '}
{type: 'text', value: '.'}
```
## API
### `visit(tree[, test], visitor[, reverse])`
Visit nodes ([**inclusive descendants**][descendant] of `tree`). Optionally
filtering nodes. Optionally in reverse.
###### Parameters
* `tree` ([`Node`][node])
— Tree to traverse
* `test` ([`Test`][is], optional)
— [`is`][is]-compatible test (such as a node type)
* `visitor` ([Function][visitor])
— Function invoked when a node is found that passes `test`
* `reverse` (`boolean`, default: `false`)
— When falsey, checking starts at the first child and continues
through to later children. When truthy, this is reversed.
This **does not** mean checking starts at the deepest node and
continues on to the highest node
#### `next? = visitor(node, index, parent)`
Invoked when a node (matching `test` if given) is found.
You can transform visited nodes. You can transform `parent`, but if adding or
removing [**children**][child] before `index`, you should return a new `index`
(`number`) from `visitor` to specify the next sibling to visit. Replacing
`node` itself still causes its descendants to be visited. Adding or removing
nodes after `index` is handled as expected without needing to return a new
`index`. Removing the `children` property on `parent` still results in them
being traversed.
###### Parameters
* `node` (`Node`) — Found node
* `index` (`number?`) — Position of `node` in `parent`
* `parent` (`Node?`) — Parent of `node`
###### Returns
* `visit.EXIT` (`false`)
— Stop traversing immediately
* `visit.CONTINUE` (`true`)
— Continue traversing as normal (same behaviour as not returning anything)
* `visit.SKIP` (`'skip'`)
— Do not enter this node (traversing into its children), but do continue
with the next sibling
* `index` (`number`)
— Move to the sibling at position `index` next (after `node` itself is
traversed). Useful if you’re mutating the tree (such as removing the node
you’re currently on, or any of its preceding siblings). Results less than
`0` or greater than or equal to `children.length` stop iteration of the
parent
## Related
* [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)
— Like `visit`, but with a stack of parents
* [`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-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 [`contribute.md` in `syntax-tree/unist`][contribute] for ways to get
started.
This organisation 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.svg
[build-page]: https://travis-ci.org/syntax-tree/unist-util-visit
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit.svg
[coverage-page]: https://codecov.io/github/syntax-tree/unist-util-visit?branch=master
[npm]: https://docs.npmjs.com/cli/install
[license]: LICENSE
[author]: http://wooorm.com
[unist]: https://github.com/syntax-tree/unist
[retext]: https://github.com/wooorm/retext
[remark]: https://github.com/wooorm/remark
[rehype]: https://github.com/wooorm/rehype
[node]: https://github.com/syntax-tree/unist#node
[descendant]: https://github.com/syntax-tree/unist#descendant
[child]: https://github.com/syntax-tree/unist#child
[is]: https://github.com/syntax-tree/unist-util-is#istest-node-index-parent-context
[visitor]: #next--visitornode-index-parent
[contribute]: https://github.com/syntax-tree/unist/blob/master/contributing.md
[coc]: https://github.com/syntax-tree/unist/blob/master/code-of-conduct.md
|
