exprforge 0.3.0 → 0.3.1

package/README.md

@@ -355,6 +355,35 @@ deferred-to-`collectLets` behavior every hand-built `letIn`/`letChain`
 already has. A `fn` body with no `let` statements at all is just
 `return expr;`, equivalent to a bare `expr` call.
 
+### Optional signature line
+
+Writing `name`/`params` separately, next to the body, is fine for a
+one-off — but `fn` can carry them too, with a leading `name(params):`
+line:
+
+```js
+const { fn, emitAll, evaluate } = require("exprforge");
+
+const normalize2 = fn`
+    normalize2(x, y):
+    let mag = sqrt(x^2 + y^2);
+    return { nx: x / mag, ny: y / mag };
+`;
+// normalize2 is now the full {name, params, body} shape directly --
+// no wrapping object needed.
+
+evaluate(normalize2, [3, 4]);        // { nx: 0.6, ny: 0.8 }
+emitAll(normalize2).rust.source;     // ready to use immediately
+```
+
+This changes `fn`'s return type based on what you wrote, deliberately:
+no signature → a bare `Node`, exactly as above and fully backward
+compatible; a signature present → the full `{name, params, body}`
+object. `let`/`return` still can't be used as a function name — a
+signature is told apart from a statement by the same rule that tells
+`let`/`return` apart from any other identifier, so naming a function
+`let` just parses as (and fails as) a `let` statement instead.
+
 ## Printing an AST back out, and a native evaluator
 
 Two things that fall out of `fn` existing: `emitters.expr` is a real,

package/expr.js

@@ -136,6 +136,17 @@ class Parser {
         return this.tokens[this.i];
     }
 
+    // One token beyond peek() -- always safe, since `tokens` always ends
+    // with an EOF token appended once by expr()/fn() before the parser
+    // ever runs, so there's always something to look at even right at
+    // the end of input. Added for fn.js's signature-line lookahead
+    // ("IDENT followed by '(' -- is this a signature, or the start of a
+    // statement?"), which expr()'s own single-token-lookahead grammar
+    // never needed.
+    peekNext() {
+        return this.tokens[this.i + 1];
+    }
+
     next() {
         return this.tokens[this.i++];
     }

package/fn.js

@@ -10,7 +10,8 @@
 // statement-sequence wrapper around that, lowering to the real ast.js
 // builders (letChain, outputs), never a new node shape:
 //
-//   program    := stmt* returnStmt
+//   program    := signature? stmt* returnStmt
+//   signature  := IDENT "(" (IDENT ("," IDENT)*)? ")" ":"
 //   stmt       := "let" IDENT "=" expression ";"
 //   returnStmt := "return" expression ";"
 //               | "return" "{" IDENT ":" expression ("," IDENT ":" expression)* "}" ";"
@@ -24,7 +25,21 @@
 // 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.
+// expr.js itself follows for function/call names. Duplicate param names
+// go unchecked for the same reason, and because nothing else in this
+// project validates that today either -- {name, params, body} objects
+// were always hand-built plain JS before this, with no infrastructure
+// for it.
+//
+// The signature line is entirely optional, which makes fn's return type
+// conditional on what you actually wrote: no signature -> a bare Node,
+// exactly as before this was added (fully backward compatible -- every
+// fn`...` template written before this feature existed still parses
+// identically); a signature present -> the full {name, params, body}
+// shape, usable directly in emitAll()/evaluate() with no wrapping. This
+// 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 { Parser, tokenizeSegment } = require("./expr.js");
 
@@ -77,7 +92,42 @@ function parseReturnStatement(parser) {
     return node;
 }
 
+// Signature lookahead needs 2 tokens, not 1: an IDENT that isn't "let"/
+// "return" (those always start a statement instead), immediately
+// followed by "(". That's a complete, unambiguous rule given the
+// grammar above -- a fn`...` program only ever starts with a signature,
+// a "let", or a "return", so there's no fourth case this could be
+// confused with. (A malformed body missing its "let"/"return" entirely
+// -- e.g. a bare `` fn`sqrt(x)` `` someone forgot the "return" on --
+// still ends up an error either way, just reported as a missing ":"
+// rather than a missing "return"; not worth deeper lookahead to improve
+// one malformed-input error message.)
+function looksLikeSignature(parser) {
+    const t = parser.peek();
+    if (t.type !== "IDENT" || t.value === "let" || t.value === "return") return false;
+    const next = parser.peekNext();
+    return next.type === "OP" && next.value === "(";
+}
+
+function parseSignature(parser) {
+    const name = expectIdent(parser, "as the function name starting a fn`...` signature");
+    parser.expectOp("(");
+    const params = [];
+    if (!parser.isOp(")")) {
+        params.push(expectIdent(parser, "as a parameter name in a fn`...` signature"));
+        while (parser.isOp(",")) {
+            parser.next();
+            params.push(expectIdent(parser, "as a parameter name in a fn`...` signature"));
+        }
+    }
+    parser.expectOp(")");
+    parser.expectOp(":");
+    return { name, params };
+}
+
 function parseProgram(parser) {
+    const signature = looksLikeSignature(parser) ? parseSignature(parser) : null;
+
     const bindings = [];
     while (isKeyword(parser, "let")) {
         bindings.push(parseLetStatement(parser));
@@ -86,7 +136,9 @@ function parseProgram(parser) {
         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;
+    const result = bindings.length > 0 ? letChain(bindings, body) : body;
+
+    return signature ? { name: signature.name, params: signature.params, body: result } : result;
 }
 
 // Same token-splicing loop expr() uses in expr.js -- see that file's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exprforge",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",