@tabnas/abnf 0.4.16 → 0.4.17

package/dist/abnf.d.ts

@@ -4,4 +4,4 @@ import { abnfCompile, toRecognitionSpec, toPureSpec, toJsonic, attachActions, at
 declare const abnf: Plugin;
 export { VERSION, abnf, abnfConvert, parseAbnf, emitGrammarSpec, eliminateLeftRecursion, abnfRules, AbnfParseError, abnfCompile, toRecognitionSpec, toPureSpec, toJsonic, attachActions, attachActionSlots, markListing, AbnfCompileError, AbnfActionError, };
 export type { AbnfConvertOptions, AbnfCompileOptions, ActionsMap };
-declare const VERSION = "0.4.16";
+declare const VERSION = "0.4.17";

package/dist/abnf.js

@@ -36,6 +36,6 @@ exports.abnf = abnf;
 // VERSION is this package's version. It MUST equal package.json "version":
 // the release orchestrator rewrites both, and the version test fails the
 // build if they drift. Mirrors `const VERSION` in go/abnf.go.
-const VERSION = '0.4.16';
+const VERSION = '0.4.17';
 exports.VERSION = VERSION;
 //# sourceMappingURL=abnf.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabnas/abnf",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "main": "dist/abnf.js",
   "type": "commonjs",
   "types": "dist/abnf.d.ts",
@@ -39,7 +39,9 @@
   "license": "MIT",
   "files": [
     "dist",
+    "src",
     "bin",
+    "README.md",
     "LICENSE"
   ],
   "bin": {
@@ -49,8 +51,8 @@
     ".": "./dist/abnf.js"
   },
   "peerDependencies": {
-    "@tabnas/parser": ">=0.12.4",
-    "@tabnas/bnf": ">=0.1.22"
+    "@tabnas/parser": ">=0.12.8",
+    "@tabnas/bnf": ">=0.1.24"
   },
   "devDependencies": {
     "@tabnas/debug": "*",

package/src/abnf.ts

@@ -0,0 +1,92 @@
+/* Copyright (c) 2025-2026 Richard Rodger and other contributors, MIT License */
+
+/*  abnf.ts
+ *  ABNF plugin — adds `tn.abnf(src)` (install) and `tn.abnf.toSpec(src)`
+ *  (build without installing) to an Tabnas instance.
+ *
+ *  The conversion logic itself lives in ./converter.ts; this file
+ *  exposes it both as a Plugin (for `tn.use(abnf)`) and as bare
+ *  exports (for code that wants to convert without an instance).
+ */
+
+import type {
+  Tabnas,
+  GrammarSpec,
+  Plugin,
+} from '@tabnas/parser'
+
+import {
+  abnf as abnfConvert,
+  parseAbnf,
+  emitGrammarSpec,
+  eliminateLeftRecursion,
+  abnfRules,
+  AbnfParseError,
+  AbnfConvertOptions,
+} from './converter'
+
+import {
+  abnfCompile,
+  toRecognitionSpec,
+  toPureSpec,
+  toJsonic,
+  attachActions,
+  attachActionSlots,
+  markListing,
+  AbnfCompileError,
+  AbnfActionError,
+  AbnfCompileOptions,
+  ActionsMap,
+} from './compile'
+
+
+// Plugin entry point. Decorates the instance with a callable `abnf`
+// member that converts and installs a grammar, plus `abnf.toSpec` for
+// callers that just want the spec.
+type AbnfPluginOptions = AbnfConvertOptions & { actions?: ActionsMap }
+
+const abnf: Plugin = function abnf(tn: Tabnas, _options?: any): void {
+  const fn = ((src: string, opts?: AbnfPluginOptions): GrammarSpec => {
+    // User actions wrap the compiler's closures, so convert in closure
+    // mode (never builtins) and request marks when actions are supplied.
+    const spec = abnfConvert(src,
+      opts?.actions ? { ...opts, builtins: false, marks: true } : opts)
+    if (opts?.actions) attachActions(spec, opts.actions)
+    tn.grammar(spec)
+    return spec
+  }) as ((src: string, opts?: AbnfPluginOptions) => GrammarSpec) & {
+    toSpec: (src: string, opts?: AbnfConvertOptions) => GrammarSpec
+  }
+  fn.toSpec = (src: string, opts?: AbnfConvertOptions): GrammarSpec =>
+    abnfConvert(src, opts)
+  tn.abnf = fn
+}
+
+
+export {
+  VERSION,
+  abnf,
+  abnfConvert,
+  parseAbnf,
+  emitGrammarSpec,
+  eliminateLeftRecursion,
+  abnfRules,
+  AbnfParseError,
+  abnfCompile,
+  toRecognitionSpec,
+  toPureSpec,
+  toJsonic,
+  attachActions,
+  attachActionSlots,
+  markListing,
+  AbnfCompileError,
+  AbnfActionError,
+}
+
+export type { AbnfConvertOptions, AbnfCompileOptions, ActionsMap }
+
+
+// VERSION is this package's version. It MUST equal package.json "version":
+// the release orchestrator rewrites both, and the version test fails the
+// build if they drift. Mirrors `const VERSION` in go/abnf.go.
+const VERSION = '0.4.17'

package/src/bin/tabnas-abnf-cli.ts

@@ -0,0 +1,222 @@
+/* Copyright (c) 2025 Richard Rodger and other contributors, MIT License */
+
+/*  tabnas-abnf-cli.ts
+ *  CLI wrapper for the ABNF -> tabnas grammar spec converter.
+ */
+
+import Fs from 'node:fs'
+
+import { abnfConvert, abnfCompile, markListing, AbnfCompileError } from '../abnf'
+import { Tabnas } from '@tabnas/parser'
+
+
+export async function run(argv: string[], console: Console) {
+  const args = {
+    help: false,
+    stdin: false,
+    files: [] as string[],
+    inline: [] as string[],
+    start: undefined as string | undefined,
+    tag: undefined as string | undefined,
+    space: 2,
+    // When set, convert and install the grammar, parse each sample,
+    // and report the tree (or an error) instead of the spec.
+    parse: [] as string[],
+    parseFiles: [] as string[],
+    // Compilation mode: emit a pure-data grammar as jsonic text.
+    compile: false,
+    // With --compile, emit the full AST grammar (tree builtins kept)
+    // instead of the recognition-only grammar.
+    full: false,
+    // List the marks the compiler assigns (for @rule:o|c:mark actions).
+    marks: false,
+  }
+
+  for (let aI = 2; aI < argv.length; aI++) {
+    const arg = argv[aI]
+    if ('-' === arg) {
+      args.stdin = true
+    } else if ('--help' === arg || '-h' === arg) {
+      args.help = true
+    } else if ('--file' === arg || '-f' === arg) {
+      args.files.push(argv[++aI])
+    } else if ('--start' === arg || '-s' === arg) {
+      args.start = argv[++aI]
+    } else if ('--tag' === arg || '-t' === arg) {
+      args.tag = argv[++aI]
+    } else if ('--compact' === arg || '-c' === arg) {
+      args.space = 0
+    } else if ('--compile' === arg || '-C' === arg) {
+      args.compile = true
+    } else if ('--full' === arg || '-F' === arg) {
+      args.compile = true
+      args.full = true
+    } else if ('--marks' === arg || '-m' === arg) {
+      args.marks = true
+    } else if ('--parse' === arg || '-P' === arg) {
+      args.parse.push(argv[++aI])
+    } else if ('--parse-file' === arg) {
+      args.parseFiles.push(argv[++aI])
+    } else if (arg && !arg.startsWith('-')) {
+      args.inline.push(arg)
+    }
+  }
+
+  if (args.help) {
+    return help(console)
+  }
+
+  let src = ''
+  for (const fp of args.files) {
+    if ('string' === typeof fp && '' !== fp) {
+      src += Fs.readFileSync(fp).toString() + '\n'
+    }
+  }
+  for (const inline of args.inline) {
+    src += inline + '\n'
+  }
+
+  if ('' === src.trim() || args.stdin) {
+    src += await readStdin(console)
+  }
+
+  const spec = abnfConvert(src, { start: args.start, tag: args.tag })
+
+  // Marks mode: list the user-action marks the compiler assigns.
+  if (args.marks) {
+    console.log(markListing(abnfConvert(src, {
+      start: args.start, tag: args.tag, marks: true,
+    })))
+    return
+  }
+
+  // Compilation mode: emit a pure recognition grammar as jsonic text.
+  // No function references — recognition is fully structural. Grammars
+  // that need control functions (probe / unbounded lookahead) are
+  // refused until those ship as engine `$`-builtins.
+  if (args.compile) {
+    try {
+      console.log(abnfCompile(src, {
+        start: args.start,
+        tag: args.tag,
+        indent: args.space || 2,
+        recognition: !args.full,
+      }))
+    } catch (e: any) {
+      if (e instanceof AbnfCompileError) {
+        console.error(e.message)
+        process.exitCode = 1
+        return
+      }
+      throw e
+    }
+    return
+  }
+
+  // Parse-mode: validate the grammar against one or more sample
+  // inputs and print their parse trees. Exits 1 if any sample fails.
+  if (args.parse.length > 0 || args.parseFiles.length > 0) {
+    const samples: { label: string; input: string }[] = []
+    for (const fp of args.parseFiles) {
+      samples.push({
+        label: fp,
+        input: Fs.readFileSync(fp).toString(),
+      })
+    }
+    for (const inp of args.parse) {
+      samples.push({ label: inp, input: inp })
+    }
+
+    // Bare engine: the ABNF spec we're about to install supplies the
+    // grammar, so we don't need any other plugin.
+    const j = new Tabnas()
+    j.grammar(spec)
+
+    let failed = 0
+    for (const { label, input } of samples) {
+      try {
+        const tree = j.parse(input)
+        console.log(
+          `ok: ${JSON.stringify(label)} -> ` +
+          JSON.stringify(tree, null, args.space || undefined))
+      } catch (e: any) {
+        failed++
+        const msg = (e?.message || String(e)).split('\n')[0]
+        console.error(`fail: ${JSON.stringify(label)}: ${msg}`)
+      }
+    }
+    if (failed > 0) {
+      process.exitCode = 1
+    }
+    return
+  }
+
+  console.log(JSON.stringify(spec, null, args.space || undefined))
+}
+
+
+async function readStdin(console: Console): Promise<string> {
+  if ('string' === typeof (console as any).test$) {
+    return (console as any).test$
+  }
+  if (process.stdin.isTTY) return ''
+  let s = ''
+  process.stdin.setEncoding('utf8')
+  for await (const p of process.stdin) s += p
+  return s
+}
+
+
+function help(console: Console) {
+  console.log(`
+tabnas-abnf: convert an ABNF grammar into a tabnas grammar spec.
+
+Usage: tabnas-abnf <args> [<abnf-source>]*
+
+Arguments:
+  -                      Read ABNF source from stdin.
+  --file <path>          Read ABNF source from <path> (repeatable).
+  -f <path>
+
+  --start <name>         Set the start rule (defaults to the first
+  -s <name>                production).
+
+  --tag <name>           Group tag applied to every emitted alt.
+  -t <name>                Defaults to \`abnf\`.
+
+  --compact              Emit single-line JSON (default indent is 2).
+  -c
+
+  --compile              Compilation mode: emit a pure-data *recognition*
+  -C                       grammar as jsonic text (no closures; control
+                           and tree building reference engine
+                           \`$\`-builtins).
+
+  --full                 With compilation mode, emit the full AST
+  -F                       grammar (tree \`$\`-builtins retained) instead
+                           of recognition-only. Still pure data.
+
+  --marks                List the per-alt marks the compiler assigns,
+  -m                       usable as \`@<rule>:o|c:<mark>\` action refs.
+
+  --parse <input>        Parse <input> against the generated grammar
+  -P <input>               and print its parse tree. Repeatable.
+                           Exits non-zero if any sample fails.
+
+  --parse-file <path>    Parse the contents of <path> against the
+                           generated grammar (repeatable).
+
+  --help                 Print this help message.
+  -h
+
+Grammar dialect:
+  Rules are ABNF-style: \`name = element ...\`, with \`/\` for choice and
+  double-quoted literals. For example: \`greet = "hi" / "hello"\`.
+
+Examples:
+  > tabnas-abnf 'greet = "hi" / "hello"'
+  > tabnas-abnf -f grammar.abnf
+  > echo 'g = "a"' | tabnas-abnf -
+  > tabnas-abnf -f grammar.abnf --parse 'hi'
+`)
+}

package/src/compile.ts

@@ -0,0 +1,62 @@
+/* Copyright (c) 2026 Richard Rodger and other contributors, MIT License */
+
+/*  compile.ts
+ *  Compilation mode for ABNF: convert the source, then serialise the
+ *  resulting spec as pure-data tabnas grammar text.
+ *
+ *  The spec transforms themselves (recognition/pure lowering, jsonic
+ *  serialisation, user action attachment) are notation-neutral and live
+ *  in `@tabnas/bnf`. This file keeps the ABNF-named public API those
+ *  transforms used to be exported under, plus `abnfCompile`, which is
+ *  the only piece that needs to know how to parse ABNF.
+ */
+
+import type { GrammarSpec } from '@tabnas/parser'
+
+import {
+  compileSpec,
+  toRecognitionSpec,
+  toPureSpec,
+  toJsonic,
+  attachActions,
+  attachActionSlots,
+  markListing,
+  CompileError,
+  ActionError,
+} from '@tabnas/bnf'
+
+import type {
+  CompileOptions,
+  JsonicOptions,
+  ActionsMap,
+} from '@tabnas/bnf'
+
+import { abnf as abnfConvert } from './converter'
+
+// Historical names for the shared errors and options. These are
+// re-exports, not `const` aliases: a `const` would carry only the value
+// side, so `let e: AbnfCompileError` would stop compiling (TS2749).
+export { CompileError as AbnfCompileError, ActionError as AbnfActionError }
+type AbnfCompileOptions = CompileOptions
+
+
+// Compile ABNF source into a pure-data tabnas grammar as jsonic text.
+// Always converts with `builtins: true` so probe dispatch and tree
+// building serialise as `@…$` builtin refs (no closures).
+export function abnfCompile(src: string, opts: AbnfCompileOptions = {}): string {
+  const spec: GrammarSpec = abnfConvert(src,
+    { start: opts.start, tag: opts.tag, builtins: true, marks: true })
+  return compileSpec(spec, opts)
+}
+
+
+export {
+  toRecognitionSpec,
+  toPureSpec,
+  toJsonic,
+  attachActions,
+  attachActionSlots,
+  markListing,
+}
+
+export type { AbnfCompileOptions, JsonicOptions, ActionsMap }