exprforge 0.4.0 → 0.5.0

package/math/index.js

@@ -11,6 +11,7 @@
 // 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");
+const { loadMacro } = require("../macros.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,
@@ -110,4 +111,24 @@ function clamp(val, lo, hi) {
     return select(cmp(val, "<", lo), lo, select(cmp(val, ">", hi), hi, val));
 }
 
+// Also registered as macros (see macros.js/issue #21 ask 3), usable
+// directly inside fn`...`/expr`...` template TEXT, not just from
+// JS-authoring -- e.g. `fn`rodrigues(...): let b = cross3(ax, ay, az,
+// bx, by, bz); let bLen = sqrt(b.rx^2 + b.ry^2 + b.rz^2); ...``. Every
+// one of these already has exactly the signature loadMacro() wants
+// ((...argNodes) => Node | {field: Node}) with no wrapping needed --
+// this IS the "safe, inline-expanded, built from existing primitives"
+// tier's worked example, not a separate mechanism layered on top of it.
+// `clamp` is deliberately excluded: it's a 3-argument (val, lo, hi) helper
+// whose own doc comment already flags `val` as re-evaluated three times
+// if it's not cheap -- fine for JS-authoring callers who control that,
+// but not offered as a macro name here since a fn`...` author has no
+// equivalent "pass an already-let-bound reference" convention to reach
+// for if they trip over the same cost.
+loadMacro("dot3", dot3);
+loadMacro("len3", len3);
+loadMacro("cross3", cross3);
+loadMacro("normalize3", normalize3);
+loadMacro("safeDiv", safeDiv);
+
 module.exports = { EPS, safeDiv, dot3, len3, cross3, normalize3, clamp };

package/package.json

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

package/primitives.js

@@ -0,0 +1,24 @@
+// exprforge/primitives.js
+//
+// The fixed, non-extensible set of built-in Math primitives (see ast.js's
+// call() node, evaluate.js's CALLS table, and every emitters/<lang>.js's
+// own `calls` table -- all three already have to agree on this same set
+// of names, per evaluate.js's own header comment) plus each one's exact,
+// required argument count.
+//
+// A standalone module with no dependencies of its own, specifically so
+// evaluate.js, emitters/base.js, and macros.js can all require it without
+// risking a cycle (macros.js already can't require evaluate.js back,
+// since evaluate.js requires macros.js -- see macros.js's own comment on
+// this). Update this table too if a new built-in primitive is ever
+// added -- same "two lists have to stay in sync" precedent evaluate.js's
+// own header comment already documents for CALLS vs. every emitter's
+// `calls` table; this is a third.
+const PRIMITIVE_ARITY = {
+    sqrt: 1, abs: 1, sin: 1, cos: 1, tan: 1, asin: 1, acos: 1, atan: 1,
+    log: 1, log2: 1, log10: 1, exp: 1, floor: 1, ceil: 1, round: 1,
+    trunc: 1, sign: 1,
+    pow: 2, atan2: 2, min: 2, max: 2, hypot: 2,
+};
+
+module.exports = { PRIMITIVE_ARITY };

package/samples/macro-demo.js

@@ -0,0 +1,56 @@
+// exprforge/samples/macro-demo.js
+// Not a worked example -- a conformance-test fixture for macros.js,
+// same role samples/kitchen-sink.js plays for the core Math primitives
+// and samples/math-demo.js plays for exprforge/math: exists purely so
+// test/conformance.test.js can prove macro-expanded code agrees across
+// every real target, not just evaluate() (which is blind to codegen --
+// see the two macros registered below, both AST-fn-def-shaped
+// (fn`...`-based via loadMacro), NOT plain-JS-function macros like
+// math/index.js's (already covered by mathDemo). That distinction is
+// the whole point of this file: an AST-fn-def macro's own "let"
+// statements get automatically alpha-renamed on every call (see
+// macros.js's toMacro/substituteAndRename), and a gensym'd name that
+// isn't a valid identifier in every target once slipped past every
+// check here and only broke Fortran (a leading underscore -- see
+// substituteAndRename's own comment). hypotSq is called TWICE in one
+// function specifically to prove two different calls' gensym'd names
+// don't collide with each other either.
+const { v, letIn, call, field, add } = require("../ast.js");
+const { fn } = require("../fn.js");
+const { loadMacro } = require("../macros.js");
+
+// Single-value macro with its own internal "let" -- the gensym path.
+loadMacro("hypotSq", fn(["hypotSq(a, b): let sq = a * a + b * b; return sq;"]));
+
+// Multi-output macro whose outputs() is wrapped in its own let-chain --
+// the exact shape that was originally misdetected as a single value
+// before that got fixed (see toMacro's own comment in macros.js).
+// Field access (.rx/.ry) on its result is exercised below.
+loadMacro(
+    "rotate90",
+    fn([
+        `rotate90(x, y):
+  let rx = 0 - y;
+  let ry = x;
+  return { rx, ry };
+`,
+    ]),
+);
+
+// "byy", not "by": BY is a reserved COBOL keyword -- same reason
+// math-demo.js's MATH_DEMO_PARAMS uses it, see that file's own comment.
+const macroDemoAst = {
+    name: "macroDemo",
+    params: ["ax", "ay", "bx", "byy"],
+    body: letIn(
+        "hSq1",
+        call("hypotSq", v("ax"), v("ay")),
+        letIn(
+            "hSq2",
+            call("hypotSq", v("bx"), v("byy")),
+            letIn("r", call("rotate90", v("ax"), v("ay")), add(v("hSq1"), v("hSq2"), field(v("r"), "rx"), field(v("r"), "ry"))),
+        ),
+    ),
+};
+
+module.exports = { macroDemoAst };