exprforge 0.2.1 → 0.3.0

package/README.md

@@ -21,10 +21,12 @@
 Author a math expression once, as a small AST, and emit verified,
 identical-behavior implementations in JavaScript, TypeScript, Python, C#,
 Lua, QB64, C, Java, Go, Rust, Perl, PHP, Julia, Fortran, Zig, Scheme
-(Guile), and COBOL (GnuCOBOL).
+(Guile), and COBOL (GnuCOBOL) — plus a native in-process evaluator and a
+printer for exprforge's own readable syntax (see `fn`/`expr` below).
 
-No parser, no dependencies. You build the AST directly with plain JS
-functions; the same tree is walked once per target language.
+No required dependencies. You can build the AST directly with plain JS
+functions, or author it as readable infix text via `expr`/`fn` (see
+below) — either way, the same tree is walked once per target.
 
 ## Why
 
@@ -52,6 +54,46 @@ Neither is "translate my code for me" — it's "prove two independent
 implementations of one formula actually match," which is a narrower,
 checkable claim.
 
+## Layered by design
+
+Everything here is layered, and the layers don't reach back into each
+other — worth being explicit about, especially if you're evaluating this
+for something like a migration and want to know exactly what you're
+trusting:
+
+- **The AST and its emitters — the whole value proposition.** `ast.js`'s
+  builders (`num`, `v`, `add`, `mul`, `letIn`, `select`, `outputs`, ...)
+  build a plain tree of plain objects; every `emitters/<lang>.js` file
+  turns that tree into target-language source text. This is also the
+  *entire* dependency graph for it: every emitter requires only
+  `emitters/base.js` and `ast.js` — nothing else in this repo. No parser,
+  no custom syntax, no interpreter sits between your AST and the code it
+  emits. Every example in `samples/` is built this way, and the library
+  worked exactly this way for its first two published releases, before
+  anything below existed.
+- **`expr`/`fn` — optional authoring sugar.** Nested builder calls
+  (`add(mul(v("a"), v("b")), num(1))`) get hard to read past a few terms.
+  `expr`/`fn` are a small hand-rolled tokenizer and recursive-descent
+  parser that turn ordinary infix text (`` expr`a * b + 1` ``) into
+  *exactly* the same tree the builders would — checked by structural unit
+  tests and a full print-reparse-evaluate round trip across every sample
+  this project has (see "Testing" below), not just asserted. It's
+  genuinely optional: nothing in the AST/emitter layer above calls into
+  it or imports it. Don't want a parser in your dependency graph, for a
+  security review or otherwise? Don't call `expr`/`fn` — build the tree
+  with the plain functions instead, and every emitter behaves identically
+  either way.
+- **The native evaluator and the `expr`-syntax printer — additive
+  conveniences.** `evaluate()` (compute a result in-process, no
+  target-language toolchain needed) and the `expr` emitter target (print
+  any AST back out as readable text) sit off to the side the same way
+  `expr`/`fn` do — nothing else depends on them either.
+
+If you only care about "does this correctly turn my AST into
+COBOL/Java/whatever" — `ast.js` and the one `emitters/<lang>.js` file you
+care about are the entire surface that matters. Everything else is there
+if you want it, invisible if you don't.
+
 ## Install
 
 ```
@@ -61,12 +103,12 @@ npm install exprforge
 ## Usage
 
 ```js
-const { num, v, bin, mul, add, sub, emitAll } = require("exprforge");
+const { expr, emitAll } = require("exprforge");
 
 const fn = {
     name: "lerp",
     params: ["a", "b", "t"],
-    body: add(v("a"), mul(sub(v("b"), v("a")), v("t"))),
+    body: expr`(b - a) * t + a`,
 };
 
 const outputs = emitAll(fn);
@@ -74,6 +116,13 @@ console.log(outputs.rust.source);
 console.log(outputs.c.source);
 ```
 
+`` expr`(b - a) * t + a` `` and `add(v("a"), mul(sub(v("b"), v("a")), v("t")))`
+build the *exact same tree* — `expr` (see below) is optional infix syntax
+sugar over the same builders, not a different API. Every example below
+still uses the builders directly, since that's what `expr` compiles down
+to and what you'll reach for once a formula needs `${...}`-spliced
+sub-expressions.
+
 ## Samples
 
 `samples/` has worked, non-trivial examples (also exported from the
@@ -236,6 +285,98 @@ See [`docs/planned-additions.md`](./docs/planned-additions.md) for the
 full design rationale, including why the naive "guard division with
 select" pattern is wrong.
 
+## Infix expression syntax (`` expr` ` ``)
+
+`add(mul(v("a"), v("b")), num(1))` is exactly what gets built, but it's
+not what a human reads at a glance. `expr` is a tagged template literal
+that parses ordinary infix math syntax into that same tree — same nodes,
+different spelling, no new capability:
+
+```js
+const { v, expr } = require("exprforge");
+
+expr`a * b + 1`
+// identical tree to add(mul(v("a"), v("b")), num(1))
+
+expr`(-b + sqrt(b^2 - 4*a*c)) / (2*a)`
+// the quadratic formula, readable as the quadratic formula
+```
+
+| Syntax | Lowers to |
+|---|---|
+| `+ - * /` | `add`/`sub`/`mul`/`div` — standard precedence, left-associative |
+| `^` | `call("pow", base, exponent)` — **not** a `bin` node (there is no `"^"` operator in the AST; every emitter's `calls` table keys `pow` by name, even targets whose own syntax has a native `^`/`**`). Right-associative and binds *tighter* than unary minus, standard math convention: `-2^2` is `-4`, `2^3^2` is `512`. |
+| `-x` | `neg(x)` |
+| `name(args...)` | `call("name", ...args)` — not checked against the 22 known functions at parse time, same deferred-to-emission-time error every hand-built `call()` already gets |
+| bare `name` | `v("name")` |
+| `cond ? then : else` | `select(cmp(left, op, right), then, else)` — the **only** place a comparison (`> < >= <= == !=`) is valid, matching `cmp()`'s own documented constraint that it's never a general boolean expression. A bare `a > b` with no `?` is a parse-time error, not a deferred one. Chains naturally: `a>0 ? 1 : b>0 ? 2 : 3`. |
+| `${...}` | Splices in an existing AST node as-is, or a plain JS number (auto-wrapped via `num()`). Anything else throws immediately. Plain strings aren't interpolatable — a bare identifier in the template text already means "variable", with no `${}` needed. |
+
+Deliberately **not** in the grammar: `let`/`outputs` blocks (it's a pure
+expression grammar, same "expression AST, not a program AST" boundary as
+the rest of exprforge — wrap the result in `letIn`/`letChain`/`outputs`,
+or reach for `fn` below, which adds exactly that) and `&&`/`||` (the AST
+has no boolean-combinator node to lower them to).
+
+```js
+// Named subexpressions still go around expr(), not inside it:
+letIn("mag", expr`sqrt(x^2 + y^2)`, expr`x / mag`)
+```
+
+## Full-program syntax (`` fn`...` ``)
+
+`expr` covers one expression; `fn` covers a whole function body —
+`let` bindings plus a `return`, on top of the exact same expression
+grammar (every expression inside a `fn` template is parsed by the same
+engine `expr` uses). Lowers to real `letChain`/`outputs` calls, same
+"same nodes, different spelling" guarantee as `expr` itself:
+
+```js
+const { fn } = require("exprforge");
+
+const body = fn`
+    let mag = sqrt(x^2 + y^2);
+    return { nx: x / mag, ny: y / mag };
+`;
+// identical tree to:
+//   letIn("mag", call("sqrt", ...), outputs({ nx: div(v("x"), v("mag")), ny: ... }))
+
+const normalize2 = { name: "normalize2", params: ["x", "y"], body };
+```
+
+| Syntax | Lowers to |
+|---|---|
+| `let name = expr;` | one `[name, valueNode]` pair, in order — a later `let` can reference an earlier one's name |
+| `return expr;` | the chain's final expression |
+| `return { name: expr, ... };` | `outputs({ name: node, ... })` as the chain's final expression |
+
+Duplicate `let` names aren't rejected by the parser itself — same
+deferred-to-`collectLets` behavior every hand-built `letIn`/`letChain`
+already has. A `fn` body with no `let` statements at all is just
+`return expr;`, equivalent to a bare `expr` call.
+
+## Printing an AST back out, and a native evaluator
+
+Two things that fall out of `fn` existing: `emitters.expr` is a real,
+registered 18th target that prints any AST *back out* as `fn`/`expr`
+source text (the reverse of parsing it) — useful for debugging a
+formula built from several composed helpers, or just getting a readable
+string to log or paste into a future `fn`/`expr` call. And `evaluate(fn,
+args)` (also exported from the main package) is a native tree-walking
+interpreter over the same AST, computing a result directly in JS with no
+codegen or compile step — the same node types every emitter already
+handles, backed by the real `Math.*` functions.
+
+```js
+const { emitAll, evaluate } = require("exprforge");
+
+emitAll(normalize2).expr.source;
+// "let mag = sqrt(((x^2) + (y^2)));\nreturn { nx: (x / mag), ny: (y / mag) };\n"
+
+evaluate(normalize2, [3, 4]);
+// { nx: 0.6, ny: 0.8 }
+```
+
 ## Multiple named outputs
 
 `outputs({ name: Node, ... })` computes several named values from ONE
@@ -295,13 +436,27 @@ pre-declared locals the way Go's named returns are.
 npm test
 ```
 
-Runs `node --test`. For each sample, that's two kinds of check:
+Runs `node --test`. For each sample, that's three kinds of check:
 
 - Emitted JS vs. an independently hand-written reference implementation
   (catches a wrong formula in the AST itself).
 - Every other emitted target vs. that same JS, compiled (and, for
   TypeScript, also type-checked under `--strict`) and run, with the sample
   inputs as arguments (catches an emitter bug).
+- The `expr`-syntax printer (`emitters/exprsyntax.js`) vs. `fn`'s own
+  parser: every sample AST in this suite is printed back out as `fn`/
+  `expr` source text, reparsed, and evaluated (via `evaluate()`) to
+  confirm the round trip behaves identically to the original. This is a
+  stronger claim than either piece being separately unit-tested — the
+  printer and the parser are two independent pieces of code that have to
+  agree with each other across every real formula this project has, not
+  just cases either one's own author thought to hand-write a test for.
+  It's also not hypothetical: this exact check caught a real bug during
+  development (a ternary printed without enough parens, so
+  `crossX / (rLen > eps ? rLen : 1)` reparsed with the wrong grouping)
+  that every other check here — including full cross-language conformance
+  — had no way to catch, since it's specific to the printer/parser pair
+  and nothing else in the pipeline touches that code path.
 
 The compiled/interpreted-language checks need their toolchain on `PATH`
 and skip (not fail) when it's missing, so `npm test` degrades gracefully

package/emitters/cobol.js

@@ -62,6 +62,35 @@ function checkReservedNames(names) {
     }
 }
 
+// Separate from COBOL_RESERVED above (general keywords/intrinsics, safe
+// to forbid everywhere including internal let-bindings) and checked only
+// against names that end up in a CALL/PROCEDURE DIVISION USING clause
+// (fn.name, params, output fields) -- NOT let-bindings. A bare "c"
+// (case-insensitive) breaks specifically in a USING identifier list --
+// confirmed against a real compiler ("syntax error, unexpected C"),
+// reproducible in isolation, and not shared by neighboring single letters
+// (b/d/e/... all compile fine in the identical position; likely GnuCOBOL
+// misparsing it as an attempted abbreviation of BY CONTENT). Deliberately
+// NOT added to COBOL_RESERVED: a plain WORKING-STORAGE item named "c"
+// referenced only in COMPUTE statements compiles fine (confirmed too),
+// and samples/spline-frame.js already has a working "c" let-binding (for
+// cos(rad)) that would break for no real reason if this were checked
+// there as well.
+const COBOL_USING_RESERVED = new Set(["c"]);
+
+function checkUsingClauseNames(names) {
+    for (const name of names) {
+        if (COBOL_USING_RESERVED.has(name.toLowerCase())) {
+            throw new Error(
+                `emitter for .cob: "${name}" can't be a function/parameter/output name -- it breaks ` +
+                `GnuCOBOL's CALL ... USING clause specifically (confirmed against a real compiler), ` +
+                `even though it's fine as an internal let-binding name (see COBOL_USING_RESERVED in ` +
+                `emitters/cobol.js) -- rename it`,
+            );
+        }
+    }
+}
+
 function fn1(name) {
     return ([x]) => `FUNCTION ${name}(${x})`;
 }
@@ -241,6 +270,35 @@ function expandExponential(s) {
     return sign + result;
 }
 
+// "**" must never end up nested inside ANOTHER call's argument -- that's
+// the actual, general form of the confirmed bug (see the file header):
+// some GnuCOBOL 4.x builds route a "**" expression through a broken
+// internal decimal codegen path (missing header for cob_decimal) when
+// it's nested inside a FUNCTION(...) argument, e.g. sqrt(a^2 + b^2) --
+// confirmed against real CI, not reproducible against this project's own
+// (older) local GnuCOBOL. A plain top-level "**" (kitchen-sink's
+// pow(x, y), summed directly, never nested as another call's argument)
+// is fine.
+//
+// Rather than rely on every caller remembering to keep a pow() result out
+// of anywhere risky, pow ALWAYS spills its own result here: call("pow", a,
+// b) unconditionally evaluates to a bare temp name, so "**" can only ever
+// appear in its own dedicated COMPUTE statement, never nested inside
+// anything else regardless of what the surrounding expression does with
+// the result. hypot's internal sum-of-squares reuses this directly, since
+// it builds "**" itself rather than going through call("pow", ...).
+//
+// Arrow function callers below, not plain ones: base.js's emitExpr calls
+// `this.calls[node.name](args)` unbound -- this closes over the `emitter`
+// const the same way atan2 already does (see its own comment further
+// down), fully assigned by the time this ever actually runs.
+function spillPow(baseRaw, exponentRaw) {
+    const pool = emitter._pool;
+    const base = pool.spill(baseRaw);
+    const exponent = pool.spill(exponentRaw);
+    return pool.spill(`(${base} ** ${exponent})`);
+}
+
 const emitter = new CobolEmitter({
     ext: "cob",
     formatNumber: (v) => {
@@ -252,13 +310,21 @@ const emitter = new CobolEmitter({
         asin: fn1("ASIN"), acos: fn1("ACOS"), atan: fn1("ATAN"),
         exp: fn1("EXP"), log: fn1("LOG"), log10: fn1("LOG10"),
         min: fn2("MIN"), max: fn2("MAX"),
-        pow: ([x, y]) => `(${x} ** ${y})`,
+        pow: ([x, y]) => spillPow(x, y),
         // No LOG2 intrinsic -- derive it (nesting two intrinsics is fine;
         // only nesting a call inside a USER-DEFINED function's argument
         // was the confirmed problem -- see the file header).
         log2: ([x]) => `(FUNCTION LOG(${x}) / FUNCTION LOG(2.0))`,
-        // No HYPOT intrinsic -- derive it the same way.
-        hypot: ([a, b]) => `FUNCTION SQRT((${a}) ** 2 + (${b}) ** 2)`,
+        // No HYPOT intrinsic -- derive it via spillPow (see its own
+        // comment): the sum-of-squares itself also gets spilled to its
+        // own temp before FUNCTION SQRT ever sees it, so SQRT's argument
+        // is always a bare name, never a "**"-containing expression.
+        hypot: ([aRaw, bRaw]) => {
+            const aSq = spillPow(aRaw, "2.0");
+            const bSq = spillPow(bRaw, "2.0");
+            const sumSq = emitter._pool.spill(`${aSq} + ${bSq}`);
+            return `FUNCTION SQRT(${sumSq})`;
+        },
         // FUNCTION INTEGER is floor (greatest integer <= x, confirmed
         // against a real compiler, including for negatives). COMPUTE's
         // automatic numeric conversion hands it back as COMP-2 with no
@@ -358,6 +424,7 @@ const emitter = new CobolEmitter({
     // the program name as a plain string literal, immune to that.
     formatFunction: (fn, body, letLines, letDecls, bodyLines) => {
         checkReservedNames([fn.name, ...fn.params]);
+        checkUsingClauseNames([fn.name, ...fn.params]);
         const linkageParams = [...fn.params, "ef-result"];
         const paramDecls = linkageParams.map((p) => `       01 ${p} USAGE COMP-2.`).join("\n");
         const wsDecls = letDecls.map((n) => `       01 ${n} USAGE COMP-2.`).join("\n");
@@ -382,6 +449,7 @@ const emitter = new CobolEmitter({
     formatSuite: (fn, outputStrs, letLines, letDecls, outputLines) => {
         const outputNames = Object.keys(outputStrs);
         checkReservedNames([fn.name, ...fn.params, ...outputNames]);
+        checkUsingClauseNames([fn.name, ...fn.params, ...outputNames]);
         const linkageParams = [...fn.params, ...outputNames];
         const paramDecls = linkageParams.map((p) => `       01 ${p} USAGE COMP-2.`).join("\n");
         const wsDecls = letDecls.map((n) => `       01 ${n} USAGE COMP-2.`).join("\n");

package/emitters/exprsyntax.js

@@ -0,0 +1,81 @@
+// exprforge/emitters/exprsyntax.js
+//
+// Prints an AST back out as fn`...`/expr`...`-compatible source text --
+// the reverse direction of expr.js/fn.js. Not a third-party language:
+// there's no external compiler/interpreter to run this output through,
+// so it's verified by round-trip instead (emit -> reparse via fn() ->
+// deepStrictEqual the original, see test/exprsyntax-emitter.test.js).
+// Registered as a real target anyway (emitters.expr) since fn/expr
+// syntax is a real, standalone, human-pasteable output format in its
+// own right, not just a test fixture.
+//
+// "call" is overridden wholesale rather than populated via a `calls`
+// table: every intrinsic passes through uniformly as `name(args...)`
+// except pow, which recovers fn/expr's own `^` sugar -- both forms
+// lower back to the identical call("pow", ...) node (see expr.js's
+// grammar comment on rule 2), so this is a readability choice, not a
+// correctness one. A side effect: this is the one emitter that never
+// needs a table update when a new intrinsic is added anywhere else in
+// the project.
+const Emitter = require("./base.js");
+
+class ExprSyntaxEmitter extends Emitter {
+    emitExpr(node) {
+        if (node.type === "call" && node.name === "pow" && node.args.length === 2) {
+            const [base, exponent] = node.args.map((a) => this.emitExpr(a));
+            return `(${base}^${exponent})`;
+        }
+        if (node.type === "call") {
+            const args = node.args.map((a) => this.emitExpr(a));
+            return `${node.name}(${args.join(", ")})`;
+        }
+        return super.emitExpr(node);
+    }
+}
+
+function letLines(letBindings) {
+    return letBindings.map(({ name, valueStr }) => `let ${name} = ${valueStr};`);
+}
+
+const emitter = new ExprSyntaxEmitter({
+    ext: "fn",
+    // fn/expr accepts JS-style numeric literal syntax directly -- it's
+    // literally the same NUMBER lexing rule (see expr.js's tokenizer).
+    formatNumber: (v) => String(v),
+    // base.js's default _defaultSelect wraps just the comparison in its
+    // own parens ("((L op R) ? then : else)") -- fn/expr's ternary
+    // grammar has no parenthesized-COMPARISON form (see expr.js's
+    // grammar comment: `ternary := additive compOp additive "?" ...`),
+    // so "(L op R)" alone would try to parse as a complete, paren-
+    // wrapped ternary condition with no "?" in sight and hit the parser's
+    // own "comparison must be used as a ternary condition" error. This
+    // wraps the WHOLE ternary in one outer paren pair instead -- still a
+    // valid `primary := ... | "(" expression ")" | ...`, and unlike the
+    // unwrapped form, safe to embed as a sub-expression anywhere (e.g.
+    // `crossX / (rLen > eps ? rLen : 1)`) without the surrounding
+    // operator's precedence reaching into the ternary's own condition.
+    emitSelect: function (condNode, thenStr, elseStr) {
+        const L = this.emitExpr(condNode.left);
+        const R = this.emitExpr(condNode.right);
+        return `(${L} ${condNode.op} ${R} ? ${thenStr} : ${elseStr})`;
+    },
+    // Output is bare fn/expr source text -- no JS wrapper/boilerplate.
+    // That's both the most direct thing to paste into a real
+    // `` fn`...` `` call, and exactly what the round-trip test reparses
+    // with zero unwrapping first.
+    formatFunction: (fn, bodyStr, letBindings = []) => {
+        const lines = letLines(letBindings);
+        lines.push(`return ${bodyStr};`);
+        return lines.join("\n") + "\n";
+    },
+    formatSuite: (fn, outputStrs, letBindings = []) => {
+        const lines = letLines(letBindings);
+        const fields = Object.entries(outputStrs)
+            .map(([name, valueStr]) => `${name}: ${valueStr}`)
+            .join(", ");
+        lines.push(`return { ${fields} };`);
+        return lines.join("\n") + "\n";
+    },
+});
+
+module.exports = emitter;

package/emitters/registry.js

@@ -19,4 +19,5 @@ module.exports = {
     zig: require("./zig.js"),
     scheme: require("./scheme.js"),
     cobol: require("./cobol.js"),
+    expr: require("./exprsyntax.js"),
 };

package/evaluate.js

@@ -0,0 +1,109 @@
+// exprforge/evaluate.js
+//
+// A native tree-walking interpreter over the exact same AST every
+// emitter compiles from -- evaluate(fn, args) computes a result (or a
+// {name: value} object for a multi-output suite) directly in JS, no
+// codegen/compile/subprocess step involved. Reuses collectLets (ast.js)
+// for the same let-lifting every emitter already goes through, so this
+// walks nodes in the identical dependency order every target does, and
+// there's exactly one node-shape contract (ast.js's own header comment)
+// for both this file and every emitters/<lang>.js to agree with.
+//
+// Every intrinsic name maps 1:1 onto emitters/js.js's own `calls` table
+// keys (the simplest existing source of truth for "what the ~22
+// intrinsics are called") straight to the real Math.* function -- this
+// target has no codegen step to route an intermediate string through.
+const { collectLets } = require("./ast.js");
+
+const CMP_OPS = {
+    ">": (a, b) => a > b,
+    "<": (a, b) => a < b,
+    ">=": (a, b) => a >= b,
+    "<=": (a, b) => a <= b,
+    "==": (a, b) => a === b,
+    "!=": (a, b) => a !== b,
+};
+
+const BIN_OPS = {
+    "+": (a, b) => a + b,
+    "-": (a, b) => a - b,
+    "*": (a, b) => a * b,
+    "/": (a, b) => a / b,
+};
+
+const CALLS = {
+    sqrt: Math.sqrt, abs: Math.abs, sin: Math.sin, cos: Math.cos, tan: Math.tan,
+    asin: Math.asin, acos: Math.acos, atan: Math.atan, log: Math.log,
+    log2: Math.log2, log10: Math.log10, exp: Math.exp, floor: Math.floor,
+    ceil: Math.ceil, round: Math.round, trunc: Math.trunc, sign: Math.sign,
+    pow: Math.pow, atan2: Math.atan2, min: Math.min, max: Math.max, hypot: Math.hypot,
+};
+
+// Handles every node type EXCEPT "let"/"outputs" -- those are only ever
+// valid pre-collectLets (a function's top-level let-chain/body shape),
+// never nested inside a bin/call/select, same constraint every emitter
+// already relies on (see ast.js's own comments on letIn/outputs).
+function evalNode(node, env) {
+    switch (node.type) {
+        case "num":
+            return node.value;
+        case "var":
+            if (!(node.name in env)) {
+                throw new Error(`evaluate(): unbound variable "${node.name}"`);
+            }
+            return env[node.name];
+        case "bin": {
+            const op = BIN_OPS[node.op];
+            if (!op) throw new Error(`evaluate(): unknown bin op "${node.op}"`);
+            return op(evalNode(node.left, env), evalNode(node.right, env));
+        }
+        case "call": {
+            const impl = CALLS[node.name];
+            if (!impl) throw new Error(`evaluate(): no mapping for Math function "${node.name}"`);
+            return impl(...node.args.map((a) => evalNode(a, env)));
+        }
+        case "select": {
+            const cmpFn = CMP_OPS[node.cond.op];
+            if (!cmpFn) throw new Error(`evaluate(): unknown cmp op "${node.cond.op}"`);
+            const cond = cmpFn(evalNode(node.cond.left, env), evalNode(node.cond.right, env));
+            return evalNode(cond ? node.then : node.else, env);
+        }
+        default:
+            throw new Error(
+                `evaluate(): unexpected node type "${node.type}" -- "let"/"outputs" must already ` +
+                `be lifted out by collectLets before evalNode runs`,
+            );
+    }
+}
+
+// evaluate(fn, args) -- fn is a {name, params, body} definition (the
+// same shape emitAll() consumes), args is a plain array positional to
+// fn.params. Returns a number for a plain body, or a {name: value}
+// object for a multi-output (outputs()) body -- matching the shape
+// test/conformance.test.js's own parseSuiteOutput() already expects
+// back from every other target.
+function evaluate(fn, args) {
+    if (args.length !== fn.params.length) {
+        throw new Error(`evaluate(): ${fn.name} expects ${fn.params.length} argument(s), got ${args.length}`);
+    }
+    const env = {};
+    fn.params.forEach((name, i) => {
+        env[name] = args[i];
+    });
+
+    const { bindings, body } = collectLets(fn.body);
+    for (const { name, node } of bindings) {
+        env[name] = evalNode(node, env);
+    }
+
+    if (body.type === "outputs") {
+        const result = {};
+        for (const [name, node] of Object.entries(body.fields)) {
+            result[name] = evalNode(node, env);
+        }
+        return result;
+    }
+    return evalNode(body, env);
+}
+
+module.exports = { evaluate };

package/expr.js

@@ -0,0 +1,313 @@
+// exprforge/expr.js
+//
+// Infix syntax sugar over ast.js's own builders -- NOT a new node type or
+// a new capability. `` expr`a * b + 1` `` builds exactly the same tree
+// `add(mul(v("a"), v("b")), num(1))` would, by calling num/v/add/sub/mul/
+// div/neg/call/cmp/select directly (never constructing a raw {type: ...}
+// object by hand), so every guarantee those builders already have
+// (collectLets round-tripping, emitter compatibility) carries over for
+// free. Unlike util.js's forComponents, this DOES return a Node -- it's
+// closer in spirit to letChain (also in ast.js): a different way to
+// spell the same tree, not a different tree.
+//
+// A tagged template literal, not a plain string function: `expr` is
+// called by JS itself as expr(strings, ...values) -- see the grammar
+// comment below for why that's the whole interpolation mechanism, with
+// no `${` text syntax of its own to parse.
+//
+// Grammar:
+//
+//   expression     := ternary
+//   ternary        := additive ( compOp additive "?" expression ":" expression )?
+//   compOp         := ">" | "<" | ">=" | "<=" | "==" | "!="
+//   additive       := multiplicative ( ("+"|"-") multiplicative )*
+//   multiplicative := unary ( ("*"|"/") unary )*
+//   unary          := "-" unary | power
+//   power          := primary ( "^" unary )?
+//   primary        := NUMBER | IDENT ("(" args ")")? | "(" expression ")" | HOLE
+//   args           := expression ("," expression)*
+//
+// Deliberately NOT supported (see the plan doc's "Scope decisions"):
+//   - No let/outputs blocks -- this is a pure expression grammar, same
+//     "expression AST, not a program AST" boundary as ast.js itself.
+//     Wrap the result in letIn/letChain/outputs instead.
+//   - No &&/|| -- the AST has no boolean-combinator node to lower them
+//     to. A comparison is ONLY ever valid as a ternary's condition
+//     (matching cmp()'s own documented constraint in ast.js), enforced
+//     here at PARSE time with a clear error, not deferred to the
+//     "cmp used outside select()" throw every emitter already has.
+//   - "^" lowers to call("pow", left, right), never a bin node -- bin.op
+//     is only ever "+"|"-"|"*"|"/" (see ast.js), and every emitter's
+//     `calls` table keys "pow" by name, even for targets whose own
+//     syntax has a native ^/** operator.
+const { num, v, add, sub, mul, div, neg, call, cmp, select } = require("./ast.js");
+
+const COMPARE_OPS = [">", "<", ">=", "<=", "==", "!="];
+
+// Tokenizes one template-literal string segment, appending {type, value,
+// pos} tokens to `tokens` (pos is an offset into the reconstructed full
+// source string built in expr() below, used only for error messages).
+// `label` is just which tag function's name shows up in error messages
+// -- fn.js passes "fn()" here so a lex error inside `` fn`...` `` isn't
+// misattributed to expr().
+function tokenizeSegment(str, offset, tokens, label = "expr()") {
+    let i = 0;
+    while (i < str.length) {
+        const ch = str[i];
+        const start = i;
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        // NUMBER: 123, 123.45, .5, 1e-9, 1.5E+10
+        if (/[0-9]/.test(ch) || (ch === "." && /[0-9]/.test(str[i + 1] || ""))) {
+            i++;
+            while (i < str.length && /[0-9]/.test(str[i])) i++;
+            if (str[i] === ".") {
+                i++;
+                while (i < str.length && /[0-9]/.test(str[i])) i++;
+            }
+            if (str[i] === "e" || str[i] === "E") {
+                let j = i + 1;
+                if (str[j] === "+" || str[j] === "-") j++;
+                if (/[0-9]/.test(str[j] || "")) {
+                    i = j;
+                    while (i < str.length && /[0-9]/.test(str[i])) i++;
+                }
+            }
+            tokens.push({ type: "NUMBER", value: Number(str.slice(start, i)), pos: offset + start });
+            continue;
+        }
+        // IDENT: variable names and function names, e.g. wy_wire, sqrt.
+        if (/[A-Za-z_]/.test(ch)) {
+            i++;
+            while (i < str.length && /[A-Za-z0-9_]/.test(str[i])) i++;
+            tokens.push({ type: "IDENT", value: str.slice(start, i), pos: offset + start });
+            continue;
+        }
+        // Two-character comparison operators before their one-character
+        // prefixes, so ">=" doesn't get lexed as ">" followed by "=".
+        if ((ch === ">" || ch === "<" || ch === "=" || ch === "!") && str[i + 1] === "=") {
+            tokens.push({ type: "OP", value: str.slice(i, i + 2), pos: offset + start });
+            i += 2;
+            continue;
+        }
+        // ";", "{", "}", "=" aren't used by expr()'s own grammar -- they're
+        // here for fn.js's statement syntax (let name = ...; / return
+        // {...};) to reuse this same tokenizer instead of forking it.
+        // Inert for expr(): nothing that parses successfully today could
+        // contain them anyway ("=" alone was always a lex error before,
+        // since only "==" was recognized).
+        if ("+-*/^(),?:><;{}=".includes(ch)) {
+            tokens.push({ type: "OP", value: ch, pos: offset + start });
+            i++;
+            continue;
+        }
+        throw new Error(`${label}: unexpected character "${ch}" at position ${offset + start}`);
+    }
+}
+
+// A HOLE's value is resolved to a Node right where it's produced (not
+// deferred into the parser), so a bad interpolation fails immediately
+// with a clear error rather than surfacing as a confusing parse error
+// somewhere else in the tree. `label` -- see tokenizeSegment above.
+function holeToNode(value, label = "expr()") {
+    if (typeof value === "number") return num(value);
+    if (value && typeof value === "object" && typeof value.type === "string") return value;
+    const shown = typeof value === "string" ? `"${value}"` : JSON.stringify(value);
+    throw new Error(
+        `${label}: interpolated value must be an AST node or a plain number, got ${shown} -- ` +
+        `a bare variable name doesn't need interpolation, just write it directly in the template text`,
+    );
+}
+
+class Parser {
+    // `label` -- see tokenizeSegment above; also threaded through to
+    // holeToNode so a bad interpolation inside `` fn`...` `` reports
+    // "fn():" too, not just lex/parse errors.
+    constructor(tokens, source, label = "expr()") {
+        this.tokens = tokens;
+        this.source = source;
+        this.i = 0;
+        this.label = label;
+    }
+
+    peek() {
+        return this.tokens[this.i];
+    }
+
+    next() {
+        return this.tokens[this.i++];
+    }
+
+    isOp(value) {
+        const t = this.peek();
+        return t.type === "OP" && t.value === value;
+    }
+
+    expectOp(value) {
+        if (!this.isOp(value)) this.error(`expected "${value}"`);
+        return this.next();
+    }
+
+    error(message) {
+        const t = this.peek();
+        const tokDesc = t.type === "EOF" ? "end of input" : `"${t.value}"`;
+        throw new Error(`${this.label}: ${message} -- found ${tokDesc} at position ${t.pos} in \`${this.source}\``);
+    }
+
+    parseExpression() {
+        return this.parseTernary();
+    }
+
+    // Only place a comparison is ever accepted -- matches cmp()'s own
+    // documented constraint in ast.js exactly (only valid as select()'s
+    // cond). A bare comparison with no trailing "?" is a parse error
+    // here, not deferred to the "cmp used outside select()" throw every
+    // emitter already has.
+    parseTernary() {
+        const left = this.parseAdditive();
+        const t = this.peek();
+        if (t.type === "OP" && COMPARE_OPS.includes(t.value)) {
+            const op = this.next().value;
+            const right = this.parseAdditive();
+            if (!this.isOp("?")) {
+                this.error(`comparison ("${op}") must be used as a ternary condition ("cond ${op} ... ? then : else")`);
+            }
+            this.next(); // consume "?"
+            const thenNode = this.parseExpression();
+            this.expectOp(":");
+            const elseNode = this.parseExpression();
+            return select(cmp(left, op, right), thenNode, elseNode);
+        }
+        if (this.isOp("?")) {
+            this.error(`"?" needs an explicit comparison as its condition (e.g. "a > 0 ? x : y") -- a bare value can't be a select() condition`);
+        }
+        return left;
+    }
+
+    parseAdditive() {
+        let node = this.parseMultiplicative();
+        while (this.isOp("+") || this.isOp("-")) {
+            const op = this.next().value;
+            const right = this.parseMultiplicative();
+            node = op === "+" ? add(node, right) : sub(node, right);
+        }
+        return node;
+    }
+
+    parseMultiplicative() {
+        let node = this.parseUnary();
+        while (this.isOp("*") || this.isOp("/")) {
+            const op = this.next().value;
+            const right = this.parseUnary();
+            node = op === "*" ? mul(node, right) : div(node, right);
+        }
+        return node;
+    }
+
+    // Unary minus binds LOOSER than "^" (-2^2 = -4, not 4) -- standard
+    // math convention, and the reason `power` sits below `unary` here
+    // rather than the other way around.
+    parseUnary() {
+        if (this.isOp("-")) {
+            this.next();
+            return neg(this.parseUnary());
+        }
+        if (this.isOp("+")) {
+            this.next(); // unary plus: no-op
+            return this.parseUnary();
+        }
+        return this.parsePower();
+    }
+
+    // Right-associative (2^3^2 = 2^(3^2) = 512): the exponent recurses
+    // into `unary`, not `power`, which is also what lets the exponent
+    // itself carry a leading unary minus (2^-1 = 0.5).
+    parsePower() {
+        const base = this.parsePrimary();
+        if (this.isOp("^")) {
+            this.next();
+            const exponent = this.parseUnary();
+            return call("pow", base, exponent);
+        }
+        return base;
+    }
+
+    parsePrimary() {
+        const t = this.peek();
+        if (t.type === "NUMBER") {
+            this.next();
+            return num(t.value);
+        }
+        if (t.type === "HOLE") {
+            this.next();
+            return holeToNode(t.value, this.label);
+        }
+        if (t.type === "IDENT") {
+            this.next();
+            if (this.isOp("(")) {
+                this.next();
+                const args = [];
+                if (!this.isOp(")")) {
+                    args.push(this.parseExpression());
+                    while (this.isOp(",")) {
+                        this.next();
+                        args.push(this.parseExpression());
+                    }
+                }
+                this.expectOp(")");
+                // Not validated against the 22 known Math functions here
+                // -- deferred to the same "no mapping for Math function"
+                // check every hand-built call() node already goes
+                // through in emitters/base.js, so there's only one list
+                // of known function names to keep in sync, not two.
+                return call(t.value, ...args);
+            }
+            return v(t.value);
+        }
+        if (this.isOp("(")) {
+            this.next();
+            const node = this.parseExpression();
+            this.expectOp(")");
+            return node;
+        }
+        this.error("expected a number, identifier, function call, or parenthesized expression");
+    }
+}
+
+// The tagged-template tag function itself: `` expr`a + b` `` is called by
+// JS as expr(["a + b"], ) -- with interpolations, `` expr`${x} + b` ``
+// is called as expr(["", " + b"], x). strings.length is always
+// values.length + 1. There is no "${" text syntax to lex: JS has already
+// done that splitting before this function ever runs, so a HOLE token is
+// just spliced into the token stream at each boundary, carrying the
+// already-evaluated JS value through untouched.
+function expr(strings, ...values) {
+    const tokens = [];
+    let source = "";
+    for (let i = 0; i < strings.length; i++) {
+        tokenizeSegment(strings[i], source.length, tokens);
+        source += strings[i];
+        if (i < values.length) {
+            tokens.push({ type: "HOLE", value: values[i], pos: source.length });
+            source += "${...}";
+        }
+    }
+    tokens.push({ type: "EOF", value: null, pos: source.length });
+
+    const parser = new Parser(tokens, source);
+    const node = parser.parseExpression();
+    if (parser.peek().type !== "EOF") {
+        parser.error("unexpected trailing input");
+    }
+    return node;
+}
+
+// Parser/tokenizeSegment/holeToNode are exported alongside expr itself so
+// fn.js (full function-body syntax: let/return on top of this same
+// expression grammar) can reuse this tokenizer and parsing engine
+// directly instead of forking it -- "fn's contain expr's" literally, not
+// just as a description. Nothing here is part of expr()'s own public
+// contract; treat these as internal to the expr/fn syntax family.
+module.exports = { expr, Parser, tokenizeSegment, holeToNode };

package/fn.js

@@ -0,0 +1,117 @@
+// exprforge/fn.js
+//
+// Full function-body syntax on top of expr.js's expression grammar: adds
+// `let` bindings and a `return` statement, so a whole function body
+// (let-chain + a single or multi-output result) can be authored as text
+// instead of nested letChain()/outputs() calls. Every individual
+// expression inside a `fn` template -- each let's value, the returned
+// expression(s) -- is parsed by the *same* Parser class expr.js uses,
+// via its parseExpression() entry point. fn's own grammar is a thin
+// statement-sequence wrapper around that, lowering to the real ast.js
+// builders (letChain, outputs), never a new node shape:
+//
+//   program    := stmt* returnStmt
+//   stmt       := "let" IDENT "=" expression ";"
+//   returnStmt := "return" expression ";"
+//               | "return" "{" IDENT ":" expression ("," IDENT ":" expression)* "}" ";"
+//
+// "let"/"return" are recognized contextually -- an IDENT token whose
+// value happens to be "let"/"return" at statement-start position. They
+// are NOT reserved words in expr.js's own grammar, so nothing about
+// expr()'s behavior changes: `` expr`let * 2` `` still means
+// v("let") * 2 today, same as before this file existed.
+//
+// Duplicate let-names are deliberately NOT checked here -- letChain()
+// doesn't check either (ast.js); collectLets() already does, at
+// emission time. Same "defer semantic validation to emission" precedent
+// expr.js itself follows for function/call names.
+const { letChain, outputs } = require("./ast.js");
+const { Parser, tokenizeSegment } = require("./expr.js");
+
+function isKeyword(parser, word) {
+    const t = parser.peek();
+    return t.type === "IDENT" && t.value === word;
+}
+
+function expectIdent(parser, context) {
+    const t = parser.peek();
+    if (t.type !== "IDENT") {
+        parser.error(`expected an identifier ${context}`);
+    }
+    parser.next();
+    return t.value;
+}
+
+function parseLetStatement(parser) {
+    parser.next(); // consume "let", already confirmed present by the caller
+    const name = expectIdent(parser, 'after "let"');
+    parser.expectOp("=");
+    const value = parser.parseExpression();
+    parser.expectOp(";");
+    return [name, value];
+}
+
+function parseReturnStatement(parser) {
+    parser.next(); // consume "return", already confirmed present by the caller
+    if (parser.isOp("{")) {
+        parser.next();
+        const fields = {};
+        const readField = () => {
+            const name = expectIdent(parser, 'as an output name inside "return { ... }"');
+            parser.expectOp(":");
+            fields[name] = parser.parseExpression();
+        };
+        if (!parser.isOp("}")) {
+            readField();
+            while (parser.isOp(",")) {
+                parser.next();
+                readField();
+            }
+        }
+        parser.expectOp("}");
+        parser.expectOp(";");
+        return outputs(fields);
+    }
+    const node = parser.parseExpression();
+    parser.expectOp(";");
+    return node;
+}
+
+function parseProgram(parser) {
+    const bindings = [];
+    while (isKeyword(parser, "let")) {
+        bindings.push(parseLetStatement(parser));
+    }
+    if (!isKeyword(parser, "return")) {
+        parser.error('expected "return" (a fn`...` body is zero or more "let" statements followed by a "return")');
+    }
+    const body = parseReturnStatement(parser);
+    return bindings.length > 0 ? letChain(bindings, body) : body;
+}
+
+// Same token-splicing loop expr() uses in expr.js -- see that file's
+// header comment for why there's no "${" text syntax to lex separately;
+// the only difference here is the entry point (parseProgram instead of
+// parser.parseExpression()).
+function fn(strings, ...values) {
+    const tokens = [];
+    let source = "";
+    for (let i = 0; i < strings.length; i++) {
+        tokenizeSegment(strings[i], source.length, tokens, "fn()");
+        source += strings[i];
+        if (i < values.length) {
+            tokens.push({ type: "HOLE", value: values[i], pos: source.length });
+            source += "${...}";
+        }
+    }
+    tokens.push({ type: "EOF", value: null, pos: source.length });
+
+    const parser = new Parser(tokens, source, "fn()");
+    const node = parseProgram(parser);
+    if (parser.peek().type !== "EOF") {
+        parser.error("unexpected trailing input");
+    }
+    return node;
+}
+
+module.exports = { fn };

package/index.js

@@ -1,6 +1,9 @@
 // exprforge/index.js
 const { num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, collectLets } = require("./ast.js");
 const { forComponents } = require("./util.js");
+const { expr } = require("./expr.js");
+const { fn } = require("./fn.js");
+const { evaluate } = require("./evaluate.js");
 const emitters = require("./emitters/registry.js");
 const { catmullRomAst } = require("./samples/catmull-rom.js");
 const { fibonacciAst } = require("./samples/fibonacci.js");
@@ -12,10 +15,10 @@ const { mathDemoAst } = require("./samples/math-demo.js");
  * Run every registered emitter against one AST function definition.
  * Returns { [lang]: { ext, source } }.
  */
-function emitAll(fn) {
+function emitAll(fnDef) {
     const result = {};
     for (const [lang, emitter] of Object.entries(emitters)) {
-        result[lang] = { ext: emitter.ext, source: emitter.emitFunction(fn) };
+        result[lang] = { ext: emitter.ext, source: emitter.emitFunction(fnDef) };
     }
     return result;
 }
@@ -25,6 +28,15 @@ module.exports = {
     num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, collectLets,
     // Authoring convenience — not an AST primitive, see util.js.
     forComponents,
+    // Infix syntax sugar over the builders above — same Nodes, see expr.js.
+    expr,
+    // Full function-body syntax (let/return) on top of expr's grammar —
+    // see fn.js. "fn's contain expr's": every expression inside a fn`...`
+    // template is parsed by the exact same engine expr() uses.
+    fn,
+    // A native interpreter over the AST -- evaluate(fn, args) computes a
+    // result directly in JS, no codegen/compile step. See evaluate.js.
+    evaluate,
     // Built-in example formulas — see samples/ for the source.
     catmullRomAst,
     fibonacciAst,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "exprforge",
-  "version": "0.2.1",
-  "description": "Author a math expression once as an AST, emit identical-behavior implementations in JS, TypeScript, Python, C#, Lua, QB64, C, Java, Go, Rust, Perl, PHP, Julia, Fortran, Zig, Scheme, and COBOL.",
+  "version": "0.3.0",
+  "description": "Author a math expression once as an AST (or readable infix text via expr/fn), emit identical-behavior implementations in JS, TypeScript, Python, C#, Lua, QB64, C, Java, Go, Rust, Perl, PHP, Julia, Fortran, Zig, Scheme, and COBOL, plus a native evaluator and its own readable syntax printer.",
   "main": "index.js",
   "type": "commonjs",
   "exports": {
@@ -13,6 +13,9 @@
     "index.js",
     "ast.js",
     "util.js",
+    "expr.js",
+    "fn.js",
+    "evaluate.js",
     "build.js",
     "emitters/",
     "samples/",