hast-util-find-and-replace
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechathast utility to find and replace things.
Contents
* [`defaultIgnore`](#defaultignore)
* [`findAndReplace(tree, list[, options])`](#findandreplacetree-list-options)
* [`Find`](#find)
* [`FindAndReplaceList`](#findandreplacelist)
* [`FindAndReplaceTuple`](#findandreplacetuple)
* [`Options`](#options)
* [`RegExpMatchObject`](#regexpmatchobject)
* [`Replace`](#replace)
* [`ReplaceFunction`](#replacefunction)
What is this?
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 <style>
and <script>
by default).When should I use this?
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.Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:npm install hast-util-find-and-replace
In Deno with
esm.sh
esmsh:import {findAndReplace} from 'https://esm.sh/hast-util-find-and-replace@5'
In browsers with
esm.sh
esmsh:<script type="module">
import {findAndReplace} from 'https://esm.sh/hast-util-find-and-replace@5?bundle'
</script>
Use
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:
element<p>[9]
│ properties: {}
├─0 text "Some "
├─1 element<em>[1]
│ │ properties: {}
│ └─0 text "em"
├─2 text ", "
├─3 element<strong>[1]
│ │ properties: {}
│ └─0 text "strong"
├─4 text ", "
├─5 text "or"
├─6 text " "
├─7 element<code>[1]
│ │ properties: {}
│ └─0 element<a>[1]
│ │ properties: {"href":"//example.com#code"}
│ └─0 text "code"
└─8 text "."
API
This package exports the identifiersdefaultIgnore
api-default-ignore and
findAndReplace
api-find-and-replace.
There is no default export.defaultIgnore
Default tag names to ignore (Array<string>
).The defaults are
math
, script
, style
, svg
, and title
.findAndReplace(tree, list[, options])
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 to change
[`FindAndReplaceTuple`][api-find-and-replace-tuple])
— one or more find-and-replace pairs
options
(Options
api-options)
— configuration
Returns
Nothing (undefined
).Find
Pattern to find (TypeScript type).Strings are escaped and then turned into global expressions.
Type
type Find = RegExp | string
FindAndReplaceList
Several find and replaces, in array form (TypeScript type).Type
type FindAndReplaceList = Array<FindAndReplaceTuple>
See
FindAndReplaceTuple
api-find-and-replace-tuple.FindAndReplaceTuple
Find and replace in tuple form (TypeScript type).Type
type FindAndReplaceTuple = [Find, Replace?]
See
Find
api-find and Replace
api-replace.Options
Configuration (TypeScript type).Fields
— test for which elements to ignore
RegExpMatchObject
Info on the match (TypeScript type).Fields
index
(number
)
— the index of the search at which the result was found
input
(string
)
— a copy of the search string in the text node
stack
(Array<Node>
node)
— all ancestors of the text node, where the last node is the text itself
Replace
Thing to replace with (TypeScript type).Type
type Replace = ReplaceFunction | string | null | undefined
See
ReplaceFunction
api-replace-function.ReplaceFunction
Callback called when a search matches (TypeScript type).Parameters
The parameters are the result of corresponding search expression:value
(string
)
— whole match
...capture
(Array<string>
)
— matches from regex capture groups
— info on the match
Returns
Thing to replace with:- when
null
,undefined
,''
, remove the match - …or when
false
, do not replace at all - …or when
string
, replace with a text node of that value - …or when
Array<Node>
orNode
, replace with those nodes
Types
This package is fully typed with TypeScript. It exports the additional typesFind
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, and
ReplaceFunction
api-replace-function.Compatibility
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.Security
Use ofhast-util-find-and-replace
can open you up to a
cross-site scripting (XSS)xss attack if a value used to replace
is unsafe.
Use hast-util-santize
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.
const tree = h('p', 'This and that.')
findAndReplace(tree, 'and', function () {
return h('script', 'alert(1)')
})
Yields:
<p>This <script>alert(1)</script> that.</p>
Related
— `querySelector`, `querySelectorAll`, and `matches`
— find and replace in mdast
— select unist nodes with CSS-like selectors
Contribute
Seecontributing.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 conductcoc. By interacting with this repository, organisation, or community you agree to abide by its terms.