hclang 0.16.0 → 0.17.1

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
@@ -82,6 +135,16 @@ export class FrameArray extends FrameList {
     collects() {
         return true;
     }
+    /**
+     * A fresh aggregate holding the same elements. Only the outer aggregate is
+     * new: the elements are shared, so collecting reuses them rather than
+     * copying, and `===` still finds each one.
+     */
+    collectingCopy() {
+        const result = this.copy();
+        result.data = [...this.data];
+        return result;
+    }
     apply(argument, _parameter) {
         if (!argument.is.void) {
             this.data.push(argument);
@@ -127,3 +190,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

@@ -7,10 +7,11 @@ import { methodEffect } from "./effect-marker.js";
  *
  * The handle's charter is that reference and nothing more. Two rules define it:
  *
- * - **Transparency.** Wrapping must not change what a value prints, equals, or
- *   exposes, so rendering, data, metadata, and array views all delegate to the
- *   target. A handle is invisible to comparison, and assignment unwraps it, so
- *   a mutation lands on the same frame it would have without the wrapper.
+ * - **Transparency.** Wrapping must not change what a value prints, equals,
+ *   exposes, or answers when applied, so rendering, data, metadata, array
+ *   views, and application all delegate to the target. A handle is invisible to
+ *   comparison, and assignment unwraps it, so a mutation lands on the same
+ *   frame it would have without the wrapper.
  * - **Caller-scoped lookup.** A handle created by symbol lookup carries that
  *   read's lexical context separately from the shared target. Local and
  *   declared-parent lookup remains live on the target, then falls back through
@@ -60,6 +61,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;
@@ -111,6 +126,19 @@ export class FrameHandle extends Frame {
     called_by(context, parameter) {
         return context.apply(this.target, parameter);
     }
+    /** Transparency covers application: a named aggregate collects like its literal. */
+    collects() {
+        return this.target.collects();
+    }
+    /**
+     * Applying through a name answers what applying the value would, without
+     * writing through the name. A collect lands on a fresh aggregate, so `xs 3`
+     * answers a new array and `xs` is unchanged, whether or not the name is
+     * mutable: a write goes through a mutating method or `@`, never application.
+     */
+    apply(argument, parameter) {
+        return this.target.collectingCopy().apply(argument, parameter);
+    }
     toString() {
         return this.target.toString();
     }

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;
@@ -267,6 +302,17 @@ export class Frame extends MetaFrame {
     collects() {
         return false;
     }
+    /**
+     * The receiver a collect lands on when it must not write this frame.
+     *
+     * A literal is a fresh aggregate each time it is evaluated, so collecting
+     * into it in place is unobservable. A value reached through a name is not,
+     * so the name asks for this instead. Anything that does not collect is its
+     * own receiver.
+     */
+    collectingCopy() {
+        return this;
+    }
     /**
      * The values this frame streams when it is iterated.
      *

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.1";

package/package.json

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