Package Exports

hast-util-find-and-replace

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hast-util-find-and-replace) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

hast-util-find-and-replace

hast utility to find and replace text in a tree.

Install

npm:

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, called with the results of calling RegExp.exec as arguments, in which case it can return a Node or a string (which is wrapped in a Text node), or false to not replace
search (Object or Array) — Perform multiple find-and-replaces. 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 (Test, default: ['title', 'script', 'style', 'svg', 'math']) — Any hast-util-is-element compatible test. The default 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.