forma-dsl 0.1.1 → 0.1.2

package/package.json

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

package/src/core/context.js

@@ -233,7 +233,7 @@ export class EvaluationContext {
           case 'union': return Concrete.union(parts);
           case 'difference': return Concrete.difference(parts);
           case 'intersection': return Concrete.intersection(parts);
-          default: throw new Error(`unknown boolean operation ${props.op}`);
+          default: throw new Error(`unknown boolean operation ${JSON.stringify(props.op)}`);
         }
       }
 

package/src/core/digest.js

@@ -18,18 +18,34 @@ function rotl(x, r) {
   return (x << r) | (x >>> (32 - r));
 }
 
+/**
+ * Wraps a number to a signed 32-bit integer, the way the algorithm's additions are defined.
+ *
+ * `Math.imul(x, 1)` rather than `x | 0`: the two are identical — both coerce through
+ * ToInt32 — but this one says *wrap*, which is what MurmurHash means here. `Math.trunc` is
+ * emphatically not a substitute: it drops the fraction without wrapping, so `2**31 + 5`
+ * stays positive instead of becoming negative, and every digest downstream changes.
+ *
+ * @param {number} x The value to wrap.
+ * @returns {number} The low 32 bits, signed.
+ */
+function int32(x) {
+  return Math.imul(x, 1);
+}
+
 /**
  * Multiplies two 32-bit words, keeping the low bits.
  *
  * `Math.imul`, not `*`: a 32-bit product above 2^53 loses its low bits to the double, and
- * those low bits are most of the mixing.
+ * those low bits are most of the mixing. It is also already defined to return a signed
+ * 32-bit result, so nothing here has to wrap it again.
  *
  * @param {number} a The left operand.
  * @param {number} b The right operand.
  * @returns {number} The low 32 bits of the product.
  */
 function mul(a, b) {
-  return Math.imul(a, b) | 0;
+  return Math.imul(a, b);
 }
 
 /**
@@ -90,16 +106,16 @@ export function digestBytes(bytes) {
     let k4 = view.getUint32(o + 12, true);
 
     k1 = mul(k1, C1); k1 = rotl(k1, 15); k1 = mul(k1, C2); h1 ^= k1;
-    h1 = rotl(h1, 19); h1 = (h1 + h2) | 0; h1 = (mul(h1, 5) + 0x561ccd1b) | 0;
+    h1 = rotl(h1, 19); h1 = int32(h1 + h2); h1 = int32(mul(h1, 5) + 0x561ccd1b);
 
     k2 = mul(k2, C2); k2 = rotl(k2, 16); k2 = mul(k2, C3); h2 ^= k2;
-    h2 = rotl(h2, 17); h2 = (h2 + h3) | 0; h2 = (mul(h2, 5) + 0x0bcaa747) | 0;
+    h2 = rotl(h2, 17); h2 = int32(h2 + h3); h2 = int32(mul(h2, 5) + 0x0bcaa747);
 
     k3 = mul(k3, C3); k3 = rotl(k3, 17); k3 = mul(k3, C4); h3 ^= k3;
-    h3 = rotl(h3, 15); h3 = (h3 + h4) | 0; h3 = (mul(h3, 5) + 0x96cd1c35) | 0;
+    h3 = rotl(h3, 15); h3 = int32(h3 + h4); h3 = int32(mul(h3, 5) + 0x96cd1c35);
 
     k4 = mul(k4, C4); k4 = rotl(k4, 18); k4 = mul(k4, C1); h4 ^= k4;
-    h4 = rotl(h4, 13); h4 = (h4 + h1) | 0; h4 = (mul(h4, 5) + 0x32ac3b17) | 0;
+    h4 = rotl(h4, 13); h4 = int32(h4 + h1); h4 = int32(mul(h4, 5) + 0x32ac3b17);
   }
 
   // The trailing bytes that did not fill a 16-byte block, folded in a word at a time.
@@ -115,11 +131,11 @@ export function digestBytes(bytes) {
   if (rem >= 13) { let x = mul(k[3], C4); x = rotl(x, 18); h4 ^= mul(x, C1); }
 
   h1 ^= len; h2 ^= len; h3 ^= len; h4 ^= len;
-  h1 = (h1 + h2) | 0; h1 = (h1 + h3) | 0; h1 = (h1 + h4) | 0;
-  h2 = (h2 + h1) | 0; h3 = (h3 + h1) | 0; h4 = (h4 + h1) | 0;
+  h1 = int32(h1 + h2); h1 = int32(h1 + h3); h1 = int32(h1 + h4);
+  h2 = int32(h2 + h1); h3 = int32(h3 + h1); h4 = int32(h4 + h1);
   h1 = fmix(h1); h2 = fmix(h2); h3 = fmix(h3); h4 = fmix(h4);
-  h1 = (h1 + h2) | 0; h1 = (h1 + h3) | 0; h1 = (h1 + h4) | 0;
-  h2 = (h2 + h1) | 0; h3 = (h3 + h1) | 0; h4 = (h4 + h1) | 0;
+  h1 = int32(h1 + h2); h1 = int32(h1 + h3); h1 = int32(h1 + h4);
+  h2 = int32(h2 + h1); h3 = int32(h3 + h1); h4 = int32(h4 + h1);
 
   return [h1 >>> 0, h2 >>> 0, h3 >>> 0, h4 >>> 0]
     .map((w) => w.toString(16).padStart(8, '0'))
@@ -170,7 +186,7 @@ export class DigestWriter {
    */
   int(value) {
     const bytes = new Uint8Array(4);
-    new DataView(bytes.buffer).setInt32(0, value | 0, true);
+    new DataView(bytes.buffer).setInt32(0, int32(value), true);
     this.#push(bytes);
     return this;
   }

package/src/core/node.js

@@ -3,6 +3,23 @@
 import { DigestWriter } from './digest.js';
 import { Transform } from '../values/transform.js';
 
+/**
+ * Orders strings by UTF-16 code unit, which is what a bare `sort()` does.
+ *
+ * Written out rather than left implicit — and deliberately *not* `localeCompare`, which is
+ * what a linter will suggest. Collation is locale-dependent, and this ordering feeds the
+ * digest: two machines with different locales would have to agree, or the cache would miss
+ * across them and a model would re-solve from scratch on someone else's laptop.
+ *
+ * @param {string} a The left string.
+ * @param {string} b The right string.
+ * @returns {number} Negative, zero or positive, as `sort` wants.
+ */
+function byCodeUnit(a, b) {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+}
+
 /**
  * Canonically encodes an attribute value into the digest.
  *
@@ -29,7 +46,7 @@ function writeValue(writer, value) {
   } else if (value instanceof Transform) {
     writer.string('t').numbers(value.toArray());
   } else {
-    const keys = Object.keys(value).sort();
+    const keys = Object.keys(value).sort(byCodeUnit);
     writer.string('o').int(keys.length);
     for (const key of keys) {
       writer.string(key);
@@ -113,7 +130,7 @@ export class GeometryNode {
       throw new TypeError(`cannot combine 2D and 3D geometry in a ${op}`);
     }
     const ordered = op === 'union'
-      ? [...live].sort((a, b) => a.subtreeSize - b.subtreeSize || a.digest.localeCompare(b.digest))
+      ? [...live].sort((a, b) => a.subtreeSize - b.subtreeSize || byCodeUnit(a.digest, b.digest))
       : live;
     return new GeometryNode(dim, 'boolean', { op }, ordered);
   }

package/src/lang/ast.js

@@ -100,13 +100,13 @@ export {};
  */
 
 /**
- * A `condition ? then : otherwise`.
+ * A `condition ? consequent : alternate`.
  *
  * @typedef {object} ConditionalExpression
  * @property {'conditional'} kind Discriminant.
  * @property {Expression} condition What decides.
- * @property {Expression} then The value when truthy.
- * @property {Expression} otherwise The value when not.
+ * @property {Expression} consequent The value when truthy.
+ * @property {Expression} alternate The value when not.
  * @property {SourceLocation} [loc] Where it was written.
  */
 
@@ -176,8 +176,8 @@ export {};
  * @typedef {object} IfBlock
  * @property {'if'} kind Discriminant.
  * @property {Expression} condition What decides.
- * @property {Body} then The branch taken when truthy.
- * @property {Body | null} otherwise The branch taken otherwise, if there is one.
+ * @property {Body} consequent The branch taken when truthy.
+ * @property {Body | null} alternate The branch taken otherwise, if there is one.
  * @property {SourceLocation} loc Where the `if` was.
  */
 

package/src/lang/evaluate.js

@@ -18,6 +18,9 @@ import { Transform } from '../values/transform.js';
  * @property {ScenePart[]} parts The scene parts declared below here.
  */
 
+/** Which index `.x`, `.y` and `.z` stand for when read off a list. */
+const AXES = { x: 0, y: 1, z: 2 };
+
 /** A lexical scope, chained to its parent. */
 class Scope {
   /**
@@ -36,13 +39,8 @@ class Scope {
    * @returns {unknown} Its value, or undefined if nothing binds it.
    */
   lookup(name) {
-    /** @type {Scope | null} */
-    let scope = this;
-    while (scope) {
-      if (scope.values.has(name)) return scope.values.get(name);
-      scope = scope.parent;
-    }
-    return undefined;
+    if (this.values.has(name)) return this.values.get(name);
+    return this.parent ? this.parent.lookup(name) : undefined;
   }
 
   /**
@@ -52,13 +50,8 @@ class Scope {
    * @returns {boolean} Whether anything binds it.
    */
   has(name) {
-    /** @type {Scope | null} */
-    let scope = this;
-    while (scope) {
-      if (scope.values.has(name)) return true;
-      scope = scope.parent;
-    }
-    return false;
+    if (this.values.has(name)) return true;
+    return this.parent ? this.parent.has(name) : false;
   }
 
   /**
@@ -303,8 +296,8 @@ export class Evaluator {
 
       case 'conditional':
         return truthy(this.expression(node.condition, scope))
-          ? this.expression(node.then, scope)
-          : this.expression(node.otherwise, scope);
+          ? this.expression(node.consequent, scope)
+          : this.expression(node.alternate, scope);
 
       case 'call': return this.call(node, scope);
 
@@ -329,8 +322,7 @@ export class Evaluator {
     if (object === null || object === undefined) {
       throw new FormaError(`cannot read "${node.property}" of nothing`, node.loc);
     }
-    const axis = { x: 0, y: 1, z: 2 }[node.property];
-    if (Array.isArray(object) && axis !== undefined) return object[axis];
+    if (Array.isArray(object) && node.property in AXES) return object[AXES[node.property]];
     if (!(node.property in object)) {
       throw new FormaError(`no attribute "${node.property}"`, node.loc);
     }
@@ -442,7 +434,7 @@ export class Evaluator {
 
     if (block.kind === 'for') return this.forBlock(block, scope);
     if (block.kind === 'if') {
-      const taken = truthy(this.expression(block.condition, scope)) ? block.then : block.otherwise;
+      const taken = truthy(this.expression(block.condition, scope)) ? block.consequent : block.alternate;
       return taken ? this.body(taken, scope) : { nodes: [], parts: [] };
     }
 
@@ -581,7 +573,7 @@ export class Evaluator {
       // An unlabelled part still needs a name to show in the viewer; its line is the one
       // thing guaranteed to differ between two of them.
       name: block.labels.length
-        ? String(this.expression(block.labels[0], scope))
+        ? formatValue(this.expression(block.labels[0], scope))
         : `part_${block.loc.line}`,
       color: args.string('color', '#b8c4d0'),
       opacity: args.number('opacity', 1),
@@ -760,7 +752,27 @@ function truthy(value) {
 function formatValue(value) {
   if (Array.isArray(value)) return `[${value.map(formatValue).join(', ')}]`;
   if (value === null || value === undefined) return '';
-  return String(value);
+  // An object reaching here is almost always a mistake in the model, so it is shown the way
+  // it was written rather than as JavaScript's `[object Object]`, which says nothing about
+  // which object went wrong.
+  if (typeof value === 'object') return `{${Object.entries(value).map(formatEntry).join(', ')}}`;
+  if (typeof value === 'string') return value;
+  // A forma expression yields a number, a string, a bool, null, a list or an object, so by
+  // here it is a number or a bool. Spelling that out keeps the coercion off `unknown`, where
+  // it could silently produce "[object Object]" for something this does not handle.
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return '';
+}
+
+/**
+ * Renders one object entry. Separate from {@link formatValue} only so the template literals
+ * do not nest.
+ *
+ * @param {[string, unknown]} entry The key and its value.
+ * @returns {string} `key: value`.
+ */
+function formatEntry([key, value]) {
+  return `${key}: ${formatValue(value)}`;
 }
 
 /**

package/src/lang/parser.js

@@ -75,7 +75,8 @@ class Parser {
 
   /**
    * @param {TokenType} type The kind required.
-   * @param {unknown} [value] The exact value required, when it matters.
+   * @param {string} [value] The exact value required, when it matters. Always a keyword or a
+   *   piece of punctuation, which is why it can go straight into the message.
    * @returns {Token} The consumed token.
    * @throws {FormaError} If the current token is not what was required.
    */
@@ -271,17 +272,17 @@ class Parser {
   parseIf() {
     const loc = this.expect('ident', 'if').loc;
     const condition = this.parseExpression();
-    const then = this.parseBracedBody();
-    let otherwise = null;
+    const consequent = this.parseBracedBody();
+    let alternate = null;
     if (this.isIdent('else')) {
       this.next();
       if (this.isIdent('if')) {
-        otherwise = { attributes: [], params: [], locals: [], blocks: [this.parseIf()] };
+        alternate = { attributes: [], params: [], locals: [], blocks: [this.parseIf()] };
       } else {
-        otherwise = this.parseBracedBody();
+        alternate = this.parseBracedBody();
       }
     }
-    return { kind: 'if', condition, then, otherwise, loc };
+    return { kind: 'if', condition, consequent, alternate, loc };
   }
 
   // --- expressions ----------------------------------------------------------------
@@ -298,10 +299,10 @@ class Parser {
     const condition = this.parseBinary(0);
     if (this.isPunct('?') && !this.breaksLine()) {
       this.next();
-      const then = this.parseExpression();
+      const consequent = this.parseExpression();
       this.expect('punct', ':');
-      const otherwise = this.parseExpression();
-      return { kind: 'conditional', condition, then, otherwise };
+      const alternate = this.parseExpression();
+      return { kind: 'conditional', condition, consequent, alternate };
     }
     return condition;
   }