@mark1russell7/coeval 0.15.0 → 0.17.0

package/src/schedule.ts

@@ -166,12 +166,12 @@ const NO_KEYS: readonly Key[] = /* @__PURE__ */ Object.freeze([]);
 const NO_EDGES: readonly NodeEdge[] = /* @__PURE__ */ Object.freeze([]);
 
 /** This function gives the error of a node on a cycle. It names only the node, thus each order of demands gives the same error. */
-function cycleOf(id: string): Failed {
+export function cycleOf(id: string): Failed {
   return fail("#CYCLE!", `The node ${id} is on a cycle of reads.`);
 }
 
 /** This function gives the error of a read of a node on the run side. */
-function runSide(id: string): Failed {
+export function runSide(id: string): Failed {
   return fail("#REF!", `The node ${id} is on the run side, thus it has no value for a reader.`);
 }
 
@@ -354,10 +354,12 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
 
   /**
    * This function gives the state of the current data epoch. Each data epoch has a new host thing at the root
-   * `world`. Thus a read that reaches the whole root changes at each change of data (READS.KEPT).
+   * `world`. Thus a read that reaches the whole root changes at each change of data (READS.KEPT). A kept read of a
+   * closure reads a node through `known`, without a demand (SCHED.CLOSURE).
    */
   const current = (): Epoch => {
     if (now !== undefined) return now;
+    const values = new Map<string, Result>();
     const nodesThing: HostThing = {
       [THING]: true,
       label: "nodes",
@@ -371,10 +373,18 @@ export function schedule(machine: Machine, options: ScheduleOptions = {}): Sched
       },
       has: (key) => docs.has(String(key)),
       toJson: record,
+      // A demand from a kept read can reach the node in evaluation, and that cycle is false (SCHED.ONE-MEANING).
+      // Thus only a node with its result in this epoch gives a value. Each such value is final (D31).
+      known(key) {
+        const result = values.get(String(key));
+        if (result === undefined) return undefined;
+        if (!result.ok) throw new Failure(result.error);
+        return { thing: result.value };
+      },
     };
     // The context has a world, thus `rootContext` only gives it its grant (CAP.NARROW-CODE). Each evaluation of the
     // epoch then uses this object with no copy.
-    now = { context: rootContext(machine, { ...base, world: nodesThing }), values: new Map() };
+    now = { context: rootContext(machine, { ...base, world: nodesThing }), values };
     return now;
   };
 

package/src/static.ts

@@ -619,9 +619,9 @@ const FOLD_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["acc", "ite
 
 /**
  * This function gives each equation of the tree contract of a kind, with the names that it sees (D42). An equation of
- * `equations`, a `unit` and a `default` see no names.
+ * `equations`, a `unit` and a `default` see no names. `check` and `factsOf` read the equations with this one function.
  */
-function equationsOf(kind: Kind): readonly { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] {
+export function equationsOf(kind: Kind): readonly { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] {
   const tree = kind.tree;
   if (tree === undefined) return [];
   const out: { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] = [];

package/src/stdlib.ts

@@ -2,12 +2,15 @@ import { type Json, type Key, field, isRecord } from "./doc.ts";
 import {
   type EvalInput,
   type Evaluator,
+  type InputWithRuntime,
   type Machine,
   type Plan,
   type Result,
   type RunPart,
   type Runner,
   type Steps,
+  RUNTIME,
+  evaluateWithin,
   fail,
   ok,
   planner,
@@ -17,6 +20,7 @@ import { type Cap, type HostThing, type Thing, type Walker, THING, isHostThing,
 import type { World } from "./ladder.ts";
 import { type AttributeDeclaration, type TreeContract, equationType, lookupKind } from "./world.ts";
 import { STD_DOMAINS } from "./types.ts";
+import type { SyntaxProfile } from "./syntax.ts";
 
 /**
  * The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
@@ -127,6 +131,52 @@ export const STD_WORLD: World = {
   defaults: { view: "view.card" },
 };
 
+/**
+ * The text syntax of the standard world (K162, D64). The syntax kit (D41) reads it, thus a host of `STD_WORLD` does
+ * not write its own profile. The operators `>`, `+` and `*` make `greater`, `add` and `multiply`. A call form makes
+ * each other kind, and `ref` uses the reference syntax of the kit.
+ *
+ * A literal in a place that takes a document gets its data envelope (K159, D65). Such a place is a part of `if`,
+ * `list`, `seq` or `pure`, the value of `write`, or the whole text. The document after a header name is such a place
+ * too. Thus `list(1, "a")` evaluates to `[1, "a"]`. The forms `add`, `multiply` and `greater` write an operator document that its operator
+ * does not write, for example `add(5)` (K163).
+ *
+ * A host with more kinds spreads this profile and adds its forms to `calls.forms`. `STD_SYNTAX` stays the profile of
+ * the formula kit.
+ */
+export const WORLD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
+  operators: [
+    { symbol: ">", fixity: "infix", prec: 4, assoc: "none", kind: "greater" },
+    { symbol: "+", fixity: "infix", prec: 5, assoc: "flat", kind: "add" },
+    { symbol: "*", fixity: "infix", prec: 6, assoc: "flat", kind: "multiply" },
+  ],
+  calls: {
+    ops: [],
+    forms: [
+      { name: "if", kind: "if", fields: ["test", "then", "else"], min: 2, wrap: true },
+      { name: "list", kind: "list", wrap: true },
+      { name: "seq", kind: "seq", wrap: true },
+      { name: "pure", kind: "pure", min: 1, wrap: true },
+      { name: "log", kind: "log", min: 1 },
+      { name: "write", kind: "write", fields: ["key", "value"], wrap: ["value"] },
+      { name: "math.sum", kind: "math.sum" },
+      { name: "math.product", kind: "math.product" },
+      { name: "number", kind: "number", args: "literal" },
+      { name: "text", kind: "text", args: "literal" },
+      { name: "bool", kind: "bool", args: "literal" },
+      { 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"] },
+      // An operator document with fewer terms than its operator takes, for example add(5) (K163, D65).
+      { name: "add", kind: "add" },
+      { name: "multiply", kind: "multiply" },
+      { name: "greater", kind: "greater" },
+    ],
+  },
+  literals: { envelopes: { number: "number", text: "text", bool: "bool" } },
+  header: { bind: "=" },
+} satisfies SyntaxProfile);
+
 function isNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }
@@ -234,7 +284,8 @@ interface NodeState {
    */
   read(key: string): Result | undefined;
   /**
-   * This function evaluates an equation of the kind of the node, with the node as `self` and no capabilities.
+   * This function evaluates an equation of the kind of the node, with the node as `self` and no capabilities. Its
+   * reads go in the list of the evaluation that made the node (READS.EQUATION).
    *
    * @param term - The equation.
    * @param names - The names that the equation sees.
@@ -403,6 +454,8 @@ function plainOf(value: unknown, path: Set<object>): Result {
  */
 function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined): HostThing {
   const { parts, context, kind: type, place, machine } = input;
+  // The equations evaluate in the evaluation that made the node, thus their reads go in its list (READS.EQUATION).
+  const runtime = (input as InputWithRuntime)[RUNTIME];
   const { tree, of } = contractOf(machine, input.typePath);
   const above = stateOf(outer);
   // Only a node of the same tree is a parent for the rungs `parent` and `copy`.
@@ -481,7 +534,7 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined)
     read,
     equation(term, names) {
       if (machine === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
-      return equationPlan(machine, of, term).evaluate({ ...context, names, caps: NO_CAPS, self: node });
+      return evaluateWithin(equationPlan(machine, of, term), { ...context, names, caps: NO_CAPS, self: node }, runtime);
     },
     childNames(child) {
       const children = read("children");
@@ -560,6 +613,18 @@ export function attributeTrace(node: Thing, attribute: string): AttributeTrace |
   return stateOf(node)?.trace(attribute);
 }
 
+/**
+ * This function gives the place of a node of the decorated tree: the keys from the root document to the document of
+ * the node (HOP.PLACE). A view puts each hop of a resolution on its node with it. The node keeps its place already,
+ * thus the function adds no record.
+ *
+ * @param thing - A thing, for example the thing of a hop.
+ * @returns The keys of the place, or `undefined` for a thing that is not a node of the decorated tree.
+ */
+export function placeOf(thing: Thing): readonly Key[] | undefined {
+  return stateOf(thing)?.place;
+}
+
 /** The path of the root `self`. A node of the tree resolves it, thus the list of reads holds the read (C4). */
 const SELF_PATH: readonly Json[] = /* @__PURE__ */ Object.freeze(["self"]);
 
@@ -597,6 +662,11 @@ export interface NearestOptions {
   readonly matches?: (node: Thing, wanted: Json | undefined) => boolean;
   /** The most hops of one walk. The default is 256. */
   readonly maxHops?: number;
+  /**
+   * `true`: the walk records one hop for each node on the way before the node that it reaches (HOP.EACH-STEP). Each
+   * such hop has the followed key as its step. The default is `false`: one hop for the whole walk.
+   */
+  readonly eachStep?: boolean;
 }
 
 function hostType(node: Thing, wanted: Json | undefined): boolean {
@@ -606,23 +676,28 @@ function hostType(node: Thing, wanted: Json | undefined): boolean {
 /**
  * This function makes a walker `nearest`. The walker follows a key (the default is `parent`) until the node that it
  * reaches has the wanted type. With `self: true`, the node where the walk starts is the first candidate. A node
- * without that key ends the walk with an error.
+ * without that key ends the walk with an error. With `eachStep`, a resolution with hops gets a hop for each node on the way.
  *
- * @param options - The test of a type and the most hops.
+ * @param options - The test of a type, the most hops and the record of each step.
  * @returns The walker.
  */
 export function nearestWalker(options: NearestOptions = {}): Walker {
   const matches = options.matches ?? hostType;
   const maxHops = options.maxHops ?? 256;
-  return ({ data, here, deref }) => {
+  const eachStep = options.eachStep === true;
+  return ({ data, here, deref, visit }) => {
     const follow = isRecord(data) && typeof field(data, "follow") === "string" ? String(field(data, "follow")) : "parent";
     const wanted = isRecord(data) ? field(data, "type") : undefined;
     const fromSelf = isRecord(data) && field(data, "self") === true;
+    const record = eachStep ? visit : undefined;
     let at: Thing | undefined = here;
     for (let hops = 0; hops < maxHops; hops += 1) {
-      if (hops > 0 || !fromSelf) at = at === undefined || at === null ? undefined : deref(at, follow);
+      const stepped = hops > 0 || !fromSelf;
+      if (stepped) at = at === undefined || at === null ? undefined : deref(at, follow);
       if (at === undefined || at === null) return { ok: false, reason: `No node of the type ${String(wanted)} is on the way.` };
       if (matches(at, wanted)) return { ok: true, thing: at };
+      // The hop of the whole walk records the node that the walk reaches. Each node before it gets its own hop.
+      if (stepped) record?.(follow, at);
     }
     return { ok: false, reason: "The walk is too long." };
   };