exprforge 0.2.0 → 0.3.0

package/emitters/zig.js

@@ -0,0 +1,126 @@
+// exprforge/emitters/zig.js
+const Emitter = require("./base.js");
+
+// Zig's reserved words plus the small set of extra identifiers this
+// emitter's own output introduces (Result, the struct-suite convention
+// below) -- same role as QB64_RESERVED in emitters/qb64.js. Zig is
+// case-sensitive, unlike QB64/Fortran, so this checks exact names.
+const ZIG_RESERVED = new Set([
+    "addrspace", "align", "allowzero", "and", "anyframe", "anytype", "asm", "async",
+    "await", "break", "callconv", "catch", "comptime", "const", "continue", "defer",
+    "else", "enum", "errdefer", "error", "export", "extern", "fn", "for", "if",
+    "inline", "noalias", "noinline", "nosuspend", "opaque", "or", "orelse", "packed",
+    "pub", "resume", "return", "linksection", "struct", "suspend", "switch", "test",
+    "threadlocal", "try", "union", "unreachable", "usingnamespace", "var", "volatile",
+    "while", "true", "false", "null", "undefined", "void", "type", "anyerror",
+    "std", "result",
+]);
+
+function checkReservedNames(names) {
+    for (const name of names) {
+        if (ZIG_RESERVED.has(name)) {
+            throw new Error(
+                `emitter for .zig: "${name}" is a reserved Zig keyword/identifier and can't be used as a ` +
+                `function/variable/parameter name -- rename it (see ZIG_RESERVED in emitters/zig.js)`,
+            );
+        }
+    }
+}
+
+function mathFn(name) {
+    return (args) => `std.math.${name}(${args.join(", ")})`;
+}
+
+function builtin(name) {
+    return ([x]) => `@${name}(${x})`;
+}
+
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+const emitter = new Emitter({
+    ext: "zig",
+    // Every literal is forced through @as(f64, ...), not left bare --
+    // confirmed against a real compiler that a bare literal reaching a
+    // comptime-eligible call (e.g. std.math.sqrt(2.0) with no runtime f64
+    // operand anywhere) gets evaluated at Zig's extended comptime_float
+    // precision instead of truncated to an actual IEEE 754 double, giving
+    // a DIFFERENT (more precise, not less) result than every other target
+    // here. @as(f64, ...) forces real double-precision truncation before
+    // any arithmetic happens, regardless of whether the surrounding
+    // expression also involves a runtime variable.
+    formatNumber: (v) => `@as(f64, ${String(v)})`,
+    calls: {
+        // Compiler builtins (map to LLVM intrinsics directly).
+        abs: builtin("abs"), exp: builtin("exp"), log: builtin("log"),
+        log2: builtin("log2"), log10: builtin("log10"),
+        floor: builtin("floor"), ceil: builtin("ceil"), round: builtin("round"), trunc: builtin("trunc"),
+        min: builtin2("min"), max: builtin2("max"),
+        // std.math functions -- not compiler builtins, but ordinary Zig
+        // stdlib functions with the expected 1/2-arg float signatures.
+        sqrt: mathFn("sqrt"), sin: mathFn("sin"), cos: mathFn("cos"), tan: mathFn("tan"),
+        asin: mathFn("asin"), acos: mathFn("acos"), atan: mathFn("atan"), atan2: mathFn("atan2"),
+        hypot: mathFn("hypot"),
+        // pow needs an explicit type argument (std.math.pow(T, x, y)) --
+        // unlike every other std.math function here, it's not purely
+        // inferred from its float arguments.
+        pow: ([x, y]) => `std.math.pow(f64, ${x}, ${y})`,
+        // std.math.sign is genuinely zero-aware (confirmed: sign(0.0) ==
+        // 0.0) -- unlike most other targets here, this doesn't need to be
+        // hand-built to get the zero case right (see Go's/Rust's sign()
+        // history in this project for what happens when a language's
+        // native sign function isn't).
+        sign: mathFn("sign"),
+    },
+    // Zig has no ?: ternary, but if/else as an EXPRESSION (not just a
+    // statement) works exactly like this project's select() -- including
+    // evaluating both branches, since there's no separate "lazy" form.
+    emitSelect: function (condNode, thenStr, elseStr) {
+        const L = this.emitExpr(condNode.left);
+        const R = this.emitExpr(condNode.right);
+        return `(if ((${L}) ${condNode.op} (${R})) ${thenStr} else ${elseStr})`;
+    },
+    formatFunction: (fn, body, letBindings = []) => {
+        checkReservedNames([fn.name, ...fn.params, ...letBindings.map((b) => b.name)]);
+        const params = fn.params.map((p) => `${p}: f64`).join(", ");
+        const lets = letBindings.map(({ name, valueStr }) => `    const ${name}: f64 = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        return `// AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+               `const std = @import("std");\n\n` +
+               `pub fn ${fn.name}(${params}) f64 {\n` +
+               letsBlock +
+               `    return ${body};\n` +
+               `}\n`;
+    },
+    // Multiple named outputs from one call: a small struct type (same idea
+    // as C's typedef struct, Rust's struct) returned by value -- Zig has
+    // no native tuple-with-names or multi-return.
+    formatSuite: (fn, outputStrs, letBindings = []) => {
+        const outputNames = Object.keys(outputStrs);
+        checkReservedNames([fn.name, ...fn.params, ...outputNames, ...letBindings.map((b) => b.name)]);
+        const resultName = `${capitalize(fn.name)}Result`;
+        const params = fn.params.map((p) => `${p}: f64`).join(", ");
+        const lets = letBindings.map(({ name, valueStr }) => `    const ${name}: f64 = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        const structFields = outputNames.map((n) => `    ${n}: f64,`).join("\n");
+        const initFields = outputNames.map((n) => `        .${n} = ${outputStrs[n]},`).join("\n");
+        return `// AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+               `const std = @import("std");\n\n` +
+               `pub const ${resultName} = struct {\n${structFields}\n};\n\n` +
+               `pub fn ${fn.name}(${params}) ${resultName} {\n` +
+               letsBlock +
+               `    return ${resultName}{\n${initFields}\n    };\n` +
+               `}\n`;
+    },
+});
+
+// builtin2 is used by the calls table above but defined after it's
+// referenced (function declarations hoist) -- kept next to builtin/mathFn
+// rather than above them so the two "2-arg compiler builtin" and "1-arg
+// compiler builtin" helpers read as a pair.
+function builtin2(name) {
+    return ([a, b]) => `@${name}(${a}, ${b})`;
+}
+
+module.exports = emitter;

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 };