README

hast-util-find-and-replace

hast utility to find and replace text in a tree.

Install

npm install hast-util-find-and-replace

Use

var h = require('hastscript')
var inspect = require('unist-util-inspect')
var findAndReplace = require('hast-util-find-and-replace')

var tree = h('p', [
  'Some ',
  h('em', 'emphasis'),
  ', ',
  h('strong', 'importance'),
  ', and ',
  h('code', 'code'),
  '.'
])

findAndReplace(tree, 'and', 'or')

findAndReplace(tree, {emphasis: 'em', importance: 'strong'})

findAndReplace(tree, {
  code: function($0) {
    return h('a', {href: '//example.com#' + $0}, $0)
  }
})

console.log(inspect(tree))

Yields:

element[9] [tagName="p"]
├─ text: "Some "
├─ element[1] [tagName="em"]
│  └─ text: "em"
├─ text: ", "
├─ element[1] [tagName="strong"]
│  └─ text: "strong"
├─ text: ", "
├─ text: "or"
├─ text: " "
├─ element[1] [tagName="code"]
│  └─ element[1] [tagName="a"][properties={"href":"//example.com#code"}]
│     └─ text: "code"
└─ text: "."

API

`findAndReplace(tree, find[, replace][, options])`

Find and replace text in a hast tree. The algorithm searches the tree in preorder for complete values in Text nodes. Partial matches are not supported.

Signatures

findAndReplace(tree, find, replace[, options])
findAndReplace(tree, search[, options])

Parameters

tree (Node) — hast tree
find (string or RegExp) — Value to find and remove. When string, escaped and made into a global RegExp
replace (string or Function) — Value to insert. When string, turned into a Text node. When Function, invoked with the results of calling RegExp.exec as arguments, in which case it can return a Node or a string, which is in the latter case wrapped in a Text node
search (Object or Array) — Perform multiple find-and-replace’s. When Array, each entry is a tuple (Array) of a find (at 0) and replace (at 1). When Object, each key is a find (in string form) and each value is a replace
options.ignore (Array, default: ['title', 'script', 'style', 'svg', 'math']) — Tag-names of elements not to search. This list can be accessed at findAndReplace.ignore

Returns

The given, modified, tree.

Security

Improper use of the replace can open you up to a cross-site scripting (XSS) attack as the value of replace is injected into the syntax tree. The following example shows how a script is injected that runs when loaded in a browser.

findAndReplace(h('p', 'This and that.'), 'and', function() {
  return h('script', 'alert(1)')
})

Yields:

<p>This <script>alert(1)</script> that.</p>

Do not use user input in replace or use hast-util-santize.

hast-util-select — querySelector, querySelectorAll, and matches
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, organization, or community you agree to abide by its terms.

@cheapsteak/hast-util-find-and-replace

Usage no npm install needed!