mdast-util-find-and-replace

mdast utility to find and replace text in a tree

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
mdast-util-find-and-replace
3.0.17 months ago4 years agoMinified + gzip package size for mdast-util-find-and-replace in KB

Popular Searches

Readme

mdast-util-find-and-replace
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
mdast utility to find and replace things.

Contents

*   [`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.

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-replacehast-util-find-and-replace does the same but on hast.

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install mdast-util-find-and-replace

In Deno with esm.shesmsh:
import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@3'

In browsers with esm.shesmsh:
<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 findAndReplaceapi-find-and-replace. 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 Texttext nodes. Partial matches are not supported.
Parameters
— tree to change
[`FindAndReplaceTuple`][api-find-and-replace-tuple])
— one or more find-and-replace pairs
— 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 FindAndReplaceTupleapi-find-and-replace-tuple.

FindAndReplaceTuple

Find and replace in tuple form (TypeScript type).
Type
type FindAndReplaceTuple = [Find, Replace?]

See Findapi-find and Replaceapi-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
— 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 ReplaceFunctionapi-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 Node or Array<Node>, replace with those nodes

Types

This package is fully typed with TypeScript. It exports the additional types Findapi-find, FindAndReplaceListapi-find-and-replace-list, FindAndReplaceTupleapi-find-and-replace-tuple, Optionsapi-options, RegExpMatchObjectapi-regexp-match-object, Replaceapi-replace, and ReplaceFunctionapi-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, 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)xss attacks.

Related

— find and replace in hast
— `querySelector`, `querySelectorAll`, and `matches`
— select unist nodes with CSS-like selectors

Contribute

See contributing.mdcontributing in syntax-tree/.githubhealth for ways to get started. See support.mdsupport 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.

License

MITlicense © Titus Wormerauthor