aontu 0.52.1 → 0.54.0

package/src/val/PlaceVal.ts

@@ -0,0 +1,193 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE PLACEHOLDER `_` (G8 phase 3,
+// docs/capability-review/g8-generation.md): a HOLE in a call, filled
+// by whatever the call is unified with.
+//
+//   x: {&: {m: _ + 2}}   x: a: m: 1     ->  a: m: 3
+//   greeting: upper(_) & hello          ->  "HELLO"
+//
+// WHY A HOLE AND NOT A FUNCTION PARAMETER. Aontu has no user-defined
+// functions and will not get them (G8's Boundary): a function value
+// crossing into the data plane is the step that makes a configuration
+// language a programming language. A hole is not a parameter -- it
+// cannot be named, passed, or partially applied. It says only "the
+// value that arrives here", which is what a template needs to compute
+// from the value it lands on.
+//
+// ALONE, `_` IS TOP WITH A MARK: it admits everything and is filled by
+// its peer, exactly as TOP is dropped by one. What makes it different
+// is that a CALL can see it, and a call that holds one waits for a
+// peer to fill it instead of resolving around it. Unfilled at
+// generation it is an error, as TOP is -- a hole is not a value.
+
+import type {
+  Val,
+  ValSpec,
+} from '../type'
+
+import {
+  AontuContext,
+} from '../ctx'
+
+import { Val as ValBase } from './Val'
+
+
+class PlaceVal extends ValBase {
+  isPlace = true
+
+  constructor(
+    spec: ValSpec,
+    ctx?: AontuContext
+  ) {
+    super(spec, ctx)
+  }
+
+
+  unify(peer: Val, _ctx: AontuContext): Val {
+    // The peer FILLS the hole. Against TOP there is nothing to fill it
+    // with, so it waits -- and waiting is not done, or a call holding
+    // it would resolve around it.
+    if (peer.isTop) {
+      this.notdone()
+      return this
+    }
+
+    return peer
+  }
+
+
+  get canon() {
+    return '_'
+  }
+
+
+  // A hole admits everything, so nothing sits above it -- the same
+  // answer TOP gives, for the same reason.
+  superior(): Val {
+    return this
+  }
+
+
+}
+
+
+// A HOLE BELONGS TO ITS NEAREST ENCLOSING GENERATOR. A `_` inside a
+// generator's template (pack/each, arg 1) or condition (filter, arg 1)
+// is that generator's to bind — "_ is the source child" — so neither
+// the hole test nor the fill walk may cross into those arguments from
+// outside. Before this boundary, `close(pack(d, _ & t))` reported a
+// hole to the OUTER call, so an ordinary overlay statement was
+// absorbed into the template instead of merging with the generated
+// child (use-cases/BUGS.md §10), and an outer pack's fill pass
+// captured a NESTED pack's hole lexically, binding it to the outer
+// source (§34). The data argument (arg 0) is not a binding position,
+// so it stays visible: a hole there is an outer hole as before.
+function boundArgStart(v: any): number {
+  return true === v.isPackFunc || true === v.isEachFunc ||
+    true === v.isFilterFunc ? 1 : Infinity
+}
+
+
+// Does this value CONTAIN a hole? Asked of a call before it resolves:
+// a call holding one must wait for a peer to fill it. Holes inside a
+// generator's own binding arguments are NOT this value's holes — see
+// boundArgStart above.
+function hasPlace(v: Val): boolean {
+  if (true === (v as any).isPlace) {
+    return true
+  }
+
+  const peg: any = (v as any).peg
+  const bound = boundArgStart(v)
+
+  if (Array.isArray(peg)) {
+    for (let cI = 0; cI < peg.length && cI < bound; cI++) {
+      const c = peg[cI]
+      if (true === c?.isVal && hasPlace(c)) {
+        return true
+      }
+    }
+  }
+  else if (true === peg?.isVal) {
+    return hasPlace(peg)
+  }
+  else if (null != peg && 'object' === typeof peg) {
+    for (const k of Object.keys(peg)) {
+      if (true === peg[k]?.isVal && hasPlace(peg[k])) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+
+// The same tree with every hole filled by `fill`. Answers the value
+// UNCHANGED when it holds no hole, so a caller can test identity to
+// know whether anything was filled -- and so a tree with no hole is
+// never needlessly cloned. A nested generator's binding arguments are
+// left untouched (boundArgStart): those holes are the inner
+// generator's to fill with its OWN source children when it fires.
+function fillPlace(v: Val, fill: Val, ctx: AontuContext): Val {
+  if (true === (v as any).isPlace) {
+    return fill
+  }
+
+  const peg: any = (v as any).peg
+  const bound = boundArgStart(v)
+
+  if (Array.isArray(peg)) {
+    let changed = false
+    const out = peg.map((c: any, cI: number) => {
+      if (true !== c?.isVal || bound <= cI) {
+        return c
+      }
+      const f = fillPlace(c, fill, ctx)
+      changed = changed || f !== c
+      return f
+    })
+    return changed ? rebuild(v, out, ctx) : v
+  }
+
+  if (true === peg?.isVal) {
+    const f = fillPlace(peg, fill, ctx)
+    return f === peg ? v : rebuild(v, f, ctx)
+  }
+
+  if (null != peg && 'object' === typeof peg) {
+    let changed = false
+    const out: Record<string, Val> = {}
+    for (const k of Object.keys(peg)) {
+      const c = peg[k]
+      // No isVal guard: a slot holding something that is not a Val
+      // answers itself, because fillPlace's own first tests -- is it a
+      // hole, has it a peg -- are both false for one.
+      const f = fillPlace(c, fill, ctx)
+      changed = changed || f !== c
+      out[k] = f
+    }
+    return changed ? rebuild(v, out, ctx) : v
+  }
+
+  return v
+}
+
+
+// A clone carrying a new peg. `clone` shares the peg by reference (see
+// Val.clone), which is exactly what must NOT happen here: the tree
+// being filled is a template, and the fill is one destination's.
+function rebuild(v: Val, peg: any, ctx: AontuContext): Val {
+  const out: any = v.clone(ctx)
+  out.peg = peg
+  out.dc = 0
+  return out
+} /* node:coverage ignore next 8 */
+
+
+export {
+  hasPlace,
+  fillPlace,
+  PlaceVal,
+}

package/src/val/PlusOpVal.ts

@@ -59,6 +59,61 @@ function isBig(k: OpKind): boolean {
 }
 
 
+// Only concrete scalar operands are valid: anything else (kinds, maps,
+// lists, null, top, funcs) must not coerce — the JS `+` would leak
+// internals like "[object Object]" into output. A non-scalar operand
+// leaves the op unresolved, which generate() reports.
+//
+// A pref operand contributes its preferred value (`pref(1)+2`), and
+// therefore that value's kind too.
+function operand(v: any) {
+  while (v?.isPref) {
+    v = v.peg
+  }
+  return v
+}
+
+
+// The operand's LEAF, not the JavaScript type of its peg: integer and
+// float share `number`, while the exact leaves are told apart from each
+// other and from everything else by their own flags. The whole ladder in
+// `operate` dispatches on this and never on `typeof`.
+function opkind(v: any): OpKind | undefined {
+  if (!(v?.isVal && v.isScalar)) {
+    return undefined
+  }
+  if (v.isBigInteger) {
+    return 'biginteger'
+  }
+  if (v.isBigDecimal) {
+    return 'bigdecimal'
+  }
+  if (v.isInteger) {
+    return 'integer'
+  }
+  const t = typeof v.peg
+  return 'number' === t ? 'float' :
+    'string' === t ? 'string' :
+      'boolean' === t ? 'boolean' :
+        undefined
+}
+
+
+// THE TEXT `+` WOULD MAKE OF THIS OPERAND, or undefined if `+` would not
+// take it at all.
+//
+// `join` folds with `+` seeded with `""`, so every member goes through
+// concatenation's string branch — and this is the function that branch
+// calls. Exported so that the fold and the operator cannot drift into
+// two answers to "how does a number become text": there is one
+// rendering, `digits` below, and both reach it here.
+function plusText(v: Val): string | undefined {
+  const o: any = operand(v)
+  const k = opkind(o)
+  return undefined === k ? undefined : digits(o, k)
+}
+
+
 class PlusOpVal extends OpBaseVal {
   isPlusOp = true
 
@@ -80,43 +135,6 @@ class PlusOpVal extends OpBaseVal {
 
 
   operate(ctx: AontuContext, args: Val[]) {
-    // Only concrete scalar operands are valid: anything else (kinds,
-    // maps, lists, null, top, funcs) must not coerce — the JS `+` would
-    // leak internals like "[object Object]" into output. A non-scalar
-    // operand leaves the op unresolved, which generate() reports.
-    const operand = (v: any) => {
-      // A pref operand contributes its preferred value (`pref(1)+2`),
-      // and therefore that value's kind too.
-      while (v?.isPref) {
-        v = v.peg
-      }
-      return v
-    }
-
-    // The operand's LEAF, not the JavaScript type of its peg: integer
-    // and float share `number`, while the exact leaves are told apart
-    // from each other and from everything else by their own flags. The
-    // whole ladder below dispatches on this and never on `typeof`.
-    const opkind = (v: any): OpKind | undefined => {
-      if (!(v?.isVal && v.isScalar)) {
-        return undefined
-      }
-      if (v.isBigInteger) {
-        return 'biginteger'
-      }
-      if (v.isBigDecimal) {
-        return 'bigdecimal'
-      }
-      if (v.isInteger) {
-        return 'integer'
-      }
-      const t = typeof v.peg
-      return 'number' === t ? 'float' :
-        'string' === t ? 'string' :
-          'boolean' === t ? 'boolean' :
-            undefined
-    }
-
     const av: any = operand(args[0])
     const bv: any = operand(args[1])
     const ak = opkind(av)
@@ -157,9 +175,18 @@ class PlusOpVal extends OpBaseVal {
     }
 
     // Float with float or integer: unchanged R5 contagion, binary64
-    // addition, float result (`1 + 2.0` is `3.0`).
+    // addition, float result (`1 + 2.0` is `3.0`) -- but a sum that
+    // leaves binary64's finite range is NOT a value. Aontu is a JSON
+    // superset and there is no notation for an infinity, so one here
+    // used to escape as `[aontu/internal]` in TypeScript and as Go's
+    // raw `json: unsupported value: +Inf` with no code at all
+    // (use-cases/BUGS.md 39). The same check governs the arithmetic
+    // family (float_overflow, ts/src/val/arith.ts).
     if ('float' === ak || 'float' === bk) {
-      return new NumberVal({ peg: av.peg + bv.peg })
+      const sum = av.peg + bv.peg
+      return Number.isFinite(sum) ?
+        new NumberVal({ peg: sum }) :
+        makeNilErr(ctx, 'float_overflow', this, undefined, 'add')
     }
 
     // Both operands are on the exact ladder: promote to the widest.
@@ -242,4 +269,5 @@ function decimal(v: any, k: OpKind): Decimal {
 
 export {
   PlusOpVal,
+  plusText,
 }

package/src/val/PrefFuncVal.ts

@@ -16,7 +16,6 @@ import {
   walk
 } from '../utility'
 
-import { NilVal } from '../val/NilVal'
 import { PrefVal } from '../val/PrefVal'
 import { FuncBaseVal } from './FuncBaseVal'