exprforge 0.1.0 → 0.2.1

package/emitters/perl.js

@@ -0,0 +1,95 @@
+// exprforge/emitters/perl.js
+const Emitter = require("./base.js");
+
+function fn1(name) {
+    return ([x]) => `${name}(${x})`;
+}
+
+function posix1(name) {
+    return ([x]) => `POSIX::${name}(${x})`;
+}
+
+// Every scalar variable reference in Perl needs a leading `$` -- unlike
+// every other emitter here, base.js's default "var" case (bare
+// `node.name`) is wrong for every single reference, not just declarations.
+// Emitter is a real class (see base.js), so this overrides just the one
+// case and defers to the base class for everything else, instead of
+// needing a new config hook shared by every other emitter.
+class PerlEmitter extends Emitter {
+    emitExpr(node) {
+        if (node.type === "var") return `$${node.name}`;
+        return super.emitExpr(node);
+    }
+}
+
+const emitter = new PerlEmitter({
+    ext: "pl",
+    // Perl accepts JS-style numeric literal syntax directly, including
+    // exponential notation ("1e-9") -- no suffix or conversion needed.
+    formatNumber: (v) => String(v),
+    calls: {
+        // Core builtins -- no module needed.
+        sqrt: fn1("sqrt"), abs: fn1("abs"), sin: fn1("sin"), cos: fn1("cos"),
+        exp: fn1("exp"), log: fn1("log"), atan2: ([a, b]) => `atan2(${a}, ${b})`,
+        pow: ([x, y]) => `(${x} ** ${y})`,
+        // Everything else Perl core doesn't have is in the POSIX module --
+        // called fully-qualified (POSIX::name) rather than imported, so
+        // there's no import list to keep in sync with this table and no
+        // risk of a POSIX symbol shadowing a core builtin of the same name.
+        tan: posix1("tan"), asin: posix1("asin"), acos: posix1("acos"), atan: posix1("atan"),
+        log10: posix1("log10"), floor: posix1("floor"), ceil: posix1("ceil"),
+        round: posix1("round"), trunc: posix1("trunc"),
+        hypot: ([a, b]) => `POSIX::hypot(${a}, ${b})`,
+        // No log2 anywhere in core or POSIX -- derive it.
+        log2: ([x]) => `(log(${x}) / log(2))`,
+        // List::Util, same fully-qualified convention as POSIX above.
+        min: ([a, b]) => `List::Util::min(${a}, ${b})`,
+        max: ([a, b]) => `List::Util::max(${a}, ${b})`,
+        // No sign() anywhere in core, POSIX, or List::Util -- build it
+        // directly. Zero-aware by construction (see Go's/Rust's sign()
+        // history in this project for what happens when it isn't).
+        sign: ([x]) => `(${x} > 0 ? 1.0 : (${x} < 0 ? -1.0 : 0.0))`,
+    },
+    // Perl's ?: is exactly base.js's default ternary -- no override needed.
+    formatFunction: (fn, body, letBindings = []) => {
+        const params = fn.params.length ? `    my (${fn.params.map((p) => `$${p}`).join(", ")}) = @_;\n` : "";
+        const lets = letBindings.map(({ name, valueStr }) => `    my $${name} = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        return `# AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+               `use strict;\n` +
+               `use warnings;\n` +
+               `use POSIX ();\n` +
+               `use List::Util ();\n\n` +
+               `sub ${fn.name} {\n` +
+               params +
+               letsBlock +
+               `    return ${body};\n` +
+               `}\n\n` +
+               `1;\n`;
+    },
+    // Multiple named outputs from one call: a plain hash ref (`{ rx => ...,
+    // ry => ... }`), Perl's lightest-weight named-record idiom -- no
+    // package/class needed just to carry a few doubles back to the caller.
+    formatSuite: (fn, outputStrs, letBindings = []) => {
+        const params = fn.params.length ? `    my (${fn.params.map((p) => `$${p}`).join(", ")}) = @_;\n` : "";
+        const lets = letBindings.map(({ name, valueStr }) => `    my $${name} = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        const outputNames = Object.keys(outputStrs);
+        const fields = outputNames.map((n) => `        ${n} => ${outputStrs[n]},`).join("\n");
+        return `# AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+               `use strict;\n` +
+               `use warnings;\n` +
+               `use POSIX ();\n` +
+               `use List::Util ();\n\n` +
+               `sub ${fn.name} {\n` +
+               params +
+               letsBlock +
+               `    return {\n` +
+               fields + "\n" +
+               `    };\n` +
+               `}\n\n` +
+               `1;\n`;
+    },
+});
+
+module.exports = emitter;

package/emitters/php.js

@@ -0,0 +1,79 @@
+// exprforge/emitters/php.js
+const Emitter = require("./base.js");
+
+function fn1(name) {
+    return ([x]) => `${name}(${x})`;
+}
+
+function fn2(name) {
+    return ([a, b]) => `${name}(${a}, ${b})`;
+}
+
+// Every variable reference in PHP needs a leading `$` -- unlike every other
+// emitter here, base.js's default "var" case (bare `node.name`) is wrong
+// for every single reference, not just declarations. Same fix as Perl's
+// emitter: override just the one case, defer to the base class otherwise.
+class PhpEmitter extends Emitter {
+    emitExpr(node) {
+        if (node.type === "var") return `$${node.name}`;
+        return super.emitExpr(node);
+    }
+}
+
+const emitter = new PhpEmitter({
+    ext: "php",
+    // PHP accepts JS-style numeric literal syntax directly, including
+    // exponential notation ("1e-9") -- no suffix or conversion needed.
+    formatNumber: (v) => String(v),
+    calls: {
+        sqrt: fn1("sqrt"), abs: fn1("abs"), sin: fn1("sin"), cos: fn1("cos"), tan: fn1("tan"),
+        asin: fn1("asin"), acos: fn1("acos"), atan: fn1("atan"), atan2: fn2("atan2"),
+        log: fn1("log"), log10: fn1("log10"), exp: fn1("exp"), pow: fn2("pow"),
+        floor: fn1("floor"), ceil: fn1("ceil"), round: fn1("round"),
+        min: fn2("min"), max: fn2("max"), hypot: fn2("hypot"),
+        // log() takes an optional base argument -- covers log2 without a
+        // separate function (PHP has no log2() of its own).
+        log2: ([x]) => `log(${x}, 2)`,
+        // No trunc() anywhere in PHP core. floor for non-negatives, ceil
+        // for negatives -- avoids an (int) cast, which would silently
+        // misbehave outside PHP's platform integer range.
+        trunc: ([x]) => `(${x} >= 0 ? floor(${x}) : ceil(${x}))`,
+        // No sign() either -- build it directly. Zero-aware by construction
+        // (see Go's/Rust's sign() history in this project for what happens
+        // when it isn't).
+        sign: ([x]) => `(${x} > 0 ? 1.0 : (${x} < 0 ? -1.0 : 0.0))`,
+    },
+    // PHP's ?: is exactly base.js's default ternary -- no override needed.
+    formatFunction: (fn, body, letBindings = []) => {
+        const params = fn.params.map((p) => `$${p}`).join(", ");
+        const lets = letBindings.map(({ name, valueStr }) => `    $${name} = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        return `<?php\n` +
+               `// AUTO-GENERATED by ExprForge -- do not hand-edit.\n\n` +
+               `function ${fn.name}(${params}) {\n` +
+               letsBlock +
+               `    return ${body};\n` +
+               `}\n`;
+    },
+    // Multiple named outputs from one call: a plain associative array
+    // (`['rx' => ..., 'ry' => ...]`), PHP's lightest-weight named-record
+    // idiom -- no class needed just to carry a few doubles back to the
+    // caller.
+    formatSuite: (fn, outputStrs, letBindings = []) => {
+        const params = fn.params.map((p) => `$${p}`).join(", ");
+        const lets = letBindings.map(({ name, valueStr }) => `    $${name} = ${valueStr};`).join("\n");
+        const letsBlock = lets ? lets + "\n" : "";
+        const outputNames = Object.keys(outputStrs);
+        const fields = outputNames.map((n) => `        '${n}' => ${outputStrs[n]},`).join("\n");
+        return `<?php\n` +
+               `// AUTO-GENERATED by ExprForge -- do not hand-edit.\n\n` +
+               `function ${fn.name}(${params}) {\n` +
+               letsBlock +
+               `    return [\n` +
+               fields + "\n" +
+               `    ];\n` +
+               `}\n`;
+    },
+});
+
+module.exports = emitter;

package/emitters/registry.js

@@ -12,4 +12,11 @@ module.exports = {
     csharp: require("./csharp.js"),
     python: require("./python.js"),
     lua: require("./lua.js"),
+    perl: require("./perl.js"),
+    php: require("./php.js"),
+    julia: require("./julia.js"),
+    fortran: require("./fortran.js"),
+    zig: require("./zig.js"),
+    scheme: require("./scheme.js"),
+    cobol: require("./cobol.js"),
 };

package/emitters/scheme.js

@@ -0,0 +1,154 @@
+// exprforge/emitters/scheme.js
+//
+// Targets Guile (R7RS-ish Scheme) specifically -- see
+// test/conformance.test.js for the exact `guile3.0` invocation this is
+// verified against. Prefix notation throughout: this project's "bin" node
+// is the one thing every OTHER emitter can handle via base.js's default
+// infix `(${L} ${op} ${R})` -- Scheme is the one target here where even
+// `+`/`-`/`*`/`/` themselves need to move into the operator position, so
+// this overrides emitExpr's "bin" case specifically (Emitter is a real
+// class -- see base.js -- so this is a small subclass, not a new shared
+// hook every other emitter would have to ignore).
+const Emitter = require("./base.js");
+
+// Guile special forms plus the procedure names this emitter's own calls
+// table depends on -- same role as QB64_RESERVED in emitters/qb64.js.
+// Scheme technically allows shadowing a procedure name like `sqrt` with a
+// local binding, but doing so would break every OTHER call in the same
+// scope that still expects it to mean the real one, so it's guarded here
+// same as a true syntactic keyword.
+const SCHEME_RESERVED = new Set([
+    "define", "lambda", "let", "let*", "letrec", "letrec*", "if", "cond", "case",
+    "and", "or", "not", "begin", "set!", "quote", "quasiquote", "unquote", "do",
+    "delay", "values", "call-with-values", "else", "define-record-type",
+    "sqrt", "abs", "sin", "cos", "tan", "asin", "acos", "atan", "exp", "log",
+    "expt", "floor", "ceiling", "round", "truncate", "min", "max",
+]);
+
+function checkReservedNames(names) {
+    for (const name of names) {
+        if (SCHEME_RESERVED.has(name)) {
+            throw new Error(
+                `emitter for .scm: "${name}" is a reserved Scheme special form/procedure name and can't be used ` +
+                `as a function/variable/parameter name -- rename it (see SCHEME_RESERVED in emitters/scheme.js)`,
+            );
+        }
+    }
+}
+
+class SchemeEmitter extends Emitter {
+    emitExpr(node) {
+        if (node.type === "bin") {
+            // ast.js's op set (+ - * /) is already valid Scheme procedure-
+            // position syntax verbatim -- no translation table needed,
+            // just moving it from infix to prefix position.
+            return `(${node.op} ${this.emitExpr(node.left)} ${this.emitExpr(node.right)})`;
+        }
+        return super.emitExpr(node);
+    }
+}
+
+function fn1(name) {
+    return ([x]) => `(${name} ${x})`;
+}
+
+function fn2(name) {
+    return ([a, b]) => `(${name} ${a} ${b})`;
+}
+
+const emitter = new SchemeEmitter({
+    ext: "scm",
+    // Guile accepts JS-style numeric literal syntax directly, including
+    // exponential notation ("1e-9") -- no conversion needed for the digits
+    // themselves. But a bare integer literal like "2" is EXACT in Scheme's
+    // reader syntax, and exact arithmetic that never happens to touch an
+    // inexact (float) operand stays exact -- confirmed a real compiler
+    // prints (/ 1 3) as the fraction "1/3", not "0.333...". Every literal
+    // this project emits is meant to behave as an IEEE double like every
+    // other target, so any literal with neither a decimal point nor an
+    // exponent marker gets ".0" appended, forcing inexactness by literal
+    // syntax alone -- not relying on some other operand in the same
+    // expression happening to already be inexact.
+    formatNumber: (v) => {
+        const s = String(v);
+        return /[.e]/i.test(s) ? s : `${s}.0`;
+    },
+    calls: {
+        sqrt: fn1("sqrt"), abs: fn1("abs"), sin: fn1("sin"), cos: fn1("cos"), tan: fn1("tan"),
+        asin: fn1("asin"), acos: fn1("acos"), atan: fn1("atan"), exp: fn1("exp"), log: fn1("log"),
+        // expt is Scheme's exponentiation procedure -- there's no infix **.
+        pow: fn2("expt"),
+        // R7RS's 2-argument atan IS atan2 -- no separate name for it.
+        atan2: fn2("atan"),
+        // No log2/log10 procedure in R7RS or Guile's core -- derive both.
+        log2: ([x]) => `(/ (log ${x}) (log 2.0))`,
+        log10: ([x]) => `(/ (log ${x}) (log 10.0))`,
+        floor: fn1("floor"), ceil: fn1("ceiling"),
+        // Guile's round is round-half-to-even (banker's rounding), not the
+        // round-half-away-from-zero most other targets here use -- same
+        // already-documented, already-avoided-in-tests divergence as
+        // Lua's/Julia's round(), not a new one (see
+        // test/conformance.test.js's kitchen-sink comment).
+        round: fn1("round"),
+        trunc: fn1("truncate"),
+        min: fn2("min"), max: fn2("max"),
+        // No hypot procedure -- derive it directly.
+        hypot: ([a, b]) => `(sqrt (+ (* ${a} ${a}) (* ${b} ${b})))`,
+        // No sign procedure either -- build it directly. Zero-aware by
+        // construction (see Go's/Rust's sign() history in this project for
+        // what happens when it isn't).
+        sign: ([x]) => `(if (> ${x} 0.0) 1.0 (if (< ${x} 0.0) -1.0 0.0))`,
+    },
+    // Scheme's `if` already IS an expression (no separate statement form),
+    // so this is the most direct emitSelect override of any target here --
+    // just prefix notation for the comparison, same as every "bin" node.
+    // "!=" needs `(not (= ...))`: R7RS has no single-procedure not-equal.
+    emitSelect: function (condNode, thenStr, elseStr) {
+        const L = this.emitExpr(condNode.left);
+        const R = this.emitExpr(condNode.right);
+        const condExpr =
+            condNode.op === "!=" ? `(not (= ${L} ${R}))` : `(${condNode.op === "==" ? "=" : condNode.op} ${L} ${R})`;
+        return `(if ${condExpr} ${thenStr} ${elseStr})`;
+    },
+    formatFunction: (fn, body, letBindings = []) => {
+        checkReservedNames([fn.name, ...fn.params, ...letBindings.map((b) => b.name)]);
+        const params = fn.params.join(" ");
+        // let* (not let): each binding can see every earlier one, matching
+        // the dependency order collectLets already produced -- exactly
+        // what our flat, ordered bindings list needs, no extra nesting.
+        if (letBindings.length === 0) {
+            return `;; AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+                   `(define (${fn.name} ${params})\n` +
+                   `  ${body})\n`;
+        }
+        const lets = letBindings.map(({ name, valueStr }) => `         (${name} ${valueStr})`).join("\n");
+        return `;; AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+               `(define (${fn.name} ${params})\n` +
+               `  (let* (${lets.trimStart()})\n` +
+               `    ${body}))\n`;
+    },
+    // Multiple named outputs from one call: Scheme's native (values ...)
+    // -- same idea as Lua's native multiple return, positional rather than
+    // named, so a leading comment documents field order (matching Lua's
+    // convention here) since Scheme's values have no names at the call
+    // site.
+    formatSuite: (fn, outputStrs, letBindings = []) => {
+        const outputNames = Object.keys(outputStrs);
+        checkReservedNames([fn.name, ...fn.params, ...outputNames, ...letBindings.map((b) => b.name)]);
+        const params = fn.params.join(" ");
+        const returnExpr = `(values ${outputNames.map((n) => outputStrs[n]).join(" ")})`;
+        const header =
+            `;; AUTO-GENERATED by ExprForge -- do not hand-edit.\n` +
+            `;; Returns (values ${outputNames.join(" ")}).\n`;
+        if (letBindings.length === 0) {
+            return header + `(define (${fn.name} ${params})\n` + `  ${returnExpr})\n`;
+        }
+        const lets = letBindings.map(({ name, valueStr }) => `         (${name} ${valueStr})`).join("\n");
+        return header +
+               `(define (${fn.name} ${params})\n` +
+               `  (let* (${lets.trimStart()})\n` +
+               `    ${returnExpr}))\n`;
+    },
+});
+
+module.exports = emitter;

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/index.js

@@ -1,11 +1,12 @@
 // exprforge/index.js
-const { num, v, bin, call, add, mul, sub, div, neg, letIn, cmp, select, outputs, collectLets } = require("./ast.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 emitters = require("./emitters/registry.js");
 const { catmullRomAst } = require("./samples/catmull-rom.js");
 const { fibonacciAst } = require("./samples/fibonacci.js");
 const { splineFrameAsts } = require("./samples/spline-frame.js");
 const { kitchenSinkAst } = require("./samples/kitchen-sink.js");
+const { mathDemoAst } = require("./samples/math-demo.js");
 
 /**
  * Run every registered emitter against one AST function definition.
@@ -21,7 +22,7 @@ function emitAll(fn) {
 
 module.exports = {
     // AST builders — use these to define your own formulas.
-    num, v, bin, call, add, mul, sub, div, neg, letIn, cmp, select, outputs, collectLets,
+    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,
     // Built-in example formulas — see samples/ for the source.
@@ -31,11 +32,15 @@ module.exports = {
     // Not a worked example -- a conformance-test fixture that calls every
     // supported Math function once. See samples/kitchen-sink.js.
     kitchenSinkAst,
+    // Also not a worked example -- a conformance-test fixture for
+    // require("exprforge/math"). See samples/math-demo.js.
+    mathDemoAst,
     samples: {
         catmullRom: catmullRomAst,
         fibonacci: fibonacciAst,
         splineFrame: splineFrameAsts,
         kitchenSink: kitchenSinkAst,
+        mathDemo: mathDemoAst,
     },
     // Per-language emitter instances, keyed by name (js, qb64, c, java, go, rust).
     emitters,

package/math/index.js

@@ -0,0 +1,113 @@
+// exprforge/math/index.js
+// Standard math utilities — see docs/v0.2.0-math-utilities.md for the
+// design doc this implements. This module is level 1: pure compositions of
+// the level-0 AST primitives (ast.js), built to save every consumer from
+// re-deriving the same safe-math/vector patterns samples/spline-frame.js
+// used to hand-roll locally (dot3/len3/safeDiv/EPS there predate this file
+// and motivated it). No new emitter logic — emitAll handles these
+// transparently, same as any other AST the caller builds by hand.
+//
+// require("exprforge/math") is a separate export path from require("exprforge")
+// itself (see package.json's "exports" map) — additive, not merged into the
+// core barrel.
+const { num, v, call, add, mul, sub, div, letIn, cmp, select } = require("../ast.js");
+
+// Shared epsilon for all near-zero guards below. Exposed so callers can
+// reuse it in their own cmp() calls for consistency with safeDiv/normalize3,
+// same convention as samples/spline-frame.js's local EPS.
+const EPS = num(0.000001);
+
+// Guard against division by zero: numerator/denominatorExpr when
+// |denominatorExpr| > EPS, else fallback. Per select()'s doc comment in
+// ast.js, both branches of a select are always evaluated on every target —
+// so this does NOT guard the division directly (div(numerator,
+// denominatorExpr) would still be reached with a near-zero denominator on
+// any target that can't short-circuit, e.g. QB64). Instead the denominator
+// is clamped to a safe, always-nonzero value by its own select first,
+// mirroring the local safeDiv in samples/spline-frame.js.
+//
+// denominatorExpr is referenced twice in the resulting tree (once for the
+// |.| > EPS check, once in the clamped-denominator select) — cheap if it's
+// a var reference or a simple expression, but if it's an expensive
+// subexpression (e.g. a len3() call), pass an already-letIn-bound v(name)
+// instead of the raw expression to avoid computing it twice per emitted
+// target. normalize3() below does exactly that internally.
+function safeDiv(numerator, denominatorExpr, fallback) {
+    const isSafe = cmp(call("abs", denominatorExpr), ">", EPS);
+    const safeDenom = select(isSafe, denominatorExpr, num(1));
+    return select(isSafe, div(numerator, safeDenom), fallback);
+}
+
+// 3-D dot product: ax*bx + ay*by + az*bz.
+function dot3(ax, ay, az, bx, by, bz) {
+    return add(mul(ax, bx), mul(ay, by), mul(az, bz));
+}
+
+// 3-D Euclidean length: sqrt(x² + y² + z²). Emits a sqrt intrinsic (see
+// README's "Supported Math functions").
+function len3(x, y, z) {
+    return call("sqrt", dot3(x, y, z, x, y, z));
+}
+
+// 3-D cross product. Returns a plain JS object { x, y, z } of AST nodes,
+// NOT an AST node itself — a deliberate ergonomic choice so callers can
+// destructure and name each component in their own letIn chain, rather
+// than exprforge picking the names for them.
+function cross3(ax, ay, az, bx, by, bz) {
+    return {
+        x: sub(mul(ay, bz), mul(az, by)),
+        y: sub(mul(az, bx), mul(ax, bz)),
+        z: sub(mul(ax, by), mul(ay, bx)),
+    };
+}
+
+// Monotonic counter behind normalize3's internal let-binding names — see
+// the comment inside normalize3 for why it needs one at all. Global (not
+// per-call-site) is deliberately overkill: it only has to avoid colliding
+// with another normalize3() binding inside the same function body, and a
+// process-wide counter trivially guarantees that regardless of how many
+// times normalize3 is called across however many functions.
+//
+// The name itself starts with a letter, not "__" -- confirmed against a
+// real Fortran compiler ("Invalid character in name") that a leading
+// underscore isn't a valid identifier start there, unlike JS/Python/etc.
+// This is an internal implementation detail (never part of any documented
+// return value or public name), so there's nothing for a leading-"__"
+// convention to usefully signal here that a portable identifier can't
+// signal just as well.
+let normalizeGensymCounter = 0;
+
+// Safe-normalize a 3-D vector. Returns { x, y, z } (same shape as cross3).
+// Falls back to (fx, fy, fz) — default (0, 1, 0) — when the vector's length
+// is at or below EPS.
+//
+// Per the spec's recommendation, this computes len3(x, y, z) ONCE and
+// shares it across all three divisions (one EPS check, one sqrt), instead
+// of calling safeDiv three times against three independent len3() calls.
+// The mechanism: the length is let-bound inside the `x` field's own tree,
+// and `y`/`z` just reference that bound name bare. collectLets (ast.js)
+// hoists a let found anywhere in a function body to one flat, ordered list
+// regardless of which sibling subtree it was found in — see
+// test/ast.test.js's "collectLets hoists a let nested inside one output
+// field's own value" for the exact behavior this relies on. The gensym'd
+// name avoids a "duplicate let binding name" throw if normalize3 is called
+// more than once inside one function (e.g. normalizing two vectors).
+function normalize3(x, y, z, fx = num(0), fy = num(1), fz = num(0)) {
+    const lenName = `efMathNrmLen${normalizeGensymCounter++}`;
+    return {
+        x: letIn(lenName, len3(x, y, z), safeDiv(x, v(lenName), fx)),
+        y: safeDiv(y, v(lenName), fy),
+        z: safeDiv(z, v(lenName), fz),
+    };
+}
+
+// Clamps val to [lo, hi]. Expressed as nested select/cmp — no runtime
+// intrinsic required, matching cmp/select's existing usage elsewhere (see
+// samples/spline-frame.js). val is referenced three times in the resulting
+// tree; pass a var reference (or an already-let-bound one) if it's not
+// already cheap to re-evaluate.
+function clamp(val, lo, hi) {
+    return select(cmp(val, "<", lo), lo, select(cmp(val, ">", hi), hi, val));
+}
+
+module.exports = { EPS, safeDiv, dot3, len3, cross3, normalize3, clamp };

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "exprforge",
-  "version": "0.1.0",
-  "description": "Author a math expression once as an AST, emit identical-behavior implementations in JS, TypeScript, Python, C#, Lua, QB64, C, Java, Go, and Rust.",
+  "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.",
   "main": "index.js",
   "type": "commonjs",
+  "exports": {
+    ".": "./index.js",
+    "./math": "./math/index.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "index.js",
     "ast.js",
     "util.js",
     "build.js",
     "emitters/",
-    "samples/"
+    "samples/",
+    "math/"
   ],
   "scripts": {
     "build": "node build.js",