hclang 0.17.0 → 0.18.0

package/esm/lib/execute/eval-pipe.js

@@ -28,7 +28,7 @@ export class EvalPipe extends Frame {
     }
     apply(expr, context) {
         const result = expr.in(EvaluationScope.root(this.fileScope, this.hostNamespace));
-        this.out.apply(result, context);
+        this.out.collect(result, context);
         return result;
     }
 }

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

@@ -1,4 +1,6 @@
 import { Frame } from "./frame.js";
+import { BoundMethod } from "./bound-method.js";
+import { methodEffect } from "./effect-marker.js";
 import { FrameExpr } from "./frame-expr.js";
 import { FrameList } from "./frame-list.js";
 import { FrameNote } from "./frame-note.js";
@@ -119,7 +121,7 @@ export class FrameArray extends FrameList {
         }
         const clone = this.copy();
         seen.set(this, clone);
-        clone.data = this.data.map((item) => item.instanceCopy(seen));
+        clone.data = this.itemsFor(clone, (item) => item.instanceCopy(seen));
         for (const [key, value] of this.meta_pairs()) {
             clone.set(key, value.instanceCopy(seen));
         }
@@ -131,13 +133,71 @@ export class FrameArray extends FrameList {
         }
         return super.lookup_here(key, origin);
     }
-    /** An aggregate collects, which is what makes applying to one a push. */
+    /**
+     * An aggregate collects, which is what makes applying to one a push, unless
+     * it declares its own application. A declared application is an operation,
+     * so a refusal applied to one stays a refusal rather than being held.
+     */
     collects() {
-        return true;
+        return this.applicationMethod() === undefined;
+    }
+    /**
+     * The method this aggregate declares as its own application (#375).
+     *
+     * Applying an aggregate collects, and a receiver that wants another rule
+     * declares it as a method named `apply`, or `apply_` when the rule writes the
+     * receiver. It is found on the aggregate or its declared parents, the same
+     * chain a class's methods come from, and never in the scope around it, so a
+     * plain array keeps collecting wherever it is written.
+     */
+    applicationMethod() {
+        for (const key of FrameArray.APPLICATION_KEYS) {
+            const seen = new Set([this]);
+            let local = this.get_here(key);
+            let next = this.hasDeclaredParent() ? this.parent : undefined;
+            while (local.is.missing && next && !seen.has(next)) {
+                seen.add(next);
+                local = next.get_here(key);
+                next = next.hasDeclaredParent() ? next.parent : undefined;
+            }
+            if (local.className() === "FrameLazy")
+                return { key, method: local };
+        }
+        return undefined;
+    }
+    /**
+     * Runs a declared application with the receiver it binds to.
+     *
+     * The effect axis decides writes, as it does for every method: `apply_`
+     * reached mutably writes the receiver and answers it, and reached immutably
+     * answers an updated copy. A step that answers nil leaves the receiver as it
+     * was, the way an aggregate ignores a nil argument, so a reduce can skip an
+     * element without losing what it accumulated.
+     */
+    static applyDeclared(bound, argument, unchanged) {
+        const result = bound.call(argument);
+        return result.is.void ? unchanged : result;
+    }
+    /**
+     * 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() {
+        return this.copy();
     }
     apply(argument, _parameter) {
-        if (!argument.is.void) {
-            this.data.push(argument);
+        const declared = this.applicationMethod();
+        if (declared) {
+            const bound = new BoundMethod(declared.method, this, true, methodEffect(declared.key));
+            return FrameArray.applyDeclared(bound, argument, this);
+        }
+        return this.collect(argument);
+    }
+    /** Pushes a non-nil value, whatever application this aggregate declares. */
+    collect(value, _context = Frame.nil) {
+        if (!value.is.void) {
+            this.data.push(value);
         }
         return this;
     }
@@ -187,3 +247,10 @@ Object.defineProperty(FrameArray, "comparing", {
     writable: true,
     value: new Map()
 });
+/** The keys an aggregate declares its own application under, mutating first. */
+Object.defineProperty(FrameArray, "APPLICATION_KEYS", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: ["apply_", "apply"]
+});

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
@@ -125,6 +126,29 @@ 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 a collect.
+     * An aggregate that declares its own application (#375) is the exception
+     * by declaration: its `apply_` method writes like any mutating method.
+     */
+    apply(argument, parameter) {
+        const declared = this.target.applicationMethod();
+        if (!declared) {
+            return this.target.collectingCopy().apply(argument, parameter);
+        }
+        // A declared application is a method, so this name's mutability decides
+        // whether it writes the target or answers an updated copy, and a nil
+        // answer leaves the accumulator as it was (`FrameArray.applyDeclared`).
+        const result = new BoundMethod(declared.method, this.target, this.mutable, methodEffect(declared.key), this.copyOnWrite, this.readContext).call(argument, parameter);
+        return result.is.void ? this : result;
+    }
     toString() {
         return this.target.toString();
     }

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

@@ -134,9 +134,35 @@ export class FrameList extends Frame {
     }
     copy() {
         const clone = super.copy();
-        clone.data = [...this.data];
+        clone.data = this.itemsFor(clone, (item) => item);
         return clone;
     }
+    /**
+     * This frame's items as a copy holds them.
+     *
+     * An echo records which frame holds its property, so an echo this frame
+     * holds is re-issued for the copy. Otherwise the copy would print and
+     * iterate its own declarations as though another frame held them.
+     */
+    itemsFor(clone, other) {
+        return this.data.map((item) => this.holdsAsProperty(item)
+            ? FrameList.reownedEcho(item, clone)
+            : other(item));
+    }
+    /**
+     * A declaration echo re-issued for `owner`, looking through a statement's
+     * wrapper. The echo is read structurally for the same reason as
+     * `echoedBinding`.
+     */
+    static reownedEcho(term, owner) {
+        if (term.is.statement === true && term instanceof FrameList) {
+            const wrapper = term.copy();
+            wrapper.data = term.data.map((inner) => FrameList.reownedEcho(inner, owner));
+            return wrapper;
+        }
+        const echo = term;
+        return echo.reownedBy ? echo.reownedBy(owner) : term;
+    }
     /** Evaluate source items with an explicit innermost declaration target. */
     array_eval(input, out = this) {
         const scope = EvaluationScope.from(input).withWriteTarget(out, "construction");

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

@@ -41,6 +41,18 @@ export class FrameLiteral extends FrameAtom {
     toData() {
         return this.data;
     }
+    /**
+     * The same echo, held by `owner`. A copy of the declaring aggregate holds
+     * the copied property, so it needs an echo that names it as the holder.
+     */
+    reownedBy(owner) {
+        if (!this.binding)
+            return this;
+        return new FrameLiteral(this.data, {
+            ...this.binding,
+            target: new WeakRef(owner),
+        });
+    }
 }
 export class FrameSymbol extends FrameAtom {
     static for(symbol) {

package/esm/lib/frames/frame.js

@@ -302,6 +302,39 @@ 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;
+    }
+    /**
+     * Hands a result to this frame as the interpreter's output, not as an
+     * application written in the program.
+     *
+     * The evaluator's output array is also the file scope, where top-level
+     * declarations land, so a program can declare an application on it (#375).
+     * Collecting output must not run that declaration, so an aggregate collects
+     * here unconditionally. Any other output receiver, such as a test harness,
+     * is applied as usual.
+     */
+    collect(value, context = Frame.nil) {
+        return this.apply(value, context);
+    }
+    /**
+     * The method this frame declares as its own application, if any.
+     *
+     * Only an aggregate can declare one, so the base answers none. See
+     * `FrameArray.applicationMethod` for the protocol.
+     */
+    applicationMethod() {
+        return undefined;
+    }
     /**
      * The values this frame streams when it is iterated.
      *

package/esm/lib/version.js

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

package/package.json

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