@tabnas/hoover

A tabnas parser-engine syntax plugin that adds configurable block-delimited string parsing — hoovering up unquoted strings with internal spaces. Define custom string formats with start/end delimiters, escape sequences, and context-sensitive matching. Its only dependency is the engine; it extends whatever grammar you register.

npm install @tabnas/parser @tabnas/hoover

Requires @tabnas/parser >=2 as a peer dependency. The engine ships no grammar, and hoover is grammar-agnostic: it adds an alternate to the val rule, so register a grammar that defines val first, then the hoover plugin. If val is absent, use(Hoover, …) throws a clear error.

Documentation

• Tutorial — zero to a working triple-quote parser.
• How-to guide — escapes, trimming, delimiter consumption, rule-context matching.
• Reference — every export, option, and type.
• Concepts — how the matcher works and why.

The Go port lives in ../go with its own four-quadrant docs.

Quick example

hoover extends a grammar you supply. This self-contained example registers a tiny inline host grammar (a single value plus a parenthesised group, the same shape as test/minigrammar.ts) before the hoover plugin, then parses triple-quoted strings — which preserve internal whitespace.

const { Tabnas } = require('@tabnas/parser')
const { Hoover } = require('@tabnas/hoover')

// Tiny host grammar defining the `val` rule hoover plugs into.
function grammar(tn) {
  tn.options({
    fixed: { token: { '#OP': '(', '#CP': ')' } },
    rule: { start: 'val' },
  })
  tn.token('#OP')
  tn.token('#CP')

  tn.rule('val', (rs) => {
    rs.bo((r) => { r.node = undefined })
    rs.bc((r, ctx) => {
      r.node =
        undefined === r.node
          ? undefined === r.child.node
            ? 0 === r.os ? undefined : r.o0.resolveVal(r, ctx)
            : r.child.node
          : r.node
    })
    rs.open([{ s: '#OP', p: 'group', b: 1 }, { s: '#VAL' }])
    rs.close([{ s: '#ZZ' }, { s: '#CP', b: 1 }])
  })

  tn.rule('group', (rs) => {
    rs.bc((r) => { r.node = r.child.node })
    rs.open([{ s: '#OP', p: 'val' }])
    rs.close([{ s: '#CP' }])
  })
}

const j = new Tabnas()
  .use(grammar)
  .use(Hoover, {
    block: [
      { name: 'triplequote', start: { fixed: "'''" }, end: { fixed: "'''" } },
    ],
  })

j.parse("'''hello world'''")  // => "hello world"
j.parse("('''x''')")          // => "x"

See the tutorial for a step-by-step walkthrough.

License

MIT. Copyright (c) Richard Rodger and other contributors.