.config/coc/extensions/node_modules/coc-prettier/node_modules/unist-util-visit-parents/readme.md

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