exprforge 0.4.0 → 0.5.1

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

package/load-expr.js

@@ -0,0 +1,112 @@
+// exprforge/load-expr.js
+//
+// Parses the .expr round-trip text format (see emitters/exprsyntax.js and
+// test/conformance.test.js's assertExprSyntaxRoundTrips) as zero or more
+// function definitions, using the exact same grammar/engine fn`...`
+// already uses (see fn.js's parseProgram), just applied repeatedly
+// instead of once. Two entry points: loadExprSource(text) parses text
+// directly (no filesystem involved -- usable anywhere source text comes
+// from, including a browser); loadExpr(path) reads a real file first and
+// delegates to it.
+//
+// Functions defined earlier are available to functions defined LATER (in
+// the same source) as inline macros -- the exact same "inline expansion,
+// not runtime calls" model loadMacro() itself uses (see macros.js's own
+// header comment), and for the same reasons: no call graph, no linking
+// problem, no runtime coupling. And, structurally, no recursion: a
+// definition is only added to this source's own local registry AFTER
+// it's been fully parsed and expanded (see the loop below), so it's
+// never resolvable through its own name while its own body is being
+// expanded, whether directly or transitively through another
+// not-yet-defined function.
+//
+// Each definition MUST have a "name(params):" signature line -- a
+// bare-Node definition with no signature has no name for a later
+// definition (or the caller) to refer to it by, so it can't usefully
+// appear alongside others.
+const fs = require("node:fs");
+const { Parser, tokenizeSegment } = require("./expr.js");
+const { parseProgram } = require("./fn.js");
+const { expandMacros, toMacro } = require("./macros.js");
+
+// Tokenizes the WHOLE file as one segment -- unlike fn()/expr() there's
+// no tagged-template interpolation to splice HOLE tokens between (a .expr
+// file is plain text, not JS source with ${...} holes), so this is
+// simpler than fn.js's own tokenizeSegment loop, not a fork of it.
+function tokenizeFile(source, label) {
+    const tokens = [];
+    tokenizeSegment(source, 0, tokens, { inComment: false }, label);
+    tokens.push({ type: "EOF", value: null, pos: source.length });
+    return tokens;
+}
+
+/**
+ * Parses `source` (plain text, not a file path -- see loadExpr below for
+ * the file-reading variant) as zero or more "name(params): let ...;
+ * return ...;" definitions back-to-back, in the same grammar fn`...`
+ * uses for one. Returns an object keyed by function name, each value the
+ * fully-expanded {name, params, body} -- ready to pass straight into
+ * evaluate()/emit()/emitMany(), with every reference to an earlier
+ * definition in the same source already inlined (see this file's own
+ * header comment). `label` identifies the source in error messages (e.g.
+ * a file path, or just "playground" for an in-browser text buffer that
+ * was never written to disk at all -- this is the one entry point here
+ * that has no `fs` dependency, so it's the one usable from a browser).
+ *
+ * Throws if any definition has no "name(params):" signature line, or if
+ * two definitions share a name.
+ *
+ * `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 defined in that
+ * session, alongside whatever's defined earlier in this same source.
+ */
+function loadExprSource(source, label = "loadExprSource()", registry = undefined) {
+    const parser = new Parser(tokenizeFile(source, label), source, label);
+
+    const fileRegistry = new Map(); // name -> {arity, fn, alreadyExpanded} -- see toMacro in macros.js
+    const defs = {};
+
+    while (parser.peek().type !== "EOF") {
+        const raw = parseProgram(parser);
+        if (!raw || typeof raw.name !== "string") {
+            throw new Error(
+                `${label}: every definition needs a "name(params):" signature line -- found one with no signature`,
+            );
+        }
+        if (defs[raw.name]) {
+            throw new Error(`${label}: duplicate function name "${raw.name}" -- names must be unique in one file`);
+        }
+
+        // Expanded against whatever's already in fileRegistry (earlier
+        // definitions in this same source) PLUS every macro/extern
+        // registered in `registry` (expandMacros merges both -- see
+        // macros.js).
+        const expanded = expandMacros(raw, fileRegistry, registry);
+        defs[raw.name] = expanded;
+
+        // Available to whatever's defined AFTER this point in the source
+        // -- never to itself (expanded above, against fileRegistry
+        // BEFORE this line adds it) or to anything defined earlier.
+        // `expanded` has nothing left to resolve (macro calls/field
+        // access are already gone), so no extraRegistry/registry needs
+        // passing here.
+        fileRegistry.set(raw.name, toMacro(expanded));
+    }
+
+    return defs;
+}
+
+/**
+ * Reads `path` from disk and parses it via loadExprSource() above -- see
+ * that function's own doc comment for the actual grammar/semantics
+ * (including `registry`); this is purely the file-reading convenience
+ * wrapper around it. Node-only (fs.readFileSync); use loadExprSource(text)
+ * directly wherever the source text comes from somewhere else (e.g. a
+ * browser text buffer, an HTTP response) instead of a real file on disk.
+ */
+function loadExpr(path, registry = undefined) {
+    return loadExprSource(fs.readFileSync(path, "utf8"), `loadExpr(${path})`, registry);
+}
+
+module.exports = { loadExpr, loadExprSource };