Never Push to Master

    mdast-util-find-and-replace
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.2 • Public • Published

    mdast-util-find-and-replace

    Build Coverage Downloads Size Sponsors Backers Chat

    mdast utility to find and replace things.

    Contents

    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 14.14+ and or 16.0+), 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@2'

    In browsers with esm.sh:

    <script type="module">
      import {findAndReplace} from 'https://esm.sh/mdast-util-find-and-replace@2?bundle'
    </script>

    Use

    import {u} from 'unist-builder'
    import {inspect} from 'unist-util-inspect'
    import {findAndReplace} from 'mdast-util-find-and-replace'
    
    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, find, replace[, 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.

    Signatures
    • findAndReplace(tree, find, replace[, options])
    • findAndReplace(tree, search[, options])
    Parameters
    Returns

    Given, modified, tree (Node).

    Find

    Pattern to find (TypeScript type).

    Strings are escaped and then turned into global expressions.

    Type
    type Find = string | RegExp

    FindAndReplaceList

    Several find and replaces, in array form (TypeScript type).

    Type
    type FindAndReplaceList = Array<FindAndReplaceTuple>

    See FindAndReplaceTuple.

    FindAndReplaceSchema

    Several find and replaces, in object form (TypeScript type).

    Type
    type FindAndReplaceSchema = Record<string, Replace>

    See Replace.

    FindAndReplaceTuple

    Find and replace in tuple form (TypeScript type).

    Type
    type FindAndReplaceTuple = [Find, Replace]

    See Find and 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 found
    • input (string) — a copy of the search string in the text node
    • stack (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 = string | ReplaceFunction

    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 groups
    • match (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 or Array<Node>, replace with those nodes

    Types

    This package is fully typed with TypeScript. It exports the additional types Find, FindAndReplaceList, FindAndReplaceSchema, FindAndReplaceTuple, Options, RegExpMatchObject, Replace, and ReplaceFunction.

    Compatibility

    Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

    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

    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.

    License

    MIT © Titus Wormer

    Install

    npm i mdast-util-find-and-replace

    DownloadsWeekly Downloads

    1,295,899

    Version

    2.2.2

    License

    MIT

    Unpacked Size

    25.6 kB

    Total Files

    7

    Last publish

    Collaborators

    • wooorm
    • kmck