diff --git a/AGENTS.md b/AGENTS.md index 57c2f88..a33d167 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,7 @@ In [docs/decisions.md](docs/decisions.md): - `parent` names the link column and the table alike - After a row, a path names a column or a linked table - A selected row is fixed, not drawn, and an unnamed read beside it is refused +- A link column after a row steps up to the parent row, and a path may not end on it - A parent row with no child row is a load error - The choice-of-rows fence guards a data file's root, and requires string fields - A table is a record of string columns diff --git a/README.md b/README.md index a1d80a6..55ac723 100644 --- a/README.md +++ b/README.md @@ -823,8 +823,9 @@ the Development section below, and who ships a register the four above then draw 3. **Valid by construction** — every value passes the check its real consumer applies; facts that belong together come from one draw, within a value and across categories. -4. **Templates are intuitive, and text means what it says** — a template renders what - every writer reading it would expect, judged by simulated writers from the Audience. +4. **Templates are intuitive, and text means what it says** — a template, and every + path in it, renders what every writer reading it would expect, judged by simulated + writers from the Audience. A format renders as written; only `{…}` varies, random characters included (`{digits(3)}`), and a selected row, `[SE]`, is that row wherever it is written. Where two writers could expect different outputs, the template is a load error diff --git a/docs/decisions.md b/docs/decisions.md index db319fb..fe68bb7 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -380,6 +380,24 @@ exactly one row. Checked against three simulated template writers from the Audience, who agreed on each case but the last, where two expected a render and all three accepted the refusal. +## A link column after a row steps up to the parent row, and a path may not end on it + +Decided 2026-09-27 by the maintainer, for goal 4; valid while a link column holds the +parent's key. + +- Where a segment follows, the link column's name reads the parent row, one level per + step, chained: `city[Oslo].country.name` renders `Norway`, and + `geo.SE.locality[Lund].municipality.region.name` Lund's region. +- A path ending on it is refused, naming the parent's key column and the columns its + format reads: `city[Oslo].country` could be `NO` or `Norway`, so the error names + `city[Oslo].country.alpha2` and `city[Oslo].country.name`. +- A route through another row is not a second spelling of a selection: + `city[Oslo].country.name` and `country[NO].name` both load, as `[1281]` and `[Lund]` do. + +Checked against three simulated template writers from the Audience: all three read the +parent row where a segment followed, and they split between the code and the name where +the path ended. + ## A parent row with no child row is a load error A descendant is drawn inside the nearest pinned ancestor, so every ancestor row must diff --git a/todo.md b/todo.md index e292442..4e9cc85 100644 --- a/todo.md +++ b/todo.md @@ -172,14 +172,19 @@ by a `data-import/` script, as README goal 12 asks. ### Library and CLI +- Step up from a row to its parent as the decision "A link column after a row steps up + to the parent row, and a path may not end on it" states: `city[Oslo].country.name` is + a load error today, and `city[Oslo].country` renders the cell `NO`. Correct the + README's `city[Oslo].country` example to match. - Render selected rows as the decision "A selected row is fixed, not drawn, and an unnamed read beside it is refused" states: `New` refuses `{/misc.territory[SE].capital} / {/misc.territory[FI].capital}` today, and a choice whose items select different rows. Have the refusal of an unnamed read name the - rewrite through each selection, selecting an ancestor of the selected row by key: - beside `{/geo.SE.locality[Lund].name}`, `{/geo.SE.municipality.name}` names none - today, where `{/geo.SE.municipality[1281].name}` holds. Scope the README's "A reference - path into a category is held" to a path that selects no row. + rewrite through each selection: beside `{/geo.SE.locality[Lund].name}`, + `{/geo.SE.municipality.name}` names none today, where + `{/geo.SE.locality[Lund].municipality.name}` holds once the step up above lands. + Scope the README's "A reference path into a category is held" to a path that + selects no row. - Report the same error every load for a table with two bad options, and for a folder with two unnamed rows files: `readTableOptions` and `loadDir` return on the first in Go's map order. @@ -220,24 +225,6 @@ by a `data-import/` script, as README goal 12 asks. ### Open questions to settle -- Decide how a path steps from a row up to its parent row, one level per step, chained. - Three simulated template writers expected `{/geo.SE.locality[Lund].municipality.name}` - to read Lund's municipality; today it is a load error, since `.municipality` after a - row is the link column's cell, `city[Oslo].country` rendering `NO`. The options: - - The name means the parent row where a segment follows, and the cell where the path - ends. It gives a refused spelling a meaning, so a minor, and extends "After a row, a - path names a column or a linked table" from child tables to the parent. - - The name always means the parent row, rendering through its format where the path - ends: `city[Oslo].country` renders `Norway`, the cell stays reachable through the - parent's key column. A change - to what exists, so a major, and a record's `country` column then holds the key while - the path renders the name. - - Goal 4 refuses a path ending on the name, since a writer could expect the code or the - name, naming the parent's key column and `.name`. A major. - - Each option gives `locality[Lund].municipality.name` and - `municipality[1281].name` one result, so goal 4's one spelling per result refuses one - of them, and the rewrite the selected-row item above names follows that choice. - Decide whether a goal 5 violation joins the comprehension gate's exception list: the `{/sel}|{/sel}` panic waits behind the whole round at 5.9, and `{/geo.SE.locality}|{/geo.SE.municipality}` mispairs the shipped data meanwhile, though a