hclang 0.17.1 → 0.19.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,9 +133,50 @@ 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
@@ -141,13 +184,20 @@ export class FrameArray extends FrameList {
      * copying, and `===` still finds each one.
      */
     collectingCopy() {
-        const result = this.copy();
-        result.data = [...this.data];
-        return result;
+        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;
     }
@@ -197,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

@@ -134,10 +134,20 @@ export class FrameHandle extends Frame {
      * 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.
+     * 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) {
-        return this.target.collectingCopy().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

@@ -313,6 +313,28 @@ export class Frame extends MetaFrame {
     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.
      *
@@ -348,17 +370,20 @@ export class Frame extends MetaFrame {
      * and never of the source, which is why no source has to declare an element
      * type. Nothing is materialized on the receiver's behalf.
      *
-     * An empty stream answers nil whatever it started from: a reduce with nothing
-     * to work with has no result to report, and answering the seed would report a
-     * value that never took part.
+     * An empty stream answers the receiver it started from. The receiver is the
+     * accumulator before any element arrives, so a fold over nothing is that
+     * accumulator: an empty collect is `[]`, an empty join `“”`, an empty product
+     * `1`. This is what keeps a reduce compositional, since folding a whole stream
+     * must equal folding its first part and continuing from that answer, even
+     * when the first part is empty.
      */
     reduce(receiver, receiverState) {
         return Frame.reduceInto(this.elements(), receiver, receiverState);
     }
-    /** Threads one stream through a receiver, answering nil for an empty one. */
+    /** Threads one stream through a receiver, answering the receiver for an empty one. */
     static reduceInto(values, receiver, receiverState) {
         if (values.length === 0) {
-            return Frame.nil;
+            return receiver;
         }
         return values.reduce((accumulator, value) => accumulator.call(value, Frame.nil, receiverState), receiver);
     }

package/esm/lib/version.js

@@ -1 +1 @@
-export const VERSION = "0.17.1";
+export const VERSION = "0.19.0";

package/package.json

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