diff --git a/AGENTS.md b/AGENTS.md index c519a01..ec26f1d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,7 +73,7 @@ In [docs/decisions.md](docs/decisions.md): - 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 selector names a row by its key alone +- A table selects by one key column, a code, never a free-form name - 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 @@ -94,7 +94,6 @@ In [docs/decisions.md](docs/decisions.md): - A title is a table under `sex` - A table owns the spelling of a selector on it - No builtin reads the clock, so a date is bounded by days, never by an age -- A name column without a key resolves inside its parent - `misc` is what every locale shares - A register's canonical spelling loses to the one its domain writes - `misc.territory` is the spine, and a `misc` table naming a territory links to it @@ -103,7 +102,7 @@ In [docs/decisions.md](docs/decisions.md): - `misc.port` selects by number, and carries no `name` - `misc.car` is one flat table, not a make linked to its models - `misc.territory` names its sovereign in a column, and there is no `misc.country` table -- `misc.loglevel` is a table keyed by the code, rendering POSIX's keyword +- `misc.loglevel` is a table keyed by POSIX's keyword, carrying the code - `misc.tld` keys carry the leading dot, where other tables key on a bare code - `misc.tld` is a table of its own, and `misc.territory.tld` stays a column - `misc.territory` carries a currency code, it does not link to `misc.currency` diff --git a/docs/decisions.md b/docs/decisions.md index 3b7788d..33e2767 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -385,8 +385,8 @@ parent. A row is selected or drawn alike. - Where a segment follows, the link column's name reads the parent row, one level per step, chained: `city[Oslo].country.name` renders `Norway`, `locality.municipality.name` - the drawn locality's municipality, and `geo.SE.locality[Lund].municipality.region.name` - Lund's region. + the drawn locality's municipality, and + `geo.US.locality[1714000].municipality.region.name` Chicago's state. - A path ending on it is refused at `New`, `NewTemplate` and `Fake` alike, naming the parent's key column and the parent's format spelled as paths: with a `country` format of `{name} ({alpha2})`, `city[Oslo].country` names `city[Oslo].country.alpha2` and @@ -404,13 +404,21 @@ Checked against three simulated template writers from the Audience: all three re parent row where a segment followed, and they split between the code and the name where the path ended. -## A selector names a row by its key alone +## A table selects by one key column, a code, never a free-form name Decided 2026-09-27 by the maintainer, for goal 4's one spelling per result; valid while -every table either has a `key` or names its rows inside a parent. A table with a `key` -selects by it alone: `country[NO]` loads, and `country[Norway]` is refused naming -`[NO]`, found by the row whose cell spells the selector. A table with no `key` selects by -its `name` inside its parent, which is the key it has. +the key is the code a user writes, as a database keys a table. `country[NO]` loads, and +`country[Norway]` is refused naming `[NO]`, found by the row whose cell spells the +selector. The key is the friendliest code the register holds, `misc.territory[SE]` and +`misc.currency[EUR]`, and only where it holds none an id the import assigns and never +moves to another row. There is no `name` option. + +- `misc.loglevel` keys on the keyword, `[err]`, which a configuration writes. +- `misc.tld` keys on the ASCII form, `[.xn--p1ai]`, the one DNS carries. +- `geo.US.locality` keys on the Census GEOID, `[1714000]` for Chicago. +- `geo.SE.locality` keys on an assigned id: a postort has no code of its own. +- A name table, `first-name`, `last-name` and `title`, carries no key, so it is drawn + from and never selected. ## A parent row with no child row is a load error @@ -546,8 +554,7 @@ are a curated proportion rather than bearers anyone counted. A reference reaches a table by a path that carries no selector — `sv_SE.person.first` reads `first-name` through `sex` — so the walk that resolved a name cannot say where a reader would type one. The table's own location can, which is why it keeps its path, and -why an ambiguity error names `sv_SE.sex[f].first-name[Kim]` rather than the table's own -name. +why an error names `geo.SE.municipality[1281]` rather than `municipality[1281]`. ## No builtin reads the clock, so a date is bounded by days, never by an age @@ -555,13 +562,6 @@ An `age(min,max)` would make a seeded fixture change with the day it runs on, wh what a seed exists to prevent; a birthdate for someone 20 to 60 is `date(1966-01-01,2006-12-31,…)`, re-pinned as any fixture is. -## A name column without a key resolves inside its parent - -A given name both sexes carry is a row under each, so `name` cannot be the key; the -parent's row tells the two apart, `sex[f].first-name[Kim]`, the ambiguity error spells -each row inside its parent, and a name repeating inside one parent row is refused at -load, since nothing could then select it. - ## `misc` is what every locale shares A category whose facts differ by country belongs in that country's locale, read from the @@ -627,7 +627,7 @@ own family; a test proves every value names a row instead. A territory the regis records no state for stands alone, which is `EH` alone, and naming one for it would be a claim fejkdata has no business making. -## `misc.loglevel` is a table keyed by the code, rendering POSIX's keyword +## `misc.loglevel` is a table keyed by POSIX's keyword, carrying the code A flat list of names carries neither the code a PRI encodes nor a selector reaching it, and goal 3 draws the two as one fact. The canonical spelling losing to the one its diff --git a/todo.md b/todo.md index 3117b8d..a90176e 100644 --- a/todo.md +++ b/todo.md @@ -178,23 +178,28 @@ by a `data-import/` script, as README goal 12 asks. cell `NO`, as `locality.municipality` does, which `List` stops advertising. Replace the README's `city[Oslo].country` example with `fejkdata -d ./mydata 'city[Oslo].country.name'`, rendering `Norway`. -- Select a row by its key alone, as the decision "A selector names a row by its key - alone" states, once the open question on each table's key is settled: - `geo.SE.municipality[Lund]` and `misc.territory[Sweden]` select a row today. +- Key every table as the decision "A table selects by one key column, a code, never a + free-form name" states: `geo.SE.municipality[Lund]` and `misc.territory[Sweden]` select + a row today. - Have a selector that misses name the key of every row whose cell spells it, matched without case, else say the table selects by its key: `misc.territory[Sweden]` and `misc.territory[se]` name `[SE]`, `misc.protocol[tcp]` - its key, and `misc.loglevel[Error]` the row a column spells `Error` in. - - Refuse a `name` option beside `key`, which then selects nothing, drop it from the - shipped tables, and delete the load check refusing a name that spells another row's - key. + its key, and `misc.loglevel[Error]` `[err]`. + - Delete the `name` option, and the load checks it carries: a name spelling another + row's key, and a name repeating inside its parent. + - Key `misc.loglevel` on `keyword`, and `geo.SE.locality` on an id `data-import/geo-se.py` + assigns and keeps across imports, linking `street` and `postal-code` by it. + - Drop `key` from `last-name` and `sv_SE.title`. - Rewrite what selects by name: in README.md, "selected by key or name", `misc.currency[Euro]`, "selects by either spelling", `misc.tld[.рф]`, - `misc.loglevel[err]` and "the code and the keyword do", the `geo` table's "by code - or name", "by USPS abbreviation or name" and "by GEOID or name", - `geo.SE.region[Skåne län]`, `geo.US.region[IL].locality[Springfield]`, "selection by - name", the `name` option's paragraph and "`[key]` or `[name]`"; in CHANGELOG.md, "a - path selects a row by key or name", "a name spelling another row's key" and + `misc.loglevel[3]`, `misc.loglevel[err]` and "the code and the keyword do", the `geo` + table's "by code or name", "by USPS abbreviation or name", "by GEOID or name" and + "by name", `geo.SE.locality[Lund]`, `geo.SE.region[Skåne län]`, + `geo.US.region[IL].locality[Springfield]`, "selection by name", + `first-name[Taylor]`, `first-name[Kim]`, `sv_SE.title[dr]`, the `name` option's + paragraph and "`[key]` or `[name]`"; `locality[Lund]` in docs/decisions.md; in + CHANGELOG.md, "a path selects a row by key or name", "a name spelling another row's + key", "a name repeating inside one parent row", "A `name` without a `key`" and `misc.tld[.рф]`. - Render selected rows as the decision "A selected row is fixed, not drawn, and an unnamed read beside it is refused" states: `New` refuses @@ -238,16 +243,6 @@ by a `data-import/` script, as README goal 12 asks. ### Open questions to settle -- Decide which spelling each shipped table selects by, now a selector names its key - alone. Keeping today's key loses `geo.US.region[IL].locality[Springfield]` to a - numeric GEOID, `misc.loglevel[err]` to `[3]`, `misc.tld[.рф]` to `[.xn--p1ai]`, - `misc.currency[Euro]`, `misc.protocol`'s second spelling and - `geo.SE.region[Skåne län]`. The tables carrying both today: `geo.SE` and `geo.US` - region, municipality and US locality, `misc` currency, httpstatus, language, - loglevel, mimetype, protocol, territory and tld, and both locales' `sex`. Decide too - whether the `name` option, left meaning "the key inside a parent", keeps its name. - Record each answer in `docs/decisions.md`, amending the `misc.tld` and `misc.loglevel` - entries it changes. - 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