hclang 0.16.0 → 0.17.0

package/esm/lib/frames/evaluation-scope.js

@@ -166,15 +166,16 @@ export class EvaluationScope {
      * the argument to the argument", which is what made a closure's write target
      * and its argument the same frame and produced a self-referential binding.
      *
-     * A handle argument is the one exception, because a handle is explicitly a
-     * mutable view requested by the caller for exactly this purpose.
+     * A mutable handle argument is the one exception, because the caller asked
+     * for a mutable view by spelling the name with the effect marker (`x_`). A
+     * plain name also arrives as a handle, but an immutable one, and it grants no
+     * write: `f x` must not change `x`.
      */
     static call(argument, parameter = Frame.nil, closure, enclosing, receiverState) {
         const local = new Frame();
-        const target = argument instanceof FrameHandle ? argument.unwrap() : local;
-        const targetRole = argument instanceof FrameHandle
-            ? "handle"
-            : "statement";
+        const writable = argument instanceof FrameHandle && argument.isMutable();
+        const target = writable ? argument.unwrap() : local;
+        const targetRole = writable ? "handle" : "statement";
         const lookupFrames = [local, argument];
         if (!parameter.is.void)
             lookupFrames.push(parameter);

package/esm/lib/frames/frame-array.js

@@ -1,3 +1,4 @@
+import { Frame } from "./frame.js";
 import { FrameExpr } from "./frame-expr.js";
 import { FrameList } from "./frame-list.js";
 import { FrameNote } from "./frame-note.js";
@@ -51,6 +52,58 @@ export class FrameArray extends FrameList {
         }
         return undefined;
     }
+    /** Aggregates own identity, so `===` compares them by reference. */
+    ownsIdentity() {
+        return true;
+    }
+    /**
+     * `=` compares the complete view, the same one `&&` iterates: visible
+     * properties in declaration order, then elements by index, each by `=`.
+     * Spelling, private fields, the declared parent, and ids are not the value.
+     */
+    equals(other) {
+        return this.sameMembers(other, (left, right) => left.equals(right));
+    }
+    /** `==` is the same walk with `==` at every node. */
+    typeEquals(other) {
+        return this.sameMembers(other, (left, right) => left.typeEquals(right));
+    }
+    sameMembers(other, same) {
+        const right = other.referent();
+        if (right === this)
+            return Frame.all;
+        if (right.constructor !== this.constructor)
+            return Frame.nil;
+        const inProgress = FrameArray.comparing.get(this) ?? new Set();
+        if (inProgress.has(right))
+            return Frame.all;
+        inProgress.add(right);
+        FrameArray.comparing.set(this, inProgress);
+        try {
+            const keys = this.visibleKeys();
+            const rightKeys = right.visibleKeys();
+            if (keys.length !== rightKeys.length ||
+                keys.some((key, index) => key !== rightKeys[index]))
+                return Frame.nil;
+            for (const key of keys) {
+                if (same(this.get_here(key), right.get_here(key)) !== Frame.all) {
+                    return Frame.nil;
+                }
+            }
+            const elements = this.elements();
+            const rightElements = right.elements();
+            if (elements.length !== rightElements.length)
+                return Frame.nil;
+            return elements.every((element, index) => same(element, rightElements[index]) === Frame.all)
+                ? Frame.all
+                : Frame.nil;
+        }
+        finally {
+            inProgress.delete(right);
+            if (inProgress.size === 0)
+                FrameArray.comparing.delete(this);
+        }
+    }
     /**
      * Aggregates are where identity matters, so an instance copy isolates them:
      * every nested aggregate, in the data plane and the metadata plane alike, gets
@@ -127,3 +180,10 @@ Object.defineProperty(FrameArray, "SIGIL_STARTS", {
         { key: FrameArray.END_ARRAY, mode: "pop" },
     ]
 });
+/** Pairs under comparison, so a frame reachable from itself terminates. */
+Object.defineProperty(FrameArray, "comparing", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Map()
+});

package/esm/lib/frames/frame-handle.js

@@ -60,6 +60,20 @@ export class FrameHandle extends Frame {
     unwrap() {
         return this.target;
     }
+    /** A handle is transparent to equality: it compares as its target. */
+    referent() {
+        return this.target.referent();
+    }
+    equals(other) {
+        return this.target.equals(other);
+    }
+    typeEquals(other) {
+        return this.target.typeEquals(other);
+    }
+    /** Whether the name that produced this handle carried the effect marker. */
+    isMutable() {
+        return this.mutable;
+    }
     /** The lexical fallback selected for this particular read. */
     readContextFrame() {
         return this.readContext;

package/esm/lib/frames/frame-typed-number.js

@@ -66,6 +66,13 @@ export class FrameTypedNumber extends FrameNumeric {
         }
         return super.lookup_here(key, origin);
     }
+    /** `==` also asks the magnitude's rung: `3.m == 3.0.m` is nil. */
+    typeEquals(right) {
+        if (!(right instanceof FrameTypedNumber) || this.unit !== right.unit) {
+            return Frame.nil;
+        }
+        return this.magnitude.typeEquals(right.magnitude);
+    }
     equals(right) {
         if (!(right instanceof FrameTypedNumber) || this.unit !== right.unit) {
             return Frame.nil;

package/esm/lib/frames/frame.js

@@ -179,6 +179,41 @@ export class Frame extends MetaFrame {
     equals(other) {
         return this.toString() === other.toString() ? Frame.all : Frame.nil;
     }
+    /**
+     * typeEquals is `==`: the same value, and the same type at every node.
+     * It is strictly stronger than `equals`, so `3 == 3.0` is nil while
+     * `3 = 3.0` holds.
+     */
+    typeEquals(other) {
+        const left = this.referent();
+        const right = other.referent();
+        return left.constructor === right.constructor
+            ? left.equals(right)
+            : Frame.nil;
+    }
+    /**
+     * identical is `===`: whether both references reach the same frame.
+     *
+     * Only a frame that owns identity can be told apart from an equal copy.
+     * Atoms and closure bodies are shared by the copy contract, so sharing them
+     * is unobservable and identity falls back to `typeEquals`, which keeps the
+     * ladder monotone: `===` implies `==` implies `=`. No id is ever exposed.
+     */
+    identical(other) {
+        const left = this.referent();
+        const right = other.referent();
+        if (left.ownsIdentity())
+            return left === right ? Frame.all : Frame.nil;
+        return left.typeEquals(right);
+    }
+    /** The frame a reference reaches. A handle answers its target. */
+    referent() {
+        return this;
+    }
+    /** Whether a write can land on this frame, so that identity is observable. */
+    ownsIdentity() {
+        return false;
+    }
     /** Compare only this frame's data plane, excluding metadata. */
     dataEquals(other) {
         return this.dataString() === other.dataString() ? Frame.all : Frame.nil;

package/esm/lib/ops/conditionals.js

@@ -5,9 +5,14 @@ export const IfThen = (source, block, receiverState) => {
     }
     return Frame.nil;
 };
+/**
+ * `:` is "or else": a value that is not nil answers itself, and only nil calls
+ * the fallback. Composed after `?`, that makes `c ? t : e` answer `t` or `e`,
+ * because the taken branch's value reaches `:` as its source.
+ */
 export const IfElse = (source, block, receiverState) => {
     if (source === Frame.nil) {
         return block.call(Frame.nil, Frame.nil, receiverState);
     }
-    return Frame.nil;
+    return source;
 };

package/esm/lib/ops/math.js

@@ -13,11 +13,13 @@ export const Power = (source, block) => numeric(source, block, (left, right) =>
 export const Equals = (source, block) => {
     return source.equals(block);
 };
-export const DataEquals = (source, block) => {
-    return source.dataEquals(block);
+/** `==`: the same value and the same type at every node. */
+export const TypeEquals = (source, block) => {
+    return source.typeEquals(block);
 };
-export const MetadataEquals = (source, block) => {
-    return source.metadataEquals(block);
+/** `===`: the same frame. Atoms, which own no identity, fall back to `==`. */
+export const Identical = (source, block) => {
+    return source.identical(block);
 };
 export const GreaterThan = (source, block) => numeric(source, block, (left, right) => left.greaterThan(right));
 export const GreaterThanOrEqual = (source, block) => numeric(source, block, (left, right) => left.greaterThanOrEqual(right));

package/esm/lib/ops.js

@@ -1,7 +1,7 @@
 import { IfElse, IfThen } from "./ops/conditionals.js";
 import { FrameOps } from "./ops/frame-ops.js";
 import { MapElements, MapMembers, ReduceElements, ReduceMembers, } from "./ops/iterators.js";
-import { Add, DataEquals, Divide, Equals, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, MetadataEquals, Modulo, Multiply, Power, Subtract, } from "./ops/math.js";
+import { Add, Divide, Equals, GreaterThan, GreaterThanOrEqual, Identical, LessThan, LessThanOrEqual, Modulo, Multiply, Power, Subtract, TypeEquals, } from "./ops/math.js";
 import { BindType, HasType } from "./ops/type-operations.js";
 export { FrameCurry } from "./ops/frame-curry.js";
 export const Ops = new FrameOps({
@@ -18,8 +18,8 @@ export const Ops = new FrameOps({
     "%%": Modulo,
     "**": Power,
     "=": Equals,
-    "==": DataEquals,
-    "===": MetadataEquals,
+    "==": TypeEquals,
+    "===": Identical,
     ">": GreaterThan,
     ">>": GreaterThan,
     ">=": GreaterThanOrEqual,

package/esm/lib/version.js

@@ -1 +1 @@
-export const VERSION = "0.16.0";
+export const VERSION = "0.17.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hclang",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Homoiconic C command-line interpreter and REPL",
   "keywords": [
     "language",