hast utility to find and replace text in a tree
npm install hast-util-find-and-replace[![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]
[hast][] utility to find and replace things.
* What is this?
* When should I use this?
* Install
* Use
* API
* defaultIgnore
* [findAndReplace(tree, list[, options])](#findandreplacetree-list-options)
* Find
* FindAndReplaceList
* FindAndReplaceTuple
* Options
* RegExpMatchObject
* Replace
* ReplaceFunction
* Types
* Compatibility
* Security
* Related
* Contribute
* License
This package is a utility that lets you find patterns (string, RegExp) in
text and replace them with nodes (such as elements).
It’s aware of HTML (such as ignoring and by default).
This utility is typically useful when you have regexes and want to modify hast.
One example is when you have some form of “mentions” (such as/@([a-z][_a-z0-9])\b/gi) and want to create links to persons from them.
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
``sh`
npm install hast-util-find-and-replace
In Deno with [esm.sh][esmsh]:
`js`
import {findAndReplace} from 'https://esm.sh/hast-util-find-and-replace@5'
In browsers with [esm.sh][esmsh]:
`html`
`js
import {h} from 'hastscript'
import {findAndReplace} from 'hast-util-find-and-replace'
import {inspect} from 'unist-util-inspect'
const tree = h('p', [
'Some ',
h('em', 'emphasis'),
', ',
h('strong', 'importance'),
', and ',
h('code', 'code'),
'.'
])
findAndReplace(tree, [
[/and/gi, 'or'],
[/emphasis/gi, 'em'],
[/importance/gi, 'strong'],
[
/code/gi,
function ($0) {
return h('a', {href: '//example.com#' + $0}, $0)
}
]
])
console.log(inspect(tree))
`
Yields:
` [9]txt
element
│ properties: {}
├─0 text "Some "
├─1 element[1]
│ │ properties: {}
│ └─0 text "em"
├─2 text ", "
├─3 element[1]
│ │ properties: {}
│ └─0 text "strong"
├─4 text ", "
├─5 text "or"
├─6 text " "
├─7 element[1]`
│ │ properties: {}
│ └─0 element[1]
│ │ properties: {"href":"//example.com#code"}
│ └─0 text "code"
└─8 text "."API
This package exports the identifiers [defaultIgnore][api-default-ignore] andfindAndReplace
[][api-find-and-replace].
There is no default export.
Default tag names to ignore (Array).
The defaults are math, script, style, svg, and title.
Find patterns in a tree and replace them.
The algorithm searches the tree in [preorder][] for complete values in
[Text][text] nodes.
Partial matches are not supported.
###### Parameters
* tree ([Node][node])list
— tree to change
* ([FindAndReplaceList][api-find-and-replace-list] orFindAndReplaceTuple
[][api-find-and-replace-tuple])options
— one or more find-and-replace pairs
* ([Options][api-options])
— configuration
###### Returns
Nothing (undefined).
Pattern to find (TypeScript type).
Strings are escaped and then turned into global expressions.
###### Type
`ts`
type Find = RegExp | string
Several find and replaces, in array form (TypeScript type).
###### Type
`ts`
type FindAndReplaceList = Array
See [FindAndReplaceTuple][api-find-and-replace-tuple].
Find and replace in tuple form (TypeScript type).
###### Type
`ts`
type FindAndReplaceTuple = [Find, Replace?]
See [Find][api-find] and [Replace][api-replace].
Configuration (TypeScript type).
###### Fields
* ignore ([Test][test], optional)
— test for which elements to ignore
Info on the match (TypeScript type).
###### Fields
* index (number)input
— the index of the search at which the result was found
* (string)stack
— a copy of the search string in the text node
* ([Array][node])
— all ancestors of the text node, where the last node is the text itself
Thing to replace with (TypeScript type).
###### Type
`ts`
type Replace = ReplaceFunction | string | null | undefined
See [ReplaceFunction][api-replace-function].
Callback called when a search matches (TypeScript type).
###### Parameters
The parameters are the result of corresponding search expression:
* value (string)...capture
— whole match
* (Array)match
— matches from regex capture groups
* ([RegExpMatchObject][api-regexp-match-object])
— info on the match
###### Returns
Thing to replace with:
* when null, undefined, '', remove the matchfalse
* …or when , do not replace at allstring
* …or when , replace with a text node of that valueArray
* …or when or Node, replace with those nodes
This package is fully typed with [TypeScript][].
It exports the additional types [Find][api-find],FindAndReplaceList
[][api-find-and-replace-list],FindAndReplaceTuple
[][api-find-and-replace-tuple],Options
[][api-options],RegExpMatchObject
[][api-regexp-match-object],Replace
[][api-replace], andReplaceFunction
[][api-replace-function].
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
hast-util-find-and-replace@^5, compatible with Node.js 16.
Use of hast-util-find-and-replace can open you up to areplace
[cross-site scripting (XSS)][xss] attack if a value used to is unsafe.hast-util-santize
Use [][hast-util-sanitize] to make the hast tree safe.
The following example shows how a script is injected that runs when loaded in a
browser.
`js
const tree = h('p', 'This and that.')
findAndReplace(tree, 'and', function () {
return h('script', 'alert(1)')
})
`
Yields:
` This that.html`
* hast-util-select
— querySelector, querySelectorAll, and matchesmdast-util-find-and-replace
* unist-util-select
— find and replace in mdast
*
— select unist nodes with CSS-like selectors
See [contributing.md][contributing] in [syntax-tree/.github][health] forsupport.md`][support] for ways to get help.
ways to get started.
See [
This project has a [code of conduct][coc].
By interacting with this repository, organisation, or community you agree to
abide by its terms.
[MIT][license] © [Titus Wormer][author]
[build-badge]: https://github.com/syntax-tree/hast-util-find-and-replace/workflows/main/badge.svg
[build]: https://github.com/syntax-tree/hast-util-find-and-replace/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/hast-util-find-and-replace.svg
[coverage]: https://codecov.io/github/syntax-tree/hast-util-find-and-replace
[downloads-badge]: https://img.shields.io/npm/dm/hast-util-find-and-replace.svg
[downloads]: https://www.npmjs.com/package/hast-util-find-and-replace
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=hast-util-find-and-replace
[size]: https://bundlejs.com/?q=hast-util-find-and-replace
[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/chat-discussions-success.svg
[chat]: https://github.com/syntax-tree/unist/discussions
[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
[health]: https://github.com/syntax-tree/.github
[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md
[support]: https://github.com/syntax-tree/.github/blob/main/support.md
[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md
[hast]: https://github.com/syntax-tree/hast
[node]: https://github.com/syntax-tree/hast#ndoes
[preorder]: https://github.com/syntax-tree/unist#preorder
[text]: https://github.com/syntax-tree/hast#text
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
[test]: https://github.com/syntax-tree/hast-util-is-element#test
[api-default-ignore]: #defaultignore
[api-find-and-replace]: #findandreplacetree-list-options
[api-options]: #options
[api-find]: #find
[api-replace]: #replace
[api-replace-function]: #replacefunction
[api-find-and-replace-list]: #findandreplacelist
[api-find-and-replace-tuple]: #findandreplacetuple
[api-regexp-match-object]: #regexpmatchobject