forma-dsl 0.1.5 → 0.2.0

package/README.md

@@ -99,7 +99,7 @@ Hand-written TypeScript declarations ship with it, so the API is typed from eith
 
 **[The full reference](https://kalpak44.github.io/forma-dsl/docs/)** — every declaration,
 block, function and error, each with usage and troubleshooting. The
-**[editor](https://kalpak44.github.io/forma-dsl/)** runs the whole thing in the browser:
+**[editor](https://kalpak44.github.io/forma-dsl/editor/)** runs the whole thing in the browser:
 type, and the solid updates.
 
 ## How it works

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A declarative DSL for 3D modeling and scene composition, reusable components, and live previews.",
   "keywords": [
     "cad",

package/src/lang/builtins.js

@@ -177,10 +177,17 @@ export class Args {
   }
 
   /**
-   * Rejects anything the block did not read.
+   * Rejects anything the block did not read, and says what it would have read instead.
    *
    * A misspelled attribute is otherwise silent, and the model renders subtly wrong with
-   * nothing to point at.
+   * nothing to point at. Naming the alternatives matters as much as the refusal: the reader
+   * is often a program with no copy of the manual, and an error that says only what is wrong
+   * leaves it guessing at spellings. What it read is tracked already, so the list costs
+   * nothing to produce.
+   *
+   * A block that branches on which of two spellings it was given — `radius` against
+   * `diameter` — only reads one of them, so the list is what this call would accept and not
+   * always the whole set.
    *
    * @returns {void}
    * @throws {FormaError} If any attribute went unread.
@@ -189,7 +196,12 @@ export class Args {
     const extra = Object.keys(this.values).filter((k) => !this.used.has(k));
     if (extra.length) {
       const plural = extra.length > 1 ? 's' : '';
-      throw new FormaError(`${this.type}: unknown attribute${plural} ${quoteAll(extra)}`, this.loc);
+      const reads = [...this.used].sort((a, z) => a.localeCompare(z));
+      const instead = reads.length ? ` — ${this.type} reads ${quoteAll(reads)}` : '';
+      throw new FormaError(
+        `${this.type}: unknown attribute${plural} ${quoteAll(extra)}${instead}`,
+        this.loc,
+      );
     }
   }
 }

package/src/lang/evaluate.js

@@ -7,6 +7,12 @@ import { BLOCKS, FUNCTIONS, CONSTANTS, TYPE_NAMES, Args, quoteAll } from './buil
 import { GeometryNode } from '../core/node.js';
 import { Transform } from '../values/transform.js';
 
+/**
+ * The blocks handled before the registry is consulted, so they are missing from `BLOCKS` and
+ * would otherwise be absent from the list an unknown block is measured against.
+ */
+const SPECIAL_FORMS = ['align', 'for', 'if', 'part'];
+
 /**
  * What a body produces: geometry to hand upwards, and any scene parts declared inside it.
  *
@@ -447,7 +453,19 @@ export class Evaluator {
 
     const definition = BLOCKS[block.type];
     if (!definition) {
-      throw new FormaError(`unknown block "${block.type}"`, block.loc);
+      // The whole vocabulary, because the reader is often a program with no copy of the
+      // manual: a misspelling it cannot correct from the error costs a round trip it has no
+      // way to end. Declared components come first — they are the names this document itself
+      // introduced, and the likeliest thing a near miss was reaching for.
+      const known = [
+        ...[...this.program.components.keys()].sort((a, z) => a.localeCompare(z)),
+        ...SPECIAL_FORMS,
+        ...Object.keys(BLOCKS).sort((a, z) => a.localeCompare(z)),
+      ];
+      throw new FormaError(
+        `unknown block "${block.type}" — the blocks are ${quoteAll(known)}`,
+        block.loc,
+      );
     }
     if (block.labels.length) {
       throw new FormaError(`"${block.type}" does not take a label`, block.loc);