Hold a reference path like a sibling path; add the lowercase, uppercase and ascii transforms

README.md

@@ -273,10 +273,11 @@ reproducible. A time-based id (UUID v7, ULID) therefore draws its timestamp from
 the rng, not the clock — the result is a valid, reproducible value, not a real
 point in time.
 
-There are four kinds. **Derivations** read the digits emitted so far, so put them
+There are five kinds. **Derivations** read the digits emitted so far, so put them
 after their payload; **samples** read only the rng, so they stand alone; one
-**session counter** (`seq`) advances state held on the generator; and one
+**session counter** (`seq`) advances state held on the generator; one
-**computation** (`calc`) evaluates arithmetic over sibling fields. Arguments are
+**computation** (`calc`) evaluates arithmetic over sibling fields; and the
+**transforms** rewrite one field's value. Arguments are
 validated at `New` (a bad count, range, country, or expression fails fast); a
 length, count or decimal place beyond a sane maximum is rejected there too, so a
 fat-fingered `hex(2000000000)` can't try to allocate gigabytes at render.
@@ -299,6 +300,7 @@ fat-fingered `hex(2000000000)` can't try to allocate gigabytes at render.
 | `{iban(CC)}` | sample | a length- and mod-97-valid IBAN for country `CC` (BE, DE, DK, ES, FI, NO, SE) |
 | `{seq()}`, `{seq(name)}` | session counter | next integer (from 1) in this generator's sequence; `name` selects an independent counter |
 | `{calc(expr)}`, `{calc(expr,dp)}` | computation | value of an arithmetic expression over number literals and sibling fields; `dp` rounds |
+| `{lowercase(x)}`, `{uppercase(x)}`, `{ascii(x)}` | transform | the field `x` — a name, a path or a `..path` — lower-cased, upper-cased, or folded to ASCII (`Åsa` → `Asa`); they nest: `{lowercase(ascii(x))}` |
 
 `{ean()}` is also the ISBN-13 check (an ISBN-13 *is* an EAN-13 — build the 978/979
 prefix in data and call `{ean()}`). `{iban()}` is a sample, not a derivation:
@@ -339,9 +341,11 @@ data dirs:
 { "format": "Hej, {..en_US.person}!" }
 ```
 
-renders e.g. `Hej, Pat Smith!`. References are bound when you create the generator, so
+renders e.g. `Hej, Pat Smith!`. A reference path is held like a sibling path:
-a path that is unknown, names a folder, or steps through a choice
+`{..person.first} {..person.last}` read one person, and `{lowercase(..person.first)}`
-fails at `New`. A reference that leads back to its own value (directly, mutually,
+reads that same draw, while a bare `{..die} {..die}` is two draws. References are
+bound when you create the generator, so a path that is unknown, names a folder,
+or reads a field not every variant of a choice carries fails at `New`. A reference that leads back to its own value (directly, mutually,
 or through a chain) is a cycle that would never finish rendering, so it too is
 rejected at `New`.
 

builtins.go

@@ -6,6 +6,7 @@ import (
 	"math"
 	"strconv"
 	"strings"
+	"unicode"
 )
 
 // maxLen caps sample output lengths (hex, nanoid, base64) and maxDecimals caps
@@ -51,9 +52,10 @@ var builtins = map[string]builtin{
 		cc := a[0]
 		return func(s *session, _ string, _ []string) string { return iban(s, cc) }
 	}},
-	// calc is the one builtin that names operands (expand reads them for it);
+	"calc":      {arity: -1, check: checkCalc, prep: calcPrep, operands: calcOperands},
-	// every other ignores them. 1 or 2 args: the expression and an optional decimals.
+	"lowercase": {arity: 1, check: transformArg, prep: transformPrep(strings.ToLower), operands: transformOperand},
-	"calc": {arity: -1, check: checkCalc, prep: calcPrep},
+	"uppercase": {arity: 1, check: transformArg, prep: transformPrep(strings.ToUpper), operands: transformOperand},
+	"ascii":     {arity: 1, check: transformArg, prep: transformPrep(asciiFold), operands: transformOperand},
 	// seq is the one stateful builtin: a per-session counter from 1, advancing on
 	// each call. An optional name selects an independent counter; no name uses the
 	// default one. Deterministic by construction, so seeded output stays stable.
@@ -92,6 +94,98 @@ func chars(alphabet string) func([]string) callFn {
 
 const hexDigits = "0123456789abcdef"
 
+// transforms are the builtins that rewrite one operand's value; they nest, so
+// {lowercase(ascii(x))} folds then lowers.
+var transforms = map[string]func(string) string{
+	"ascii":     asciiFold,
+	"lowercase": strings.ToLower,
+	"uppercase": strings.ToUpper,
+}
+
+// unwrapTransform peels nested transform calls off an operand arg, returning the
+// field it finally names and the transforms to apply, innermost last.
+func unwrapTransform(arg string) (leaf string, chain []func(string) string, err error) {
+	for {
+		name, args, isCall := funcCall(arg)
+		if !isCall {
+			return arg, chain, nil
+		}
+		fn, isTransform := transforms[name]
+		if !isTransform {
+			return "", nil, fmt.Errorf("%s(%s) is not a transform, so it cannot be an operand", name, strings.Join(args, ","))
+		}
+		if len(args) != 1 {
+			return "", nil, fmt.Errorf("%s takes 1 arg, got %d", name, len(args))
+		}
+		chain = append(chain, fn)
+		arg = args[0]
+	}
+}
+
+func transformArg(fields map[string]node, a []string) error {
+	leaf, _, err := unwrapTransform(a[0])
+	if err != nil {
+		return err
+	}
+	if isRef(leaf) {
+		if leaf == refPrefix {
+			return fmt.Errorf("reference has no path")
+		}
+		return nil
+	}
+	return checkArm(leaf, fields)
+}
+
+func transformOperand(a []string) []string {
+	leaf, _, err := unwrapTransform(a[0])
+	if err != nil {
+		return nil
+	}
+	return []string{leaf}
+}
+
+func transformPrep(outer func(string) string) func([]string) callFn {
+	return func(a []string) callFn {
+		_, chain, err := unwrapTransform(a[0])
+		if err != nil {
+			panic(fmt.Sprintf("fejkdata: transform arg %q reached prep unvalidated: %v", a[0], err))
+		}
+		return func(_ *session, _ string, operands []string) string {
+			v := operands[0]
+			for i := len(chain) - 1; i >= 0; i-- {
+				v = chain[i](v)
+			}
+			return outer(v)
+		}
+	}
+}
+
+// asciiFolds maps the Latin letters with diacritics or ligatures to ASCII.
+var asciiFolds = map[rune]string{
+	'À': "A", 'Á': "A", 'Â': "A", 'Ã': "A", 'Ä': "A", 'Å': "A", 'Æ': "AE", 'Ç': "C",
+	'È': "E", 'É': "E", 'Ê': "E", 'Ë': "E", 'Ì': "I", 'Í': "I", 'Î': "I", 'Ï': "I",
+	'Ð': "D", 'Ñ': "N", 'Ò': "O", 'Ó': "O", 'Ô': "O", 'Õ': "O", 'Ö': "O", 'Ø': "O",
+	'Ù': "U", 'Ú': "U", 'Û': "U", 'Ü': "U", 'Ý': "Y", 'Þ': "Th", 'ß': "ss", 'Œ': "OE",
+	'à': "a", 'á': "a", 'â': "a", 'ã': "a", 'ä': "a", 'å': "a", 'æ': "ae", 'ç': "c",
+	'è': "e", 'é': "e", 'ê': "e", 'ë': "e", 'ì': "i", 'í': "i", 'î': "i", 'ï': "i",
+	'ð': "d", 'ñ': "n", 'ò': "o", 'ó': "o", 'ô': "o", 'õ': "o", 'ö': "o", 'ø': "o",
+	'ù': "u", 'ú': "u", 'û': "u", 'ü': "u", 'ý': "y", 'þ': "th", 'ÿ': "y", 'œ': "oe",
+}
+
+// asciiFold rewrites s to ASCII: folded Latin letters stay, any other non-ASCII
+// rune is dropped.
+func asciiFold(s string) string {
+	var b strings.Builder
+	for _, r := range s {
+		if r < unicode.MaxASCII {
+			b.WriteRune(r)
+		} else {
+			b.WriteString(asciiFolds[r])
+		}
+	}
+	return b.String()
+}
+
 // atoi parses an arg a builtin's check already validated. It panics rather than
 // returning zero, so a check that stops covering its own args is a stack trace and
 // not a silently wrong length, range or decimal count.

calc.go

@@ -122,26 +122,10 @@ func indexVars(n calcNode, at map[string]int) calcNode {
 	return n
 }
 
-// calcOperands lists the sibling-field names every {calc(...)} token in a format
+// calcOperands lists the sibling-field names a calc's args read. checkCalc reports
-// reads, so cycle detection sees the field edges calc renders through (a function
+// an expression that does not parse, so one that does not simply names nothing.
-// token otherwise carries no field edge).
+func calcOperands(args []string) []string {
-func calcOperands(format string) []string {
+	if len(args) == 0 {
-	var names []string
-	_ = eachToken(format, func(t ftoken) error {
-		if t.kind == 'b' {
-			names = append(names, calcTokenOperands(t.body)...)
-		}
-		return nil
-	})
-	return names
-}
-
-// calcTokenOperands lists the sibling-field names one {token} body reads, empty
-// for anything that is not a {calc(...)}. checkCalc reports an expression that does
-// not parse, so one that does not simply names nothing here.
-func calcTokenOperands(body string) []string {
-	name, args, ok := funcCall(body)
-	if !ok || name != "calc" || len(args) == 0 {
 		return nil
 	}
 	expr, err := parseCalc(args[0])

node.go

@@ -41,10 +41,11 @@ type template struct {
 	fields    map[string]node
 	repeat    int
 	separator string
-	ops       []op   // format compiled once (see compileOps); what expand walks
+	ops       []op              // format compiled once (see compileOps); what expand walks
-	grow      int    // minimum output size, to size the render buffer
+	grow      int               // minimum output size, to size the render buffer
-	fixed     bool   // no op varies, so every render is lit
+	fixed     bool              // no op varies, so every render is lit
-	lit       string // the whole output when fixed
+	lit       string            // the whole output when fixed
+	refs      map[string]string // each {..path} the format reads -> the head it is bound under
 	// bound maps each field the format addresses by dotted path to one path token
 	// reading it, which is the half of an overlap the fences name. nil when the
 	// format takes no path.
@@ -92,7 +93,7 @@ func compileString(s string) (node, error) {
 
 // compileFormat compiles the format into ops once every field is in place.
 func (t *template) compileFormat() {
-	t.ops, t.grow, t.bound, t.held = compileOps(t.format)
+	t.ops, t.grow, t.bound, t.held = compileOps(t.format, t.refs)
 	t.fixed = true
 	for _, o := range t.ops {
 		if o.kind != 'l' {
@@ -214,15 +215,15 @@ func compileTemplate(m map[string]any) (node, error) {
 		return nil, err
 	}
 	t.compileFormat()
-	if err := checkNoOverlap(format, t.bound); err != nil {
+	if err := checkNoOverlap(format, t.bound, nil); err != nil {
 		return nil, err
 	}
 	return t, nil
 }
 
 // checkPath reports whether a token's dotted tail can address a node whichever way
-// the draw goes, by the reachability rule descend applies — a multi-variant choice
+// the draw goes, by the reachability rule descend applies — a choice must carry
-// must carry the whole remaining path in the set every variant shares — plus the
+// the whole remaining path in the set every variant shares — plus the
 // rules a held draw adds, which descend has no need of: a level a path reads may
 // not carry a repeat, and each variant answers for that itself. So a path that
 // validates here resolves on every render, and a typo is a New-time error.

reference.go

@@ -8,33 +8,47 @@ import (
 
 // refPrefix marks a {..path} token: a reference to a node elsewhere in the data
 // root rather than a sibling field. The path is resolved across every loaded
-// directory (see linkRefs), and is stricter than the one Fake takes: a reference
+// directory (see linkRefs).
-// binds one node, so it cannot step through a choice even where Fake and List can.
 const refPrefix = ".."
 
 func isRef(name string) bool { return strings.HasPrefix(name, refPrefix) }
 
-// linkRefs resolves every {..path} reference in the assembled tree, binding the
+// linkRefs resolves every {..path} reference in the assembled tree. The head of the
-// target node into the referring template's fields under the token's key so the
+// path — up to the category it names — is bound into the referring template's
-// ordinary resolver renders it like a sibling. It runs once, after all data is
+// fields, and the rest reads into it the way a sibling path does, so a reference
-// merged, so a reference sees the final (override-resolved) tree. A path that is
+// is held like a sibling. It runs once, after all data is merged, so a reference
-// unknown, names a folder, or steps through a multi-variant choice fails here,
+// sees the final (override-resolved) tree. A path that is unknown, names a folder,
-// keeping a bad reference a New-time error, never a random render-time one.
+// or reads a field not every variant carries fails here, keeping a bad reference a
+// New-time error, never a random render-time one.
 func linkRefs(root map[string]node) error {
 	return walkNodes(root, func(path string, n node) error {
 		t, ok := n.(*template)
 		if !ok {
 			return nil
 		}
-		for _, name := range refTokens(t.format) {
+		names := refTokens(t.format)
-			target, err := lookup(root, strings.Split(name[len(refPrefix):], "."))
+		if len(names) == 0 {
+			return nil
+		}
+		if t.fields == nil {
+			t.fields = map[string]node{}
+		}
+		t.refs = make(map[string]string, len(names))
+		for _, name := range names {
+			head, target, tail, err := resolveRef(root, strings.Split(name[len(refPrefix):], "."))
 			if err != nil {
 				return fmt.Errorf("%s: reference {%s}: %w", path, name, err)
 			}
-			if t.fields == nil {
+			key := refPrefix + strings.Join(head, ".")
-				t.fields = map[string]node{}
+			if err := checkPath(target, tail, key); err != nil {
+				return fmt.Errorf("%s: reference {%s}: %w", path, name, err)
 			}
-			t.fields[name] = target
+			t.fields[key] = target
+			t.refs[name] = key
+		}
+		t.compileFormat()
+		if err := checkNoOverlap(t.format, t.bound, t.refs); err != nil {
+			return fmt.Errorf("%s: %w", path, err)
 		}
 		return nil
 	})
@@ -43,7 +57,7 @@ func linkRefs(root map[string]node) error {
 // checkBoundLevelsHeld rejects every route to a held name except the ones that read
 // its draw. An expansion holds one draw of that name; anything else that renders it
 // draws again, and the two disagree. checkNoOverlap settles the spellings within one
-// format (a token, a calc operand); this settles the rest — a reference, whether it
+// format (a token, an operand); this settles the rest — a reference, whether it
 // sits in that format or in anything the format renders, however deep.
 //
 // It runs after checkNoCycles, whose guarantee is what lets the walk terminate.
@@ -57,33 +71,48 @@ func checkBoundLevelsHeld(root map[string]node) error {
 		for head := range t.held {
 			heads = append(heads, head)
 		}
-		sort.Strings(heads) // so which overlap is reported does not vary
+		// Operand heads first, then paths, each in name order: a level read both
+		// ways is reported by the operand's fence, and which overlap is reported
+		// does not vary.
+		sort.Slice(heads, func(i, j int) bool {
+			_, pi := t.bound[heads[i]]
+			_, pj := t.bound[heads[j]]
+			if pi != pj {
+				return !pi
+			}
+			return heads[i] < heads[j]
+		})
+		readers := boundReaders(t.format, t.bound, t.refs)
 		for _, head := range heads {
-			// What one draw answers for depends on how the draw is read. A path may
+			// What one draw answers for depends on how the draw is read: a path pins
-			// read into anything the level contains; a calc renders its operand, so
+			// the levels it passes through and the leaf it lands on, an operand
-			// that draw fixes exactly the value the render produces.
+			// exactly the value its render produces.
 			held := map[node]bool{}
 			reader, isPath := t.bound[head]
 			if isPath {
-				cover(t.fields[head], held)
+				for _, r := range readers {
+					if a := splitArm(r.name, t.refs); a.key == head {
+						coverPath(t.fields[head], a.tail, held)
+					}
+				}
 			} else {
 				operandDraw(t.fields[head], held)
 			}
 			if len(held) == 0 {
-				continue // an early out: a literal head holds nothing to reach
+				continue // an early out: a fixed head holds nothing to reach
 			}
 			// One seen set across the edges: a node that cannot reach the level
 			// cannot reach it by another route either, so it is walked once here.
 			seen := map[node]bool{}
 			for _, e := range renderEdges(t) {
-				if splitArm(e.label).key == head {
+				if splitArm(e.label, t.refs).key == head {
 					continue // a token or operand reading this draw, the routes allowed
 				}
 				if renders(e.to, held, seen) {
 					if isPath {
 						return fmt.Errorf("%s: %s renders %q, which {%s} reads a path into; name the fields you want instead", path, e.reached(), head, reader)
 					}
-					return fmt.Errorf("%s: %s renders %q, which a {calc()} also reads; reach it one way so it is drawn once", path, e.reached(), head)
+					return fmt.Errorf("%s: %s renders %q, which a {%s()} also reads; reach it one way so it is drawn once", path, e.reached(), head, operandReader(t, head))
 				}
 			}
 		}
@@ -91,28 +120,63 @@ func checkBoundLevelsHeld(root map[string]node) error {
 	})
 }
 
-// cover collects what one held draw of a level answers for: the level and
+// operandReader names the builtin whose operand holds head.
-// everything contained in it, since a path may read any of it. A fixed string is
+func operandReader(t *template, head string) string {
-// left out — it cannot disagree with itself.
+	fn := ""
-func cover(n node, into map[node]bool) {
+	_ = eachToken(t.format, func(tok ftoken) error {
-	if isFixed(n) {
+		if tok.kind != 'b' || fn != "" {
+			return nil
+		}
+		if name, _, isFunc := funcCall(tok.body); isFunc {
+			for _, operand := range tokenOperands(tok.body) {
+				if splitArm(operand, t.refs).key == head {
+					fn = name
+				}
+			}
+		}
+		return nil
+	})
+	return fn
+}
+
+// coverPath collects what holding one path pins: every choice level the path
+// passes through, whole, and the leaf it renders.
+func coverPath(n node, tail []string, into map[node]bool) {
+	if _, isChoice := n.(*choice); isChoice || len(tail) == 0 {
+		cover(n, into, false)
 		return
 	}
-	into[n] = true
+	t, ok := n.(*template)
-	for _, c := range contained(n) {
+	if !ok {
-		cover(c.node, into)
+		return
+	}
+	if child, ok := t.fields[tail[0]]; ok {
+		coverPath(child, tail[1:], into)
 	}
 }
 
-// operandDraw collects what one held draw of a {calc()} operand answers for: the
+// cover collects a level and everything contained in it. A fixed string outside a
-// operand and what rendering it settles inside itself. A calc renders its operand
+// choice is left out — it cannot disagree with itself — but inside one each
+// variant carries its own, so there it counts.
+func cover(n node, into map[node]bool, inChoice bool) {
+	if isFixed(n) && !inChoice {
+		return
+	}
+	into[n] = true
+	_, isChoice := n.(*choice)
+	for _, c := range contained(n) {
+		cover(c.node, into, inChoice || isChoice)
+	}
+}
+
+// operandDraw collects what one held draw of an operand answers for: the operand
+// and what rendering it settles inside itself. The builtin renders its operand
 // whole, so that draw fixes every value the render produced, and a second route to
 // any of them disagrees with it.
 //
 // The walk stops at a {..path} edge, which is where the operand's own value ends
 // and a shared source begins: two names referencing one category are two draws, the
-// same rule {word} {word} follows. cover stops there too, by way of named, so both
+// same rule {word} {word} follows.
-// halves of the fence end at the same boundary.
 func operandDraw(n node, into map[node]bool) {
 	if isFixed(n) {
 		return
@@ -232,43 +296,35 @@ func sortedNames(m map[string]node) []string {
 	return names
 }
 
-// lookup finds the single node a reference path names, walking groups and
+// resolveRef walks a reference path through the folders to the category it names,
-// template fields by segment. A missing segment, a folder target, or a step
+// returning that head, the node, and the tail left to read into it.
-// through a choice (which has no one value to bind) is an error.
+func resolveRef(root map[string]node, segments []string) (head []string, target node, tail []string, err error) {
-func lookup(root map[string]node, segments []string) (node, error) {
 	var n node = &group{children: root}
-	for i := 0; i < len(segments); i++ {
+	i := 0
-		switch c := n.(type) {
+	for ; i < len(segments); i++ {
-		case *group:
+		g, ok := n.(*group)
-			child, ok := c.children[segments[i]]
+		if !ok {
-			if !ok {
+			break
-				return nil, fmt.Errorf("no entry %q", segments[i])
-			}
-			n = child
-		case *template:
-			child, ok := c.fields[segments[i]]
-			if !ok {
-				return nil, fmt.Errorf("no field %q", segments[i])
-			}
-			n = child
-		case *choice:
-			return nil, fmt.Errorf("%q steps through a %d-way choice", segments[i], len(c.items))
-		default:
-			return nil, fmt.Errorf("cannot descend into %T at %q", n, segments[i])
 		}
+		child, ok := g.children[segments[i]]
+		if !ok {
+			return nil, nil, nil, fmt.Errorf("no entry %q", segments[i])
+		}
+		n = child
 	}
 	if _, ok := n.(*group); ok {
-		return nil, fmt.Errorf("names a folder, not a value")
+		return nil, nil, nil, fmt.Errorf("names a folder, not a value")
 	}
-	return n, nil
+	return segments[:i], n, segments[i:], nil
 }
 
-// refTokens returns just the {..path} reference names among a format's field
+// refTokens returns the {..path} names a format reads, as tokens or as operands.
-// tokens (linkRefs binds each into the template's fields).
 func refTokens(format string) []string {
 	var refs []string
-	for _, name := range fieldTokens(format) {
+	seen := map[string]bool{}
-		if isRef(name) {
+	for _, name := range append(fieldTokens(format), operandTokens(format)...) {
+		if isRef(name) && !seen[name] {
+			seen[name] = true
 			refs = append(refs, name)
 		}
 	}
@@ -276,27 +332,27 @@ func refTokens(format string) []string {
 }
 
 // renderEdge is a child a node renders into, labelled by what reaches it (a field
-// name, reference, or choice index) for a readable cycle report. operand marks a
+// name, reference, or choice index) for a readable cycle report. operand names
-// label that is a {calc()} operand name rather than a token, so an error can name
+// the builtin when the label is its operand rather than a token, so an error can
-// it the way the author wrote it.
+// name it the way the author wrote it.
 type renderEdge struct {
 	to      node
 	label   string
-	operand bool
+	operand string
 }
 
 // reached names an edge as the author spelled it, the vocabulary boundReaders uses
 // for the sibling fence.
 func (e renderEdge) reached() string {
-	if e.operand {
+	if e.operand != "" {
-		return fmt.Sprintf("calc operand %q", e.label)
+		return fmt.Sprintf("%s operand %q", e.operand, e.label)
 	}
 	return "{" + e.label + "}"
 }
 
 // renderEdges lists the children rendering n recurses into, mirroring expand: a
-// choice's items, and a template's field/reference tokens plus its calc operands.
+// choice's items, and a template's field/reference tokens plus its operands. A
-// A group renders nothing, so it has no edges.
+// group renders nothing, so it has no edges.
 func renderEdges(n node) []renderEdge {
 	switch n := n.(type) {
 	case *choice:
@@ -307,8 +363,8 @@ func renderEdges(n node) []renderEdge {
 		return es
 	case *template:
 		var es []renderEdge
-		add := func(name string, operand bool) {
+		add := func(name, operand string) {
-			a := splitArm(name)
+			a := splitArm(name, n.refs)
 			c, ok := n.fields[a.key]
 			if !ok {
 				return
@@ -317,12 +373,21 @@ func renderEdges(n node) []renderEdge {
 				es = append(es, renderEdge{leaf, name, operand})
 			}
 		}
-		for _, name := range fieldTokens(n.format) {
+		_ = eachToken(n.format, func(t ftoken) error {
-			add(name, false)
+			if t.kind != 'b' {
-		}
+				return nil
-		for _, name := range calcOperands(n.format) {
+			}
-			add(name, true)
+			if fn, _, isFunc := funcCall(t.body); isFunc {
-		}
+				for _, operand := range tokenOperands(t.body) {
+					add(operand, fn)
+				}
+				return nil
+			}
+			for _, name := range strings.Split(t.body, "|") {
+				add(name, "")
+			}
+			return nil
+		})
 		return es
 	default:
 		return nil

render.go

@@ -143,8 +143,8 @@ func expand(s *session, t *template) string {
 			var operands []string
 			if len(o.operands) > 0 {
 				operands = make([]string, len(o.operands))
-				for j, name := range o.operands {
+				for j, a := range o.operands {
-					operands[j] = readField(s, t, held, arm{name: name, key: name})
+					operands[j] = readField(s, t, held, a)
 				}
 			}
 			b.WriteString(o.call(s, b.String(), operands)) // b.String() is the output so far

template.go

@@ -69,6 +69,9 @@ type builtin struct {
 	// prep parses validated args once, at compile time, into the closure expand calls.
 	prep  func(args []string) callFn
 	check func(fields map[string]node, args []string) error
+	// operands names the fields the call reads, which expand renders for it; nil
+	// for a builtin that reads none.
+	operands func(args []string) []string
 }
 
 // funcCall splits a "{token}" body shaped name(args) into its parts; ok is false
@@ -137,23 +140,9 @@ func checkTokens(format string, fields map[string]node) error {
 				}
 				continue // a root reference; its target is checked at New (see linkRefs)
 			}
-			a := splitArm(name)
+			if err := checkArm(name, fields); err != nil {
-			if err := checkSegments(a); err != nil {
 				return fmt.Errorf("token {%s}: %w", t.body, err)
 			}
-			head, ok := fields[a.key]
-			if !ok {
-				if a.key == "" {
-					return fmt.Errorf("token {%s}: a name is never empty, so this token can name no field", t.body)
-				}
-				if isOption(a.key) {
-					return fmt.Errorf("token {%s}: %q is an option and can never be a field", t.body, a.key)
-				}
-				return fmt.Errorf("token {%s}: no field %q", t.body, a.key)
-			}
-			if err := checkPath(head, a.tail, a.key); err != nil {
-				return fmt.Errorf("token {%s}: field %q: %w", t.body, a.key, err)
-			}
 		}
 		// Last, so an arm broken on its own terms is reported as that: a repeat is
 		// the consequence of such a mistake, not the mistake itself.
@@ -161,6 +150,54 @@ func checkTokens(format string, fields map[string]node) error {
 	})
 }
 
+// checkArm validates one sibling name or path against a template's fields.
+func checkArm(name string, fields map[string]node) error {
+	a := splitArm(name, nil)
+	if err := checkSegments(a); err != nil {
+		return err
+	}
+	head, ok := fields[a.key]
+	if !ok {
+		if a.key == "" {
+			return fmt.Errorf("a name is never empty, so this token can name no field")
+		}
+		if isOption(a.key) {
+			return fmt.Errorf("%q is an option and can never be a field", a.key)
+		}
+		return fmt.Errorf("no field %q", a.key)
+	}
+	if err := checkPath(head, a.tail, a.key); err != nil {
+		return fmt.Errorf("field %q: %w", a.key, err)
+	}
+	return nil
+}
+
+// tokenOperands lists the fields one {token} body reads as operands, empty for a
+// field token or a builtin that reads none.
+func tokenOperands(body string) []string {
+	name, args, ok := funcCall(body)
+	if !ok {
+		return nil
+	}
+	b, known := builtins[name]
+	if !known || b.operands == nil {
+		return nil
+	}
+	return b.operands(args)
+}
+
+// operandTokens lists every operand the builtins in a format read.
+func operandTokens(format string) []string {
+	var names []string
+	_ = eachToken(format, func(t ftoken) error {
+		if t.kind == 'b' {
+			names = append(names, tokenOperands(t.body)...)
+		}
+		return nil
+	})
+	return names
+}
+
 // checkNoRepeatedArm rejects {a|a|b}: an alternation picks its arms evenly, so a
 // repeated one is a second spelling of weight. The error names the spelling that
 // does skew a pick.
@@ -192,10 +229,11 @@ func fieldTokens(format string) []string {
 	return names
 }
 
-// arm is one alternative of a {a|b} token, split into the key naming the node in
+// arm is one alternative of a {a|b} token or one operand, split into the key
-// a template's fields (a sibling field, or the whole "..path" string a reference is
+// naming the node in a template's fields (a sibling field, or the "..path" head a
-// bound under) and the tail of a dotted path into it. A non-empty tail is what makes
+// reference is bound under) and the tail of a dotted path into it. A non-empty
-// the arm a bound draw: its head is drawn once per expansion (see compileOps).
+// tail is what makes the arm a bound draw: its head is drawn once per expansion
+// (see compileOps).
 type arm struct {
 	name  string // as written, and the key a bound draw's value is held under
 	key   string
@@ -203,22 +241,29 @@ type arm struct {
 	steps []string // key per level passed through; the head and leaf hold their own
 }
 
-// splitArm splits one token alternative into key and tail. A reference keeps its
+// splitArm splits one name into key and tail. refs maps a reference to the head
-// dots — linkRefs binds it whole — so only a sibling name reads as a path.
+// linkRefs bound it under; before linking, a reference is whole.
-func splitArm(name string) arm {
+func splitArm(name string, refs map[string]string) arm {
 	if isRef(name) {
-		return arm{name: name, key: name}
+		key, bound := refs[name]
+		if !bound || key == name {
+			return arm{name: name, key: name}
+		}
+		return pathArm(name, key, strings.Split(name[len(key)+1:], "."))
 	}
 	head, tail, dotted := strings.Cut(name, ".")
 	if !dotted {
 		return arm{name: name, key: name}
 	}
-	segs := strings.Split(tail, ".")
+	return pathArm(name, head, strings.Split(tail, "."))
+}
+
+func pathArm(name, key string, segs []string) arm {
 	var steps []string
 	for i := 0; i < len(segs)-1; i++ { // every level except the leaf's own
-		steps = append(steps, head+"."+strings.Join(segs[:i+1], "."))
+		steps = append(steps, key+"."+strings.Join(segs[:i+1], "."))
 	}
-	return arm{name: name, key: head, tail: segs, steps: steps}
+	return arm{name: name, key: key, tail: segs, steps: steps}
 }
 
 // checkNoOverlap rejects a format that both renders a level and reads a path into
@@ -226,8 +271,8 @@ func splitArm(name string) arm {
 // level's held draw while rendering the level expands it afresh, so their values
 // would disagree. Names are compared in sorted order, so which pair is reported
 // does not depend on where the tokens sit.
-func checkNoOverlap(format string, bound map[string]string) error {
+func checkNoOverlap(format string, bound map[string]string, refs map[string]string) error {
-	names := boundReaders(format, bound)
+	names := boundReaders(format, bound, refs)
 	// Stable over one format-order scan, so two readers of one name (a token and a
 	// calc operand both naming "p") are reported as the format writes them.
 	sort.SliceStable(names, func(i, j int) bool { return names[i].name < names[j].name })
@@ -245,23 +290,24 @@ func checkNoOverlap(format string, bound map[string]string) error {
 type reader struct{ name, label string }
 
 // boundReaders lists every way a format reaches a bound field, in the order the
-// format writes them. A calc operand renders its field, so it names a level exactly
+// format writes them. An operand renders its field, so it names a level exactly
 // as a token does; one scan finds both, which is what puts them in one order.
-func boundReaders(format string, bound map[string]string) []reader {
+func boundReaders(format string, bound map[string]string, refs map[string]string) []reader {
 	var names []reader
 	_ = eachToken(format, func(t ftoken) error {
 		if t.kind != 'b' {
 			return nil
 		}
-		if _, _, isFunc := funcCall(t.body); isFunc {
+		if fn, _, isFunc := funcCall(t.body); isFunc {
-			for _, operand := range calcTokenOperands(t.body) {
+			for _, operand := range tokenOperands(t.body) {
-				if _, isBound := bound[operand]; isBound {
+				a := splitArm(operand, refs)
-					names = append(names, reader{operand, fmt.Sprintf("calc operand %q", operand)})
+				if _, isBound := bound[a.key]; isBound {
+					names = append(names, reader{a.name, fmt.Sprintf("%s operand %q", fn, operand)})
 				}
 			}
 			return nil
 		}
-		for _, a := range splitArms(t.body) {
+		for _, a := range splitArms(t.body, refs) {
 			if _, isBound := bound[a.key]; isBound {
 				names = append(names, reader{a.name, "token {" + a.name + "}"})
 			}
@@ -290,11 +336,11 @@ func checkSegments(a arm) error {
 }
 
 // splitArms splits a token body's '|' alternatives.
-func splitArms(body string) []arm {
+func splitArms(body string, refs map[string]string) []arm {
 	parts := strings.Split(body, "|")
 	arms := make([]arm, len(parts))
 	for i, p := range parts {
-		arms[i] = splitArm(p)
+		arms[i] = splitArm(p, refs)
 	}
 	return arms
 }
@@ -312,30 +358,38 @@ type op struct {
 	lit  string // kind 'l'
 	arms []arm  // kind 'f': the '|' alternatives, split into key and path once
 	call callFn
-	// operands names the sibling fields a {calc()} reads, in the order calcVars
+	// operands are the fields the builtin reads, in the order its operands func
-	// fixed; expand reads them before the call. nil for every other builtin.
+	// fixed; expand reads them before the call. nil for a builtin that reads none.
-	operands []string
+	operands []arm
 }
 
 // compileOps turns a format string into ops, and returns the size of its literal
 // text to size the render buffer, plus two sets. bound is the levels the format
 // addresses by dotted path, each mapped to the first path reading it, which is what
 // the overlap fences name. held is every name drawn once per expansion — those
-// levels, plus the siblings a {calc()} reads, so an operand shown is the operand
+// levels, plus the fields an operand reads, so an operand shown is the operand
 // computed. Both are nil when the format needs neither, so data that uses neither
 // carries no render-time cost. Call checkTokens first: it is what proves the scan
 // and every token are valid.
-func compileOps(format string) ([]op, int, map[string]string, map[string]bool) {
+func compileOps(format string, refs map[string]string) ([]op, int, map[string]string, map[string]bool) {
 	var ops []op
 	var lit strings.Builder
 	var bound map[string]string
 	var held map[string]bool
 	grow := 0
-	hold := func(name string) {
+	hold := func(a arm) {
 		if held == nil {
 			held = map[string]bool{}
 		}
-		held[name] = true
+		held[a.key] = true
+		if len(a.tail) > 0 {
+			if bound == nil {
+				bound = map[string]string{}
+			}
+			if _, named := bound[a.key]; !named {
+				bound[a.key] = a.name // the first path reading it, for error messages
+			}
+		}
 	}
 	flush := func() {
 		if lit.Len() > 0 {
@@ -351,22 +405,18 @@ func compileOps(format string) ([]op, int, map[string]string, map[string]bool) {
 		case 'b':
 			flush()
 			if name, args, ok := funcCall(t.body); ok {
-				operands := calcTokenOperands(t.body)
+				var operands []arm
-				for _, operand := range operands {
+				for _, operand := range tokenOperands(t.body) {
-					hold(operand) // a calc renders its operand, so the expansion holds that draw
+					a := splitArm(operand, refs)
+					hold(a) // the builtin renders its operand, so the expansion holds that draw
+					operands = append(operands, a)
 				}
 				ops = append(ops, op{kind: 'b', call: builtins[name].prep(args), operands: operands})
 			} else {
-				arms := splitArms(t.body)
+				arms := splitArms(t.body, refs)
 				for _, a := range arms {
 					if len(a.tail) > 0 {
-						if bound == nil {
+						hold(a)
-							bound = map[string]string{}
-						}
-						if _, named := bound[a.key]; !named {
-							bound[a.key] = a.name // the first path reading it, for error messages
-						}
-						hold(a.key)
 					}
 				}
 				ops = append(ops, op{kind: 'f', arms: arms})

transform_test.go

@@ -6,8 +6,8 @@ func TestTransforms(t *testing.T) {
 	f := engine(1)
 	for src, want := range map[string]string{
 		`{"format":"{uppercase(x)}|{lowercase(x)}|{ascii(x)}","x":"Åsa Ödegård-Nuñez"}`: "ÅSA ÖDEGÅRD-NUÑEZ|åsa ödegård-nuñez|Asa Odegard-Nunez",
-		`{"format":"{lowercase(ascii(x))}","x":"Åsa"}`:                              "asa",
+		`{"format":"{lowercase(ascii(x))}","x":"Åsa"}`:                                  "asa",
-		`{"format":"{ascii(x)}","x":"Ærø ß 日本"}`:                                "AEro ss ",
+		`{"format":"{ascii(x)}","x":"Ærø ß 日本"}`:                                        "AEro ss ",
 	} {
 		if got := mustRender(t, f, src); got != want {
 			t.Errorf("render(%s) = %q, want %q", src, got, want)