hast-util-find-and-replace

hast utility to find and replace text in a tree

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
hast-util-find-and-replace
505.0.16 months ago7 years agoMinified + gzip package size for hast-util-find-and-replace in KB

Readme

hast-util-find-and-replace
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
hast 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.shesmsh:
import {findAndReplace} from 'https://esm.sh/hast-util-find-and-replace@5'

In browsers with esm.shesmsh:
<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 identifiers defaultIgnoreapi-default-ignore and findAndReplaceapi-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 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 | null | undefined

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 Array<Node> or 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, hast-util-find-and-replace@^5, compatible with Node.js 16.

Security

Use of hast-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-santizehast-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

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