unified

Project: syntax-tree/nlcst-search

Package: nlcst-search@3.1.0

  1. Dependents: 0
  2. nlcst utility to search for patterns in a tree
  1. util 147
  2. utility 143
  3. unist 133
  4. nlcst 15
  5. nlcst-util 9
  6. search 6

nlcst-search

Build Coverage Downloads Size Sponsors Backers Chat

nlcst utility to search for patterns in a tree.

Contents

What is this?

This utility can search for patterns (words and phrases) in trees.

When should I use this?

This package is a tiny utility that helps when you’re searching for words and phrases.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, 18.0+), install with npm:

npm install nlcst-search

In Deno with esm.sh:

import {search} from "https://esm.sh/nlcst-search@3"

In browsers with esm.sh:

<script type="module">
  import {search} from "https://esm.sh/nlcst-search@3?bundle"
</script>

Use

import {search} from 'nlcst-search'
import {toString} from 'nlcst-to-string'

const tree = {
  type: 'SentenceNode',
  children: [
    {
      type: 'WordNode',
      children: [
        {type: 'TextNode', value: 'Don'},
        {type: 'PunctuationNode', value: '’'},
        {type: 'TextNode', value: 't'}
      ]
    },
    {type: 'WhiteSpaceNode', value: ' '},
    {
      type: 'WordNode',
      children: [{type: 'TextNode', value: 'do'}]
    },
    {type: 'WhiteSpaceNode', value: ' '},
    {
      type: 'WordNode',
      children: [
        {type: 'TextNode', value: 'Block'},
        {type: 'PunctuationNode', value: '-'},
        {type: 'TextNode', value: 'level'}
      ]
    }
  ]
}

search(tree, ['dont'], function(nodes) {
  console.log(toString(nodes))
})
// `Don’t`

search(tree, ['do blocklevel'], function(nodes) {
  console.log(toString(nodes))
})
// `do Block-level`

API

This package exports the identifier search. There is no default export.

search(tree, patterns, handler[, allowApostrophes|options])

Search for patterns a tree.

Parameters
node

Tree to search in (Node).

patterns

Patterns to search for (Array<string> or Record<string, unknown>). If an Object, uses its keys as patterns. Each pattern is a space-separated list of words, where each word is normalized to remove casing, apostrophes, and dashes. Spaces in a pattern mean zero or more white space nodes in the tree. Instead of a word, it’s also possible to use a wildcard symbol (*, an asterisk), that matches any word in a pattern (alpha * charlie).

handler

Handler called when a match is found (Handler).

allowApostrophes

Treated as options.allowApostrophes.

options.allowApostrophes

Passed to nlcst-normalize (boolean, default: false).

options.allowDashes

Passed to nlcst-normalize (boolean, default: false).

options.allowLiterals

Include literal phrases (boolean, default: false).

function handler(nodes, index, parent, pattern)

Handler called when a match is found.

Parameters
nodes

List of siblings that match pattern (Array<Node>).

index

Index where the match starts in parent (number).

parent

Parent node of nodes (Node).

pattern

The matched pattern (string).

Types

This package is fully typed with TypeScript. It exports the additional types Options, PhrasesList, PhrasesMap, and Handler.

Compatibility

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

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.

License

MIT © Titus Wormer