@mark1russell7/coeval 0.20.1 → 0.21.0

package/src/stdlib.ts

@@ -18,7 +18,7 @@ import {
 import { Failure } from "./errors.ts";
 import { type Cap, type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
 import type { World } from "./ladder.ts";
-import { type AttributeDeclaration, type CircularRule, type TreeContract, circularOf, equationType, lookupKind } from "./world.ts";
+import { type AttributeDeclaration, type CircularRule, type TreeContract, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
 import { STD_DOMAINS } from "./types.ts";
 import type { SyntaxProfile } from "./syntax.ts";
 
@@ -67,6 +67,15 @@ export const STD_WORLD: World = {
       pure: true,
       summary: "A step of a path: it follows a key again and again, until it reaches a node of a type.",
     },
+    tree: {
+      kinds: {
+        named: {
+          verbs: { step: "walk.named", view: "view.card" },
+          pure: true,
+          summary: "A step of a path: it goes up to the nearest registry of names, and it gives the node with the name (TREE.NAMED).",
+        },
+      },
+    },
     panel: {
       verbs: { eval: "tree.node", view: "view.op" },
       parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
@@ -167,6 +176,7 @@ export const WORLD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
       { name: "panel", kind: "panel", args: "named", fields: ["width", "height", "children"] },
       { name: "box", kind: "box", args: "named", fields: ["width", "height", "children"] },
       { name: "nearest", kind: "nearest", args: "named", fields: ["type", "follow", "self"] },
+      { name: "tree.named", kind: "tree.named", args: "named", fields: ["name", "in"] },
       // An operator document with fewer terms than its operator takes, for example add(5) (K163, D65).
       { name: "add", kind: "add" },
       { name: "multiply", kind: "multiply" },
@@ -272,6 +282,8 @@ export interface AttributeTrace {
 /** The state of a node behind its brand. */
 interface NodeState extends LoopNode {
   readonly build: TreeBuild;
+  /** The binding name from the header of the document of the node, for the registry of names (TREE.NAMED). */
+  readonly name: string | undefined;
   /**
    * This function gives an attribute through its ladder (TREE.LADDER).
    *
@@ -853,6 +865,57 @@ function plainOf(value: unknown, path: Set<object>): Result {
   }
 }
 
+/**
+ * This function gives the collection of an attribute of a node (TREE.COLLECT, D122). It visits the node, then each node
+ * of the same tree in each list `children`, in the order of the lists. Each node is visited one time.
+ * The registry of names (TREE.NAMED) gives a record from each binding name to its node.
+ */
+function collected(root: HostThing, key: string, declared: unknown): Result {
+  const top = stateOf(root) as NodeState;
+  const rule = collectOf(declared);
+  if (!rule.ok) return fail("#VALUE!", `The attribute ${attributeText(key, top.type, top.place)} has a bad declaration collect. ${rule.reason}`);
+  const registry: Record<string, unknown> = {};
+  const owners = new Map<string, NodeState>();
+  let acc = rule.names ? ok(registry) : top.equation(rule.unit, NO_NAMES);
+  if (!acc.ok) return acc;
+  const seen = new Set<NodeState>();
+  const stack: unknown[] = [root];
+  while (stack.length > 0) {
+    const thing = stack.pop();
+    const at = stateOf(thing);
+    // An item that is not a node of this tree does not count, and a node counts one time.
+    if (at === undefined || at.build !== top.build || seen.has(at)) continue;
+    seen.add(at);
+    if (rule.names) {
+      const name = at.name;
+      const earlier = name === undefined ? undefined : owners.get(name);
+      if (earlier !== undefined) {
+        const both = `${earlier.type} at [${earlier.place.join(", ")}] and ${at.type} at [${at.place.join(", ")}]`;
+        return fail("#VALUE!", `Two nodes have the name ${name} in the registry ${attributeText(key, top.type, top.place)}: ${both}.`);
+      }
+      if (name !== undefined) {
+        owners.set(name, at);
+        putField(registry, name, thing);
+      }
+    } else {
+      const term = entryOf(at.tree?.contributes, key);
+      if (term !== undefined) {
+        const item = at.equation(term, NO_NAMES);
+        if (!item.ok) return item;
+        acc = top.equation(rule.combine, { acc: acc.value, item: item.value });
+        if (!acc.ok) return acc;
+      }
+    }
+    const children = at.read("children");
+    if (children === undefined) continue;
+    if (!children.ok) return children;
+    if (!Array.isArray(children.value)) return fail("#VALUE!", `The collection of ${key} needs a list in children of ${at.type} at [${at.place.join(", ")}].`);
+    const list = children.value as readonly unknown[];
+    for (let index = list.length - 1; index >= 0; index -= 1) stack.push(list[index]);
+  }
+  return acc;
+}
+
 /**
  * This function makes a node of the decorated tree. A step `parent` gives the self of the context of the node, and a
  * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
@@ -916,6 +979,7 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
       if (copied !== undefined) return { result: copied, by: "copy" };
     }
     if (declared?.fold !== undefined) return { result: fold(key, declared.fold), by: "default" };
+    if (declared?.collect !== undefined) return { result: collected(node, key, declared.collect), by: "default" };
     if (declared?.default !== undefined) return { result: state.equation(declared.default, NO_NAMES), by: "default" };
     return undefined;
   };
@@ -984,6 +1048,7 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
 
   const state: NodeState = {
     build,
+    name: input.doc.name,
     type,
     place,
     tree,
@@ -1170,8 +1235,29 @@ export function nearestWalker(options: NearestOptions = {}): Walker {
 
 const nearest: Walker = /* @__PURE__ */ nearestWalker();
 
+/**
+ * The walker of the step `tree.named` (TREE.NAMED, D122). It goes up from the thing before the step through the key
+ * `parent`, to the first thing that answers the registry. The field `in` names the registry, and the default is
+ * `names`. The walker gives the node with the field `name` in that registry.
+ */
+const named: Walker = ({ data, here, deref }) => {
+  const name = isRecord(data) ? field(data, "name") : undefined;
+  if (typeof name !== "string") return { ok: false, code: "#VALUE!", reason: "The step tree.named needs a text name." };
+  const registry = isRecord(data) && typeof field(data, "in") === "string" ? String(field(data, "in")) : "names";
+  let at: Thing | undefined = here;
+  for (let hops = 0; hops < 256 && at !== undefined && at !== null; hops += 1) {
+    const found = deref(at, registry);
+    if (found !== undefined) {
+      if (!isRecord(found) || !Object.hasOwn(found, name)) return { ok: false, reason: `The registry ${registry} has no node with the name ${name}.` };
+      return { ok: true, thing: field(found, name) as Thing };
+    }
+    at = deref(at, "parent");
+  }
+  return { ok: false, reason: `No registry ${registry} is on the way.` };
+};
+
 /** The walkers of the standard world, by name. */
-export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest };
+export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest, "walk.named": named };
 
 /** This function evaluates parts one after the other, and stops at the first error. */
 function* inOrder(parts: readonly RunPart[]): Generator<Promise<unknown>, { readonly values: readonly unknown[] } | { readonly error: Result }, unknown> {

package/src/types.ts

@@ -1144,8 +1144,10 @@ function valueStep(value: unknown, key: Key): { readonly found: unknown } | { re
  *
  * - A record gives the type of its field. A closed record without the field has no such step. An open record gives
  *   `unknown`.
- * - A list gives the type of its items for an index, and `number` for `length`.
- * - A base type reads the steps of its domain, then of each parent (`Domain.steps`).
+ * - A list gives the type of its items for an index, and `number` for `length`. Another key has no such step.
+ * - A base type reads the steps of its domain, then of each parent (`Domain.steps`). A base type of the kernel
+ *   without such a step has no step, because its values are not objects (TYPE.NO-STEP, D120).
+ * - A function type has no step, because a step into a function reaches nothing.
  * - A union joins the steps of its types. `one` gives the values that the step reaches.
  * - Each other step gives `unknown`, and `never` gives `never`.
  *
@@ -1171,10 +1173,13 @@ export function stepType(
         const found = steps[name] as ValueType;
         return { type: examine === undefined ? found : examine(found, `type of the step ${name} of the domain ${each}`) };
       }
-      return { type: "unknown" };
+      // A value of a base type of the kernel is not an object, thus a step into it reaches nothing (TYPE.NO-STEP).
+      return Object.hasOwn(STD_DOMAINS, form.name) ? NO_STEP : { type: "unknown" };
+    case "fn":
+      return NO_STEP;
     case "list":
       if (key === "length") return { type: "number" };
-      return { type: indexOf(key) >= 0 ? form.item : "unknown" };
+      return indexOf(key) >= 0 ? { type: form.item } : NO_STEP;
     case "record":
       if (Object.hasOwn(form.fields, name)) return { type: form.fields[name] as ValueType };
       return form.closed ? { missing: Object.keys(form.fields) } : { type: "unknown" };
@@ -1204,6 +1209,9 @@ export function stepType(
   }
 }
 
+/** The answer of `stepType` for a type whose members have no step with the key, and no fields to name. */
+const NO_STEP: StepType = { missing: [] };
+
 /** A term that `typeIssues` reads later: the term, its keys from the root and its depth. */
 interface Pending {
   readonly type: unknown;

package/src/world.ts

@@ -116,12 +116,20 @@ export interface LazyRule {
  * - `lazy`: the parts that an evaluation can skip and still give a value.
  * - `reads`: the roots that the code of the kind resolves as a whole, with the path of one root. The static facts
  *   give a read of each root at each document of the kind (D44). The tree node reads `self` this way.
+ * - `effects`: the effects that the code of `eval` can cause, in the form of the field `effects` of a kind (D27). In
+ *   the answer of the hook `facts`, it gives the effects of the code of a name. The contract of a kind does not
+ *   describe an own entry for another evaluator, thus only the hook can give its effects (CAP.OWN-EFFECTS, D118).
+ * - `drives`: the parts that the code of a runner evaluates itself, without a wait, in the form of the lazy rules. A
+ *   step under such a part cannot wait for the host. The check of a run then refuses a part that can wait there
+ *   (RUN.DRIVES, D119). Without `drives`, the check assumes that the runner passes each wait of its parts through.
  */
 export interface KindFacts {
   readonly pure?: boolean;
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
   readonly reads?: readonly Root[];
+  readonly effects?: "type" | readonly string[];
+  readonly drives?: readonly LazyRule[];
 }
 
 /**
@@ -136,14 +144,38 @@ export interface KindFacts {
  * - `default`: the term that gives the value when no rung before it answers and the declaration has no fold.
  * - `circular`: a cycle of this attribute gives its fixed point, not `#CYCLE!` (TREE.CIRCULAR, D113). Only a cycle
  *   whose attributes each declare `circular` gives a fixed point.
+ * - `collect`: the value of a node without an answer of the first four rungs and without a fold. The node combines
+ *   the contributions of each node of its subtree (TREE.COLLECT, D122).
  */
 export interface AttributeDeclaration {
   readonly copy?: boolean;
   readonly fold?: { readonly unit: Json; readonly combine: Json };
   readonly default?: Json;
   readonly circular?: CircularDeclaration;
+  readonly collect?: CollectDeclaration;
 }
 
+/**
+ * The declaration `collect` of an attribute (TREE.COLLECT, D122). The node of the attribute visits each node of its
+ * subtree. It visits the node itself first. Then it visits the nodes in its list `children`, in the order of the list.
+ *
+ * - `{ unit, combine }`: the collection starts with the term `unit`. The term `combine` then adds the contribution
+ *   of each node, with the names `acc` and `item`. A node contributes when its kind has an equation for the
+ *   attribute in `tree.contributes`.
+ * - `"names"`: the registry of binding names. Its value is a record from the header name of each node to its node
+ *   (TREE.NAMED). Two nodes with one name give `#VALUE!` at the read of the registry.
+ */
+export type CollectDeclaration = { readonly unit: Json; readonly combine: Json } | "names";
+
+/** A declaration `collect` that the kit can use, or the reason of a bad declaration (D122). */
+export type CollectRule =
+  | { readonly ok: true; readonly names: true }
+  | { readonly ok: true; readonly names: false; readonly unit: Json; readonly combine: Json }
+  | { readonly ok: false; readonly reason: string };
+
+/** The rule of the registry of binding names. */
+const NAMES_RULE: CollectRule = /* @__PURE__ */ Object.freeze({ ok: true, names: true });
+
 /**
  * The declaration `circular` of an attribute (TREE.CIRCULAR, D113). The attribute that a cycle reaches first leads it.
  * The leader evaluates again until no value of the cycle changes.
@@ -200,6 +232,21 @@ export function circularOf(declared: unknown): CircularRule {
   return { ok: true, start: start as Json, limit };
 }
 
+/**
+ * This function reads the declaration `collect` of an attribute (D122). The tree kit, the reference, `check` and the
+ * graph of attribute instances read it with this one function.
+ *
+ * @param declared - The value of the field `collect`.
+ * @returns The rule of the collection, or the reason when the declaration has no correct form.
+ */
+export function collectOf(declared: unknown): CollectRule {
+  if (declared === "names") return NAMES_RULE;
+  if (!isRecord(declared) || !Object.hasOwn(declared, "unit") || !Object.hasOwn(declared, "combine")) {
+    return { ok: false, reason: 'The declaration collect needs the text "names" or a record with the fields unit and combine.' };
+  }
+  return { ok: true, names: false, unit: field(declared, "unit") as Json, combine: field(declared, "combine") as Json };
+}
+
 /**
  * The tree contract of a kind (D42): the equations of the attributes of its nodes. Each equation is a document that
  * evaluates with the node as `self` and without capabilities. A bare equation gets the type `of` of the parts of the
@@ -209,11 +256,14 @@ export function circularOf(declared: unknown): CircularRule {
  * - `down`: the attributes of each child of the node. `self` is this node. An equation sees the names `child`,
  *   `index` and `prev` (TREE.DOWN).
  * - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
+ * - `contributes`: the contribution of the node to each collection of an attribute (TREE.COLLECT, D122). An
+ *   equation sees no names.
  */
 export interface TreeContract {
   readonly equations?: Readonly<Record<string, Json>>;
   readonly down?: Readonly<Record<string, Json>>;
   readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
+  readonly contributes?: Readonly<Record<string, Json>>;
 }
 
 /**