Awesome
mdast-util-find-and-replace
mdast utility to find and replace things.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Types
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This package is a utility that lets you find patterns (string
, RegExp
) in
text and replace them with nodes.
When should I use this?
This utility is typically useful when you have regexes and want to modify mdast.
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.
A similar package, hast-util-find-and-replace
does the same but on hast.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-find-and-replace
In Deno with esm.sh
:
import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@3'
In browsers with esm.sh
:
<script type="module">
import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@3?bundle'
</script>
Use
import {findAndReplace} from 'mdast-util-find-and-replace'
import {u} from 'unist-builder'
import {inspect} from 'unist-util-inspect'
const tree = u('paragraph', [
u('text', 'Some '),
u('emphasis', [u('text', 'emphasis')]),
u('text', ' and '),
u('strong', [u('text', 'importance')]),
u('text', '.')
])
findAndReplace(tree, [
[/and/gi, 'or'],
[/emphasis/gi, 'em'],
[/importance/gi, 'strong'],
[
/Some/g,
function ($0) {
return u('link', {url: '//example.com#' + $0}, [u('text', $0)])
}
]
])
console.log(inspect(tree))
Yields:
paragraph[8]
├─0 link[1]
│ │ url: "//example.com#Some"
│ └─0 text "Some"
├─1 text " "
├─2 emphasis[1]
│ └─0 text "em"
├─3 text " "
├─4 text "or"
├─5 text " "
├─6 strong[1]
│ └─0 text "strong"
└─7 text "."
API
This package exports the identifier findAndReplace
.
There is no default export.
findAndReplace(tree, list[, options])
Find patterns in a tree and replace them.
The algorithm searches the tree in preorder for complete values in
Text
nodes.
Partial matches are not supported.
Parameters
tree
(Node
) — tree to changelist
(FindAndReplaceList
orFindAndReplaceTuple
) — one or more find-and-replace pairsoptions
(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
.
FindAndReplaceTuple
Find and replace in tuple form (TypeScript type).
Type
type FindAndReplaceTuple = [Find, Replace?]
Options
Configuration (TypeScript type).
Fields
ignore
(Test
, optional) — 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 foundinput
(string
) — a copy of the search string in the text nodestack
(Array<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
See ReplaceFunction
.
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 groupsmatch
(RegExpMatchObject
) — 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
Node
orArray<Node>
, replace with those nodes
Types
This package is fully typed with TypeScript.
It exports the additional types Find
,
FindAndReplaceList
,
FindAndReplaceTuple
,
Options
,
RegExpMatchObject
,
Replace
, and
ReplaceFunction
.
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,
mdast-util-find-and-replace@^3
, compatible with Node.js 16.
Security
Use of mdast-util-find-and-replace
does not involve hast or user content
so there are no openings for cross-site scripting (XSS) attacks.
Related
hast-util-find-and-replace
— find and replace in hasthast-util-select
—querySelector
,querySelectorAll
, andmatches
unist-util-select
— select unist nodes with CSS-like selectors
Contribute
See contributing.md
in syntax-tree/.github
for
ways to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.