Skip to content

Commit

Permalink
Add improved docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Jun 5, 2022
1 parent abcf6be commit 2d8bea2
Showing 1 changed file with 98 additions and 37 deletions.
135 changes: 98 additions & 37 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,30 +8,66 @@
[![Backers][backers-badge]][collective]
[![Chat][chat-badge]][chat]

[**unist**][unist] utility to visit direct children of a parent.
[unist][] utility to visit direct children of a parent.

## Install
## Contents

* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`visitChildren(visitor)`](#visitchildrenvisitor)
* [Types](#types)
* [Compatibility](#compatibility)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)

## What is this?

This is a tiny utility that you can use to create a reusable function that
only visits direct children.

This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
## When should I use this?

Probably never!
Use [`unist-util-visit`][unist-util-visit].

## Install

[npm][]:
This package is [ESM only][esm].
In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with [npm][]:

```sh
npm install unist-util-visit-children
```

In Deno with [`esm.sh`][esmsh]:

```js
import {visitChildren} from "https://esm.sh/unist-util-visit-children@2"
```

In browsers with [`esm.sh`][esmsh]:

```html
<script type="module">
import {visitChildren} from "https://esm.sh/unist-util-visit-children@2?bundle"
</script>
```

## Use

```js
import u from 'unist-builder'
import {visitChildren} from 'unist-util-visit-children'

var visit = visitChildren(function(node) {
const visit = visitChildren(function (node) {
console.log(node)
})

var tree = u('tree', [
const tree = u('tree', [
u('leaf', 'leaf 1'),
u('node', [u('leaf', 'leaf 2'), u('leaf', 'leaf 3')]),
u('leaf', 'leaf 4'),
Expand All @@ -58,53 +94,70 @@ Yields:

## API

This package exports the following identifiers: `visitChildren`.
This package exports the identifier `visitChildren`.
There is no default export.

### `visit = visitChildren(visitor)`
### `visitChildren(visitor)`

Wrap [`visitor`][visitor] to be called for each child in the nodes later given
to [`visit`][visit].

###### Returns

[`Visit`][visit].

#### `visitor(child, index, parent)`

Callback called for each `child` in `parent` later given to [`visit`][visit].

#### `visit(parent)`

Wrap [`visitor`][visitor] to be called for each [child][] in the nodes later
given to [`visit`][visit].
Call the bound [`visitor`][visitor] for each child in `parent`
([`Parent`][parent]).

#### `function visitor(child, index, parent)`
## Types

Called if [`visit`][visit] is called on a [parent][] node for each [child][].
This package is fully typed with [TypeScript][].
It exports the additional types `Visitor` and `Visit`.

#### `function visit(parent)`
## Compatibility

Called [`visitor`][visitor] for each [child][] of the [parent][].
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

## Related

* [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
— Recursively walk over nodes
— walk the tree
* [`unist-util-visit-parents`](https://github.com/syntax-tree/unist-util-visit-parents)
— Like `visit`, but with a stack of parents
— walk the tree with a stack of parents
* [`unist-util-filter`](https://github.com/syntax-tree/unist-util-filter)
— Create a new tree with all nodes that pass a test
— 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
— 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 given function
— create a new tree by mapping (to an array) with the given function
* [`unist-util-find-all-after`](https://github.com/syntax-tree/unist-util-find-all-after)
— Find nodes after another node
— find nodes after another node
* [`unist-util-find-all-before`](https://github.com/syntax-tree/unist-util-find-all-before)
— Find nodes before another node
— find nodes before another node
* [`unist-util-find-after`](https://github.com/syntax-tree/unist-util-find-after)
— Find a node after another node
— find a node after another node
* [`unist-util-find-before`](https://github.com/syntax-tree/unist-util-find-before)
— Find a node before another node
— find a node before another node
* [`unist-util-find-all-between`](https://github.com/mrzmmr/unist-util-find-all-between)
— Find all nodes between two nodes
— find all nodes between two nodes
* [`unist-util-remove`](https://github.com/syntax-tree/unist-util-remove)
— Remove nodes from a tree that pass a test
— remove nodes from a tree that pass a test
* [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
— Select nodes with CSS-like selectors
— select nodes with CSS-like selectors

## Contribute

See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
started.
See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
ways to get started.
See [`support.md`][support] for ways to get help.

This project has a [Code of Conduct][coc].
Expand Down Expand Up @@ -145,22 +198,30 @@ abide by its terms.

[npm]: https://docs.npmjs.com/cli/install

[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[esmsh]: https://esm.sh

[typescript]: https://www.typescriptlang.org

[license]: license

[author]: https://wooorm.com

[unist]: https://github.com/syntax-tree/unist
[health]: https://github.com/syntax-tree/.github

[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md

[parent]: https://github.com/syntax-tree/unist#parent-1
[support]: https://github.com/syntax-tree/.github/blob/main/support.md

[child]: https://github.com/syntax-tree/unist#child
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md

[visit]: #function-visitparent
[unist]: https://github.com/syntax-tree/unist

[visitor]: #function-visitorchild-index-parent
[parent]: https://github.com/syntax-tree/unist#parent

[contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
[unist-util-visit]: https://github.com/syntax-tree/unist-util-visit

[support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
[visit]: #visitparent

[coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
[visitor]: #visitorchild-index-parent

0 comments on commit 2d8bea2

Please sign in to comment.