exprforge 0.3.1 → 0.5.0

package/emitters/exprsyntax.js

@@ -63,17 +63,48 @@ const emitter = new ExprSyntaxEmitter({
     // 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.
+    //
+    // ALWAYS includes the "name(params):" signature line -- every other
+    // emitter's formatFunction includes the full declaration per
+    // base.js's own documented contract ("Full source text for one
+    // function, including any language-specific signature/type/wrapper
+    // syntax"); this was the one target that didn't, dropping fn.name/
+    // fn.params on the floor entirely. That wasn't a deliberate
+    // minimalism choice, it was a leftover from before fn`...`'s
+    // optional signature line (see fn.js) existed at all -- without it,
+    // reparsing this emitter's own output via fn() could only ever
+    // recover a bare Node, never a runnable {name, params, body}, unlike
+    // literally every other target's output being immediately usable.
+    // Body lines (every let, the return) are indented 2 spaces deeper
+    // than the signature line itself -- a Python-esque pretty-print
+    // convention, not something the parser requires (whitespace is
+    // insignificant to fn's grammar; see expr.js's tokenizer). Applied
+    // here, not just in hand-written docs/examples, so every printed
+    // AST comes out reading the same way automatically.
     formatFunction: (fn, bodyStr, letBindings = []) => {
-        const lines = letLines(letBindings);
-        lines.push(`return ${bodyStr};`);
-        return lines.join("\n") + "\n";
+        const body = [...letLines(letBindings), `return ${bodyStr};`].map((line) => `  ${line}`);
+        return [`${fn.name}(${fn.params.join(", ")}):`, ...body].join("\n") + "\n";
     },
+    // Each output field gets its own line (4 spaces -- one level deeper
+    // than "return {" itself, which sits at the usual 2), rather than
+    // cramming every field onto one line -- found the gap by comparing
+    // this against a hand-formatted multi-output example and noticing
+    // the printer didn't follow its own convention once a suite had
+    // more than a couple of fields (a real, wide, 5-output formula made
+    // this one very long line instead of something readable).
     formatSuite: (fn, outputStrs, letBindings = []) => {
-        const lines = letLines(letBindings);
-        const fields = Object.entries(outputStrs)
-            .map(([name, valueStr]) => `${name}: ${valueStr}`)
-            .join(", ");
-        lines.push(`return { ${fields} };`);
+        const entries = Object.entries(outputStrs);
+        const fieldLines = entries.map(([name, valueStr], i) => {
+            const comma = i < entries.length - 1 ? "," : "";
+            return `    ${name}: ${valueStr}${comma}`;
+        });
+        const lines = [
+            `${fn.name}(${fn.params.join(", ")}):`,
+            ...letLines(letBindings).map((line) => `  ${line}`),
+            "  return {",
+            ...fieldLines,
+            "  };",
+        ];
         return lines.join("\n") + "\n";
     },
 });

package/emitters/registry.js

@@ -1,7 +1,7 @@
 // exprforge/emitters/registry.js
 // Add a new language: write emitters/<lang>.js exporting an Emitter instance,
 // then add one line here. Nothing else in the project needs to change.
-module.exports = {
+const emitters = {
     js: require("./js.js"),
     ts: require("./typescript.js"),
     qb64: require("./qb64.js"),
@@ -21,3 +21,14 @@ module.exports = {
     cobol: require("./cobol.js"),
     expr: require("./exprsyntax.js"),
 };
+
+// Each emitter learns its own registered key here, once -- base.js's
+// emitExpr uses this.lang to resolve an extern (see loadExtern() in
+// macros.js), and this is the one place that already knows the
+// name<->instance mapping, so it's the only file that needs to change
+// for this instead of every emitters/<lang>.js.
+for (const [lang, emitter] of Object.entries(emitters)) {
+    emitter.lang = lang;
+}
+
+module.exports = emitters;

package/evaluate.js

@@ -9,11 +9,12 @@
 // 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
+// Every primitive 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
+// primitives 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 { collectLets, checkUnboundVars } = require("./ast.js");
+const { expandMacros, resolveExternForEvaluate, withContext } = require("./macros.js");
 
 const CMP_OPS = {
     ">": (a, b) => a > b,
@@ -43,7 +44,12 @@ const CALLS = {
 // 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) {
+// `registry` -- see macros.js's createRegistry()/index.js's
+// createSession() -- resolves an extern against the right session's own
+// registrations, defaulting to the process-wide one when not passed
+// (evaluate() below never passes `undefined` on purpose either way, see
+// there).
+function evalNode(node, env, registry) {
     switch (node.type) {
         case "num":
             return node.value;
@@ -55,18 +61,25 @@ function evalNode(node, env) {
         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));
+            return op(evalNode(node.left, env, registry), evalNode(node.right, env, registry));
         }
         case "call": {
-            const impl = CALLS[node.name];
+            const impl = CALLS[node.name] || resolveExternForEvaluate(node.name, registry);
             if (!impl) throw new Error(`evaluate(): no mapping for Math function "${node.name}"`);
-            return impl(...node.args.map((a) => evalNode(a, env)));
+            const args = node.args.map((a) => evalNode(a, env, registry));
+            // Only an extern's own `evaluate` entry is caller-supplied
+            // code that could have a bug worth attributing -- a built-in
+            // primitive (impl === CALLS[node.name]) is exprforge's own
+            // Math.* wrapper, not worth wrapping.
+            return CALLS[node.name]
+                ? impl(...args)
+                : withContext(`evaluate(): while running extern "${node.name}"`, () => impl(...args));
         }
         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);
+            const cond = cmpFn(evalNode(node.cond.left, env, registry), evalNode(node.cond.right, env, registry));
+            return evalNode(cond ? node.then : node.else, env, registry);
         }
         default:
             throw new Error(
@@ -81,8 +94,28 @@ function evalNode(node, env) {
 // 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) {
+// back from every other target. `registry` (see macros.js's
+// createRegistry()) defaults to the process-wide default when omitted --
+// pass a session's own (see index.js's createSession()) to resolve
+// macros/externs against that session instead; ordinary callers never
+// need to pass it.
+function evaluate(fn, args, registry = undefined) {
+    // Resolves every macro call and field() access into plain arithmetic
+    // FIRST -- checkUnboundVars/collectLets/evalNode below know nothing
+    // about either (see macros.js's own header comment); an extern's
+    // call node is left alone here, and resolved above in evalNode's own
+    // "call" case instead.
+    fn = expandMacros(fn, null, registry);
+    // Checked once, up front, exhaustively -- NOT relying on evalNode's
+    // own runtime "unbound variable" throw below to happen to hit it,
+    // which it might never do for a given call: a bad reference inside
+    // a select() branch these particular args don't take would silently
+    // never surface that way. See checkUnboundVars's own comment in
+    // ast.js. evalNode's runtime check stays in place too, as a cheap
+    // internal backstop -- it should be unreachable now that this runs
+    // first, same "check early, keep the deeper check anyway" precedent
+    // emitters/cobol.js already follows for its own reserved-name checks.
+    checkUnboundVars(fn);
     if (args.length !== fn.params.length) {
         throw new Error(`evaluate(): ${fn.name} expects ${fn.params.length} argument(s), got ${args.length}`);
     }
@@ -93,17 +126,17 @@ function evaluate(fn, args) {
 
     const { bindings, body } = collectLets(fn.body);
     for (const { name, node } of bindings) {
-        env[name] = evalNode(node, env);
+        env[name] = evalNode(node, env, registry);
     }
 
     if (body.type === "outputs") {
         const result = {};
         for (const [name, node] of Object.entries(body.fields)) {
-            result[name] = evalNode(node, env);
+            result[name] = evalNode(node, env, registry);
         }
         return result;
     }
-    return evalNode(body, env);
+    return evalNode(body, env, registry);
 }
 
 module.exports = { evaluate };

package/expr.js

@@ -23,7 +23,8 @@
 //   additive       := multiplicative ( ("+"|"-") multiplicative )*
 //   multiplicative := unary ( ("*"|"/") unary )*
 //   unary          := "-" unary | power
-//   power          := primary ( "^" unary )?
+//   power          := postfix ( "^" unary )?
+//   postfix        := primary ( "." IDENT )*
 //   primary        := NUMBER | IDENT ("(" args ")")? | "(" expression ")" | HOLE
 //   args           := expression ("," expression)*
 //
@@ -40,7 +41,7 @@
 //     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 { num, v, add, sub, mul, div, neg, call, cmp, select, field } = require("./ast.js");
 
 const COMPARE_OPS = [">", "<", ">=", "<=", "==", "!="];
 
@@ -50,8 +51,28 @@ const COMPARE_OPS = [">", "<", ">=", "<=", "==", "!="];
 // `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()") {
+//
+// `state.inComment` carries "# comment" status ACROSS segments -- these
+// are tagged template literals, so a source like
+// `` expr`a + b # comment ${x} more` `` tokenizes segment "a + b #
+// comment " and segment " more" separately, with a HOLE for `x` spliced
+// between them by expr()/fn() below. A comment open at the end of one
+// segment has to stay open into the next, or "more" would wrongly
+// become real tokens again. One `state` object is created once per
+// top-level expr()/fn() call and threaded through every call here --
+// never reset per segment.
+function tokenizeSegment(str, offset, tokens, state = { inComment: false }, label = "expr()") {
     let i = 0;
+    if (state.inComment) {
+        const nl = str.indexOf("\n");
+        if (nl === -1) {
+            // The whole segment is still inside the comment -- nothing
+            // to tokenize, and still in-comment for whatever's next.
+            return;
+        }
+        i = nl + 1;
+        state.inComment = false;
+    }
     while (i < str.length) {
         const ch = str[i];
         const start = i;
@@ -59,6 +80,20 @@ function tokenizeSegment(str, offset, tokens, label = "expr()") {
             i++;
             continue;
         }
+        // "#" comments run to the next newline (or off the end of this
+        // segment, in which case state.inComment stays set for the next
+        // one -- see above). Not part of the OP set below: this
+        // produces no token at all, the same category as whitespace,
+        // not an operator.
+        if (ch === "#") {
+            const nl = str.indexOf("\n", i);
+            if (nl === -1) {
+                state.inComment = true;
+                return;
+            }
+            i = nl + 1;
+            continue;
+        }
         // NUMBER: 123, 123.45, .5, 1e-9, 1.5E+10
         if (/[0-9]/.test(ch) || (ch === "." && /[0-9]/.test(str[i + 1] || ""))) {
             i++;
@@ -97,8 +132,12 @@ function tokenizeSegment(str, offset, tokens, label = "expr()") {
         // {...};) 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)) {
+        // since only "==" was recognized). "." is new too -- postfix field
+        // access (b.rx), see parsePostfix() below; harmless to add here
+        // since a bare "." was always a lex error before (the NUMBER
+        // branch above already claims every "." that's followed by a
+        // digit, e.g. ".5", so there's no ambiguity with number literals).
+        if ("+-*/^(),?:><;{}=.".includes(ch)) {
             tokens.push({ type: "OP", value: ch, pos: offset + start });
             i++;
             continue;
@@ -121,6 +160,21 @@ function holeToNode(value, label = "expr()") {
     );
 }
 
+// How deep parseExpression() can recurse into itself -- nested
+// parens/function-call args/ternary branches, the only places genuine
+// nesting comes from (the additive/multiplicative/unary/power/postfix
+// precedence chain always runs once per primary regardless of how deep
+// the tree ends up, so it isn't what this is bounding). 100 is
+// deliberately generous, not tight: the deepest real formula in this
+// project (Cardano's cubic, samples/ via the playground's own example)
+// doesn't come close to double digits. It exists so a pathologically
+// nested input -- "((((((...))))))" or "f(f(f(f(...))))" thousands
+// deep, plausible if this ever parses genuinely untrusted, unbounded-
+// size text -- fails with one clear, controlled error instead of a raw
+// "Maximum call stack size exceeded" RangeError once the real JS stack
+// (which this sits comfortably below at 100) actually gives out.
+const MAX_EXPRESSION_DEPTH = 100;
+
 class Parser {
     // `label` -- see tokenizeSegment above; also threaded through to
     // holeToNode so a bad interpolation inside `` fn`...` `` reports
@@ -130,6 +184,7 @@ class Parser {
         this.source = source;
         this.i = 0;
         this.label = label;
+        this.depth = 0;
     }
 
     peek() {
@@ -167,8 +222,22 @@ class Parser {
         throw new Error(`${this.label}: ${message} -- found ${tokDesc} at position ${t.pos} in \`${this.source}\``);
     }
 
+    // Every recursive re-entry (a parenthesized group, a function-call
+    // argument, a ternary's then/else branch) goes through here, so
+    // tracking depth at this ONE point -- not at every precedence-level
+    // method, which would overcount a wide-but-shallow expression like
+    // "a + b + c + ..." as if it were deeply nested -- correctly bounds
+    // genuine nesting without rejecting a merely long one.
     parseExpression() {
-        return this.parseTernary();
+        this.depth++;
+        if (this.depth > MAX_EXPRESSION_DEPTH) {
+            this.error(`expression nested too deeply (max ${MAX_EXPRESSION_DEPTH} levels of parens/calls/ternaries)`);
+        }
+        try {
+            return this.parseTernary();
+        } finally {
+            this.depth--;
+        }
     }
 
     // Only place a comparison is ever accepted -- matches cmp()'s own
@@ -236,7 +305,7 @@ class Parser {
     // 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();
+        const base = this.parsePostfix();
         if (this.isOp("^")) {
             this.next();
             const exponent = this.parseUnary();
@@ -245,6 +314,26 @@ class Parser {
         return base;
     }
 
+    // Postfix "." field access (b.rx, chainable: a.b.c) -- binds tighter
+    // than "^", same as function-call parens already do inside
+    // parsePrimary. Accepted generally here, for any primary, same "defer
+    // semantic validation" precedent call() already follows for unknown
+    // function names -- whether `target` actually resolves to something
+    // with that field is checked later, by macros.js's expandMacros(),
+    // which is the only thing that ever consumes a "field" node (see its
+    // and ast.js's own comments).
+    parsePostfix() {
+        let node = this.parsePrimary();
+        while (this.isOp(".")) {
+            this.next();
+            const t = this.peek();
+            if (t.type !== "IDENT") this.error('expected a field name after "."');
+            this.next();
+            node = field(node, t.value);
+        }
+        return node;
+    }
+
     parsePrimary() {
         const t = this.peek();
         if (t.type === "NUMBER") {
@@ -296,13 +385,22 @@ class Parser {
 // already-evaluated JS value through untouched.
 function expr(strings, ...values) {
     const tokens = [];
+    const state = { inComment: false };
     let source = "";
     for (let i = 0; i < strings.length; i++) {
-        tokenizeSegment(strings[i], source.length, tokens);
+        tokenizeSegment(strings[i], source.length, tokens, state);
         source += strings[i];
         if (i < values.length) {
-            tokens.push({ type: "HOLE", value: values[i], pos: source.length });
             source += "${...}";
+            // A value interpolated inside an open "#" comment is
+            // silently dropped -- never reaches holeToNode, so it's
+            // never validated, even if it would otherwise be an
+            // invalid interpolation (a string, undefined, ...). This is
+            // deliberate: the whole point of a comment is that its
+            // contents don't matter.
+            if (!state.inComment) {
+                tokens.push({ type: "HOLE", value: values[i], pos: source.length });
+            }
         }
     }
     tokens.push({ type: "EOF", value: null, pos: source.length });

package/fn.js

@@ -14,7 +14,13 @@
 //   signature  := IDENT "(" (IDENT ("," IDENT)*)? ")" ":"
 //   stmt       := "let" IDENT "=" expression ";"
 //   returnStmt := "return" expression ";"
-//               | "return" "{" IDENT ":" expression ("," IDENT ":" expression)* "}" ";"
+//               | "return" "{" field ("," field)* "}" ";"
+//   field      := IDENT (":" expression)?
+//
+// A field with no ":" is shorthand for "name: name" (return { rx, ry, rz };
+// means return { rx: rx, ry: ry, rz: rz };) -- same convention JS object
+// literals use for a property whose value is a same-named variable, and
+// fields can freely mix shorthand and explicit form in one return.
 //
 // "let"/"return" are recognized contextually -- an IDENT token whose
 // value happens to be "let"/"return" at statement-start position. They
@@ -40,7 +46,7 @@
 // was a deliberate API choice, not an oversight -- see the GitHub issue
 // this shipped from for the alternative considered (a separate,
 // always-full-definition tag) and why this was preferred.
-const { letChain, outputs } = require("./ast.js");
+const { letChain, outputs, v } = require("./ast.js");
 const { Parser, tokenizeSegment } = require("./expr.js");
 
 function isKeyword(parser, word) {
@@ -73,7 +79,15 @@ function parseReturnStatement(parser) {
         const fields = {};
         const readField = () => {
             const name = expectIdent(parser, 'as an output name inside "return { ... }"');
-            parser.expectOp(":");
+            // No ":" -- shorthand for "name: name" (return { rx, ry, rz };
+            // means return { rx: rx, ry: ry, rz: rz };), matching JS object
+            // literal shorthand. Explicit ":" still works, and either form
+            // can appear anywhere in the same field list.
+            if (!parser.isOp(":")) {
+                fields[name] = v(name);
+                return;
+            }
+            parser.next(); // consume ":"
             fields[name] = parser.parseExpression();
         };
         if (!parser.isOp("}")) {
@@ -147,13 +161,19 @@ function parseProgram(parser) {
 // parser.parseExpression()).
 function fn(strings, ...values) {
     const tokens = [];
+    const state = { inComment: false };
     let source = "";
     for (let i = 0; i < strings.length; i++) {
-        tokenizeSegment(strings[i], source.length, tokens, "fn()");
+        tokenizeSegment(strings[i], source.length, tokens, state, "fn()");
         source += strings[i];
         if (i < values.length) {
-            tokens.push({ type: "HOLE", value: values[i], pos: source.length });
             source += "${...}";
+            // See expr.js's tokenizeSegment/expr() for why this is
+            // silently dropped rather than pushed -- same rule, same
+            // reasoning, shared state object.
+            if (!state.inComment) {
+                tokens.push({ type: "HOLE", value: values[i], pos: source.length });
+            }
         }
     }
     tokens.push({ type: "EOF", value: null, pos: source.length });
@@ -166,4 +186,9 @@ function fn(strings, ...values) {
     return node;
 }
 
-module.exports = { fn };
+// parseProgram is also exported for load-expr.js: loading a .expr file
+// means parsing zero or more of these back-to-back over one shared token
+// stream (see load-expr.js's own header comment), which needs the same
+// "signature? stmt* returnStmt" grammar this file already implements --
+// reused directly, not forked.
+module.exports = { fn, parseProgram };

package/index.js

@@ -1,31 +1,126 @@
 // exprforge/index.js
-const { num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, collectLets } = require("./ast.js");
+const { num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, field, collectLets, checkUnboundVars } = require("./ast.js");
 const { forComponents } = require("./util.js");
 const { expr } = require("./expr.js");
 const { fn } = require("./fn.js");
 const { evaluate } = require("./evaluate.js");
+const { loadMacro, loadExtern, expandMacros, createRegistry } = require("./macros.js");
+const { loadExpr, loadExprSource } = require("./load-expr.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");
+const { macroDemoAst } = require("./samples/macro-demo.js");
 
 /**
- * Run every registered emitter against one AST function definition.
- * Returns { [lang]: { ext, source } }.
+ * Run ONE emitter against one AST function definition. Returns
+ * { ext, source }. Throws if `lang` isn't a registered emitter name, or if
+ * that emitter itself throws for this fn (an unmapped Math function, a
+ * reserved-name collision, ...) -- the caller picked exactly this one
+ * target, so there's no "other languages" for a per-language error to be
+ * isolated from; let it propagate. Prefer this over emitAll (deprecated,
+ * below) when you only need one or a few targets -- it doesn't pay for
+ * every registered emitter to get one.
+ *
+ * `registry` (see macros.js's createRegistry()) defaults to the
+ * process-wide default when omitted -- pass a session's own (see
+ * createSession() below) to resolve macros/externs registered in that
+ * session instead; ordinary callers never need to pass it directly.
  */
-function emitAll(fnDef) {
+function emit(fnDef, lang, registry = undefined) {
+    const emitter = emitters[lang];
+    if (!emitter) {
+        throw new Error(
+            `emit(): no emitter registered for language "${lang}" -- known languages: ${Object.keys(emitters).sort().join(", ")}`,
+        );
+    }
+    return { ext: emitter.ext, source: emitter.emitFunction(fnDef, registry) };
+}
+
+/**
+ * Run several emitters against one AST function definition, each in
+ * isolation from the others: one language's emitter throwing shows up as
+ * { source: null, error } for THAT language only, alongside every other
+ * requested language's real { source, error: null } result -- a single
+ * bad target (e.g. a parameter name COBOL's reserved-word check rejects)
+ * no longer takes the whole batch down with it. `langs` defaults to every
+ * registered language; pass an explicit array to avoid running (and
+ * paying for) emitters you don't need.
+ *
+ * `registry` -- see emit()'s own doc comment above -- same meaning here,
+ * applied to every language in `langs`.
+ */
+function emitMany(fnDef, langs = Object.keys(emitters), registry = undefined) {
     const result = {};
-    for (const [lang, emitter] of Object.entries(emitters)) {
-        result[lang] = { ext: emitter.ext, source: emitter.emitFunction(fnDef) };
+    for (const lang of langs) {
+        const emitter = emitters[lang];
+        if (!emitter) {
+            result[lang] = { ext: null, source: null, error: `no emitter registered for language "${lang}"` };
+            continue;
+        }
+        try {
+            result[lang] = { ext: emitter.ext, source: emitter.emitFunction(fnDef, registry), error: null };
+        } catch (e) {
+            result[lang] = { ext: emitter.ext, source: null, error: e instanceof Error ? e.message : String(e) };
+        }
     }
     return result;
 }
 
+/**
+ * @deprecated Runs every registered emitter unconditionally, whether you
+ * need all of them or not -- prefer emit(fnDef, lang) for one target, or
+ * emitMany(fnDef, langs) for an explicit subset (or emitMany(fnDef) with
+ * no `langs` for the same "every language" behavior this has always had).
+ * Kept working, not scheduled for removal -- existing callers reading
+ * result[lang].ext/.source see no change; the only behavior change is the
+ * bug fix this shares with emitMany: a single emitter throwing used to
+ * abort the whole batch (nothing for ANY language came back), and now
+ * surfaces as { source: null, error } for that language alone.
+ */
+function emitAll(fnDef) {
+    return emitMany(fnDef);
+}
+
+/**
+ * Creates an isolated "session": its own private macro/extern registry
+ * (see macros.js's createRegistry()), plus every macro/extern/evaluate/
+ * emit-shaped function bound to use it instead of the process-wide
+ * default registry loadMacro/loadExtern/evaluate/emit/emitMany use when
+ * called bare. Purely additive -- loadMacro/loadExtern/etc. above are
+ * completely unaffected by a session's existence, and a session's own
+ * registrations are invisible to them and to every OTHER session,
+ * garbage-collected normally once the session object itself is no
+ * longer referenced. No removal API: rebuild a fresh session (via a new
+ * createSession() call) instead of trying to unregister one macro/extern
+ * out of an existing one -- see the design discussion this came out of
+ * (github.com/theraccoonbear/exprforge/issues/21).
+ *
+ * Useful whenever a program legitimately needs more than one independent
+ * "namespace" of macros/externs at once -- e.g. a multi-tenant service
+ * evaluating math defined by different untrusted users, where one
+ * user's loadMacro("helper", ...) must never resolve inside another
+ * user's expression just because they picked the same name.
+ */
+function createSession() {
+    const registry = createRegistry();
+    return {
+        loadMacro: (name, def) => loadMacro(name, def, registry),
+        loadExtern: (name, def) => loadExtern(name, def, registry),
+        expandMacros: (fnOrNode, extraRegistry = null) => expandMacros(fnOrNode, extraRegistry, registry),
+        evaluate: (fn, args) => evaluate(fn, args, registry),
+        emit: (fnDef, lang) => emit(fnDef, lang, registry),
+        emitMany: (fnDef, langs = Object.keys(emitters)) => emitMany(fnDef, langs, registry),
+        loadExpr: (path) => loadExpr(path, registry),
+        loadExprSource: (source, label = "loadExprSource()") => loadExprSource(source, label, registry),
+    };
+}
+
 module.exports = {
     // AST builders — use these to define your own formulas.
-    num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, collectLets,
+    num, v, bin, call, add, mul, sub, div, neg, letIn, letChain, cmp, select, outputs, field, collectLets, checkUnboundVars,
     // Authoring convenience — not an AST primitive, see util.js.
     forComponents,
     // Infix syntax sugar over the builders above — same Nodes, see expr.js.
@@ -37,6 +132,28 @@ module.exports = {
     // A native interpreter over the AST -- evaluate(fn, args) computes a
     // result directly in JS, no codegen/compile step. See evaluate.js.
     evaluate,
+    // Register a macro: a name usable inside fn`...`/expr`...` text
+    // beyond the built-in primitives, inline-expanded at build time,
+    // never emitted as a real call. See macros.js's own header comment.
+    loadMacro,
+    // Register an extern: same usable-by-name mechanism, but a real
+    // per-target native call instead -- caller-owned risk, ExprForge
+    // can't verify it. See macros.js's own header comment.
+    loadExtern,
+    // Runs the same macro/field-access expansion evaluate() and every
+    // emitter already run internally -- exposed for callers who want the
+    // expanded tree itself (e.g. to inspect or re-emit it without
+    // re-running expansion). Ordinary callers never need this.
+    expandMacros,
+    // Parses a .expr file (the exprsyntax emitter's own round-trip
+    // format) into its function definitions, letting later functions in
+    // the file reference earlier ones as inline macros. See load-expr.js.
+    loadExpr,
+    // Same parser, given source text directly instead of a file path --
+    // no filesystem involved, so this is the one usable from a browser
+    // (a text editor buffer, an HTTP response, ...). loadExpr(path) is
+    // now just this plus a readFileSync.
+    loadExprSource,
     // Built-in example formulas — see samples/ for the source.
     catmullRomAst,
     fibonacciAst,
@@ -47,15 +164,31 @@ module.exports = {
     // Also not a worked example -- a conformance-test fixture for
     // require("exprforge/math"). See samples/math-demo.js.
     mathDemoAst,
+    // Also not a worked example -- a conformance-test fixture for
+    // macros.js's AST-fn-def macro tier specifically (loadMacro(name,
+    // fn`...`), not the plain-JS-function tier mathDemoAst already
+    // covers). See samples/macro-demo.js.
+    macroDemoAst,
     samples: {
         catmullRom: catmullRomAst,
         fibonacci: fibonacciAst,
         splineFrame: splineFrameAsts,
         kitchenSink: kitchenSinkAst,
         mathDemo: mathDemoAst,
+        macroDemo: macroDemoAst,
     },
     // Per-language emitter instances, keyed by name (js, qb64, c, java, go, rust).
     emitters,
-    // Convenience: run every emitter at once.
+    // One target, explicit -- see this function's own doc comment above.
+    emit,
+    // Several targets at once, each isolated from the others' failures.
+    emitMany,
+    // Deprecated: every target at once, no way to ask for fewer. Prefer
+    // emit()/emitMany() above -- kept working, not removed.
     emitAll,
+    // Creates an isolated session: its own private macro/extern registry,
+    // plus loadMacro/loadExtern/evaluate/emit/emitMany/loadExpr/
+    // loadExprSource bound to use it. See this function's own doc
+    // comment above.
+    createSession,
 };