The three modes
One grammar, three ways to run it, identical results from all of them. You write the combinators once; the mode only decides when they turn into running code, and how fast that code ends up being.
| Mode | Setup | Per-parse work | Where it fits |
|---|---|---|---|
| Interpreter | None | Runs the grammar directly, with automatic optimizations for parsers that return JavaScript values | Tests, REPLs, dynamic grammars, browsers, anywhere a bundler isn't around |
| Macro build | Bundler plugin + with { type: 'macro' } — lowers at build time | Runs a table artifact through the shared table runtime; a module's terminal grammar also embeds generated code for its hottest sites | Production apps built with Vite/Rollup/webpack |
compile() | Call compile() — lowers once at runtime | Runs a specialised live table assembly, with a closure fallback | Grammars assembled dynamically at runtime |
Most projects live in the first two. compile() is there for the grammars you can't know about until runtime.
Interpreter (the default)
Import a combinator, call parse(), done. Parsers that return ordinary JavaScript values are optimized automatically, while advanced features such as recovery, line tracking, and CST/trivia capture continue to work as before. There is no build step, no new Function, and nothing to configure. The interpreter stays lightweight for browsers and runs anywhere JavaScript does.
import { choice, literal, parse } from 'parseman'
const yesNo = choice(literal('yes'), literal('no'))
parse(yesNo, 'yes') // { ok: true, value: 'yes', … }This is the mode your tests use, and it's the safety net the other two fall back to when their tooling isn't around.
Macro build (no runtime compile step)
Register the bundler plugin and add with { type: 'macro' } to your parseman import — that's standard import-attributes syntax, with macro as the bundler convention for "evaluate this at build time."
At build time the plugin runs your combinator declarations and replaces them with a table literal. Ordinary rules stay compact data. A module's terminal grammar — its composeLeaf(), or a compose() in a module that declares no composeLeaf() — gets one extra thing: generated code for its hottest sites, baked in at build time, within a budget of the module's own code, comments and whitespace aside (the plugin's assemblyBudget, a half by default). The closure engine runs every other site. Its line-tracking and CST siblings stay compact, so you don't pay for that four times over (test/unit/table-selective-assembly.test.ts; pnpm size:guard:jess holds jess's four grammars within 5× their source).
The combinator import vanishes. Every artifact imports the shared parseman/table runtime instead of carrying its own copy of a parser.
Running the grammar is still a parse() call, so parseman stays an ordinary import in the code that drives the parser. The macro removes the combinators and the compiler from your bundle — not the driver.
import { literal, sequence, choice } from 'parseman' with { type: 'macro' }Same combinators, nothing else changes. If the attribute ever gets stripped — an older bundler, a test runner — it's silently ignored and the interpreter takes over. Identical results, no errors, no drama. This is the recommended path for shipping apps; the details live in Macro mode.
compile() (runtime lowering)
compile() runs the same optimizer as the plugin, just later. Reach for it when you assemble a grammar from config or user input, or when you want the speed without adding a build step:
import { choice, literal, compile } from 'parseman'
const compiled = compile(choice(literal('yes'), literal('no')))
compiled.parse('yes', 0, { trackLines: false }) // { ok: true, value: 'yes', … }
compiled.source // printable table module source
compiled.inlineExpression // table expression (requires tableRules)parse(input, pos, ctx) takes the same arguments as a combinator's own parse. A lexer that asks a compiled grammar what starts at many positions passes one context to every call; without one, each call makes its own.
compile() also takes a whole rule map — a rules() grammar or a runtime compose() result — and returns a map of runnable table rules that run() and parseDoc() accept:
const table = compile(compose([baseGrammar, dialectRules]))
run(table.Stylesheet, source)Content Security Policy
compile() is the ONLY place Parseman constructs code at runtime. A live parser it returns tries to specialise its table once with new Function; if the environment rejects that, Parseman catches the EvalError and runs the same table on the closure assembler. Everything else — the interpreter, runtime compose() and composeLeaf(), linkable(), loading macro or printed artifacts, and the spec/railroad tooling — never turns a string into code, so all of it parses under a strict Content Security Policy.
test/unit/csp-runtime-paths.test.ts decides this for every runtime path: in-process with Function and eval spied (zero calls outside compile()), and in a child process under --disallow-code-generation-from-strings, where every path, compile() included, parses exactly what it parses unrestricted.
A terminal grammar's selective assembly is one ordinary function literal for its strict AST/no-lines option set; it is emitted by the build, not constructed from source at runtime. A grammar whose budget does not cover the assembly's fixed prelude stays on the empty-inventory closure form (test/unit/canonical-closure-artifact.test.ts).
test/unit/no-function-constructor.test.ts proves the serialized and macro routes never reach globalThis.Function. test/unit/canonical-closure-artifact.test.ts separately proves one-time live specialisation, cache reuse, and the blocked-Function closure fallback.
Compiling costs something up front — roughly 75–650 µs depending on how big the grammar is — so it pays off when you're parsing many inputs through the same compiled parser, and not much when you're parsing one.
Choosing a mode
- Shipping an app through a bundler? Use the macro build — no compile step at runtime, and it falls back to the interpreter automatically anywhere the attribute is stripped.
- Writing tests, scripts, or a REPL? Use the interpreter. It's the default and needs nothing.
- Building a grammar from user input or config at runtime? Use
compile(); it specialises a live table when permitted and falls back automatically under CSP.
Since all three produce identical results, you can develop against the interpreter and flip on the macro for production without touching a line of grammar.
Debugging compiled grammars
Compiled parsers have a reputation for being undebuggable. That reputation is earned elsewhere, not here — what you step through depends on the mode, and two of the three show you your own source:
| Mode | What you step through |
|---|---|
| Interpreter | Your combinator source directly — no compilation, no indirection |
| Macro build | Your combinator source via source maps — breakpoints on choice(...) lines hit when the compiled function runs |
compile() | Generated JS (compiled.source) — no IDE source maps today |
Interpreter is the easiest place to be while you're still writing the grammar. You're running the tree you wrote, so a breakpoint lands exactly where you'd expect.
Macro build compiles that tree away, but the bundler plugin emits precise source maps via magic-string. Step through in a debugger and you see your combinator source, not the emitted codePointAt dispatch.
compile() hands you the generated source as a string you can read, but doesn't wire up IDE source maps today. The pragmatic move: develop on the interpreter, switch to macro or compile() once the grammar has stopped moving.
