Answer the step-up question at goal level: a path renders what every writer expects, so a link column steps up to its parent and may not end a path

This commit is contained in:
2026-09-27 16:41:31 +02:00
committed by Lillem4n
parent 543b21d99f
commit f8e9d9a280
4 changed files with 31 additions and 24 deletions
+1
View File
@@ -72,6 +72,7 @@ In [docs/decisions.md](docs/decisions.md):
- `parent` names the link column and the table alike - `parent` names the link column and the table alike
- After a row, a path names a column or a linked table - 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 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 - 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 - The choice-of-rows fence guards a data file's root, and requires string fields
- A table is a record of string columns - A table is a record of string columns
+3 -2
View File
@@ -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 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 applies; facts that belong together come from one draw, within a value and
across categories. across categories.
4. **Templates are intuitive, and text means what it says** — a template renders what 4. **Templates are intuitive, and text means what it says** — a template, and every
every writer reading it would expect, judged by simulated writers from the Audience. 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 A format renders as written; only `{…}` varies, random characters included
(`{digits(3)}`), and a selected row, `[SE]`, is that row wherever it is written. (`{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 Where two writers could expect different outputs, the template is a load error
+18
View File
@@ -380,6 +380,24 @@ exactly one row.
Checked against three simulated template writers from the Audience, who agreed on each 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. 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 parent row with no child row is a load error
A descendant is drawn inside the nearest pinned ancestor, so every ancestor row must A descendant is drawn inside the nearest pinned ancestor, so every ancestor row must
+9 -22
View File
@@ -172,14 +172,19 @@ by a `data-import/` script, as README goal 12 asks.
### Library and CLI ### 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 - Render selected rows as the decision "A selected row is fixed, not drawn, and an
unnamed read beside it is refused" states: `New` refuses unnamed read beside it is refused" states: `New` refuses
`{/misc.territory[SE].capital} / {/misc.territory[FI].capital}` today, and a choice `{/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 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: rewrite through each selection: beside `{/geo.SE.locality[Lund].name}`,
beside `{/geo.SE.locality[Lund].name}`, `{/geo.SE.municipality.name}` names none `{/geo.SE.municipality.name}` names none today, where
today, where `{/geo.SE.municipality[1281].name}` holds. Scope the README's "A reference `{/geo.SE.locality[Lund].municipality.name}` holds once the step up above lands.
path into a category is held" to a path that selects no row. 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 - 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 folder with two unnamed rows files: `readTableOptions` and `loadDir` return on the
first in Go's map order. first in Go's map order.
@@ -220,24 +225,6 @@ by a `data-import/` script, as README goal 12 asks.
### Open questions to settle ### 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 - 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 `{/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 `{/geo.SE.locality}|{/geo.SE.municipality}` mispairs the shipped data meanwhile, though a