1 | # unist-util-visit [![Build Status][build-badge]][build-page] [![Coverage Status][coverage-badge]][coverage-page]
|
2 |
|
3 | [Unist][] node visitor. Useful when working with [**remark**][remark],
|
4 | [**retext**][retext], or [**rehype**][rehype].
|
5 |
|
6 | ## Installation
|
7 |
|
8 | [npm][]:
|
9 |
|
10 | ```bash
|
11 | npm install unist-util-visit
|
12 | ```
|
13 |
|
14 | ## Usage
|
15 |
|
16 | ```javascript
|
17 | var remark = require('remark');
|
18 | var visit = require('.');
|
19 |
|
20 | var tree = remark.parse('Some _emphasis_, **importance**, and `code`.');
|
21 |
|
22 | visit(tree, 'text', visitor);
|
23 |
|
24 | function visitor(node) {
|
25 | console.log(node);
|
26 | }
|
27 | ```
|
28 |
|
29 | Yields:
|
30 |
|
31 | ```js
|
32 | { type: 'text', value: 'Some ' }
|
33 | { type: 'text', value: 'emphasis' }
|
34 | { type: 'text', value: ', ' }
|
35 | { type: 'text', value: 'importance' }
|
36 | { type: 'text', value: ', and ' }
|
37 | { type: 'text', value: '.' }
|
38 | ```
|
39 |
|
40 | ## API
|
41 |
|
42 | ### `visit(node[, type], visitor[, reverse])`
|
43 |
|
44 | Visit nodes. Optionally by node type. Optionally in reverse.
|
45 |
|
46 | ###### Parameters
|
47 |
|
48 | * `node` ([`Node`][node])
|
49 | — Node to search
|
50 | * `type` (`string`, optional)
|
51 | — Node type
|
52 | * `visitor` ([Function][visitor])
|
53 | — Visitor invoked when a node is found
|
54 | * `reverse` (`boolean`, default: `false`)
|
55 | — When falsey, checking starts at the first child and continues
|
56 | through to later children. When truthy, this is reversed.
|
57 | This **does not** mean checking starts at the deepest node and
|
58 | continues on to the highest node
|
59 |
|
60 | #### `stop? = visitor(node, index, parent)`
|
61 |
|
62 | Invoked when a node (when `type` is given, matching `type`) is found.
|
63 |
|
64 | ###### Parameters
|
65 |
|
66 | * `node` (`Node`) — Found node
|
67 | * `index` (`number?`) — Position of `node` in `parent`
|
68 | * `parent` (`Node?`) — Parent of `node`
|
69 |
|
70 | ###### Returns
|
71 |
|
72 | `boolean?` - When `false`, visiting is immediately stopped.
|
73 |
|
74 | ## Related
|
75 |
|
76 | * [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)
|
77 | — Like `visit`, but with a stack of parents
|
78 | * [`unist-util-filter`](https://github.com/eush77/unist-util-filter)
|
79 | — Create a new tree with all nodes that pass a test
|
80 | * [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
|
81 | — Create a new tree with all nodes mapped by a given function
|
82 | * [`unist-util-remove`](https://github.com/eush77/unist-util-remove)
|
83 | — Remove nodes from a tree that pass a test
|
84 | * [`unist-util-select`](https://github.com/eush77/unist-util-select)
|
85 | — Select nodes with CSS-like selectors
|
86 |
|
87 | ## License
|
88 |
|
89 | [MIT][license] © [Titus Wormer][author]
|
90 |
|
91 |
|
92 |
|
93 | [build-badge]: https://img.shields.io/travis/syntax-tree/unist-util-visit.svg
|
94 |
|
95 | [build-page]: https://travis-ci.org/syntax-tree/unist-util-visit
|
96 |
|
97 | [coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-visit.svg
|
98 |
|
99 | [coverage-page]: https://codecov.io/github/syntax-tree/unist-util-visit?branch=master
|
100 |
|
101 | [npm]: https://docs.npmjs.com/cli/install
|
102 |
|
103 | [license]: LICENSE
|
104 |
|
105 | [author]: http://wooorm.com
|
106 |
|
107 | [unist]: https://github.com/syntax-tree/unist
|
108 |
|
109 | [retext]: https://github.com/wooorm/retext
|
110 |
|
111 | [remark]: https://github.com/wooorm/remark
|
112 |
|
113 | [rehype]: https://github.com/wooorm/rehype
|
114 |
|
115 | [node]: https://github.com/syntax-tree/unist#node
|
116 |
|
117 | [visitor]: #stop--visitornode-index-parent
|