diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bb2597..a62c8c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ replacement, and each removed path, column or flag. drawing afresh. `New` refuses a `..` naming anything but the parent table, and a selector after a `..`. - A path, given to `Fake` or the CLI or referenced in a template, may not read into a - level carrying a `repeat`, and `List` advertises none that does: where `x` carries + level carrying a `repeat`, and `List` advertises no such path: where `x` carries `"repeat": 3`, `Fake("x.a")` fails naming the level `x`, and `Fake("x")` renders it whole. - Every `{…}` draws afresh, and a name is the one way to keep a pick: `{p.a} {p.b}`, diff --git a/README.md b/README.md index 619f6ac..095ffbc 100644 --- a/README.md +++ b/README.md @@ -796,7 +796,7 @@ token {p.postal-code}: not every variant of this 2-way choice carries "postal-co The sub-fields stay addressable — `Fake("address.place.locality")` renders, and `List` advertises it. A path may not read into a level carrying a `repeat`, and `List` -advertises none that does; read that level whole. +advertises no such path; read that level whole. ### Performance diff --git a/doc.go b/doc.go index ef85520..ea7e56d 100644 --- a/doc.go +++ b/doc.go @@ -29,7 +29,7 @@ package fejkdata // and the value each path read: `drawMemo`. // - pin — fixing which row of a table one path, or one named pick, uses: // `pinSet`, `namedPick.pins`, `table.drawStep`. -// - family — a table and every table reaching it through a chain of links -// `table.linkParent` makes. +// - family — a table and every table reaching it through a chain of parent +// links (`table.linkParent`). // - fence — a load-time check, run over each category, template or struct as it // loads or compiles, so rendering a compiled tree cannot fail. diff --git a/docs/decisions.md b/docs/decisions.md index 7bc2f1f..44c3f70 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -839,8 +839,8 @@ each value one writer would spread that knot across packages, behind forwarding every public method. The draw state, the grammar, `DataType`, what a proof knows of a value, the builtins, the reading of data files and a table's rows read no engine type, so each sits in a package under `internal/`, behind the import list `imports_test.go` checks. -A table's rows reach the engine table owning them as their owner, a value of a type parameter. Valid -until `todo.md` item 107 moves the engine. +A rows table holds the engine table owning it as a value of a type parameter, so +`internal/rows` imports no engine type. Valid until `todo.md` item 107 moves the engine. ## Goal 5.1's `{…}` covers `{{`, `}}` and a lone `}`, so the goal names no escape diff --git a/fejkdata.go b/fejkdata.go index b160124..451d273 100644 --- a/fejkdata.go +++ b/fejkdata.go @@ -113,8 +113,8 @@ func (c config) load() (folder, error) { } // List returns the sorted dotted paths Fake renders: each category and every field, -// column and linked table below it, a direct descent at a time, stopping at a level -// carrying a repeat. A choice consumes no segment, so a path continues through one +// column and linked table below it, a direct descent at a time, listing a level +// carrying a repeat but nothing below it. A choice consumes no segment, so a path continues through one // only where every variant carries it. func (f *Generator) List() []string { f.mu.Lock() @@ -126,8 +126,8 @@ func (f *Generator) List() []string { // paths lists the dot paths addressable from n, relative to it, where "" is n // itself. A folder has no value of its own, so it contributes only its children's. -// intoRepeats lists the fields under a level carrying a repeat too, which a path -// reaches only to be refused. +// With intoRepeats, it also lists the paths below a level carrying a repeat, so a path +// there meets the repeat's refusal. func paths(n node, intoRepeats bool) []string { switch n := n.(type) { case *folder: @@ -163,7 +163,6 @@ func paths(n node, intoRepeats bool) []string { } } -// appendUnder appends each of ps to out under name. func appendUnder(out []string, name string, ps []string) []string { for _, p := range ps { out = append(out, join(name, p)) diff --git a/internal/grammar/path.go b/internal/grammar/path.go index b3259fb..8774b49 100644 --- a/internal/grammar/path.go +++ b/internal/grammar/path.go @@ -139,7 +139,7 @@ func HasSelector(segs []string) bool { func SelectorOf(seg string) string { return seg[1 : len(seg)-1] } // inSelector is what a selector may not contain: the path grammar reserves brackets and -// braces, and a quote or a bar would make the selector no path and no token arm. +// braces, and inside a token a quote would end the path and a bar would split the token into arms. const inSelector = `[]{}"|` // UnspellableInSelector is the first character of s a selector cannot spell, "" where there is none. diff --git a/internal/rows/pins.go b/internal/rows/pins.go index 6e9d5ce..b311a12 100644 --- a/internal/rows/pins.go +++ b/internal/rows/pins.go @@ -28,7 +28,7 @@ func (p *Pins[O]) Pinned(t *Table[O]) (int, bool) { return r, ok } -// MustRow is the row pinned for t, which the caller pinned. +// MustRow is the row pinned for t; the caller must have pinned one. func (p *Pins[O]) MustRow(t *Table[O]) int { r, ok := p.Pinned(t) if !ok { diff --git a/internal/rows/rows.go b/internal/rows/rows.go index f361200..261d781 100644 --- a/internal/rows/rows.go +++ b/internal/rows/rows.go @@ -141,7 +141,7 @@ func (t *Table[O]) appendRow(row string, line int) error { return nil } -// bindOptions resolves each option to its column, refuses a name reading the key column, and +// bindOptions resolves each option to its column, refuses a name option naming the key column, and // proves what the options claim of the cells: a key is unique, a weight a positive number. func (t *Table[O]) bindOptions() error { o := t.options @@ -253,8 +253,8 @@ func (t *Table[O]) checkSelectorCells() error { } // Link links t to p, the table its link column names, after proving p has a key, every -// link cell is one, and every row of p is linked to. sibling is the table beside t -// named name, nil where none is. It is the only writer of a table's parent and children. +// link cell is one, and every row of p is linked to. sibling returns the table beside t +// named name, or nil. Link is the only writer of a table's parent and children. // docs/decisions.md#a-parent-row-with-no-child-row-is-a-load-error func (t *Table[O]) Link(p *Table[O], sibling func(name string) *Table[O]) error { name := t.header[t.parentIndex] @@ -307,7 +307,7 @@ func (t *Table[O]) checkAncestors(p *Table[O], sibling func(name string) *Table[ return nil } -// Children is the tables linked to t, by segment. +// Children is the tables linked to t, sorted by segment. func (t *Table[O]) Children() []*Table[O] { out := make([]*Table[O], 0, len(t.children)) for _, c := range t.children { @@ -411,9 +411,9 @@ func (t *Table[O]) drawUnder(s *drawstate.State, pr int) int { return rows[s.Weighted(lookup.childCum[k])] } -// DrawIn is the row of t inside the rows p pins: the one pinned in p, else one drawn inside the nearest -// pinned ancestor — its parent drawn inside that first where the ancestor is further up — or -// over the whole table, and pinned with its ancestors. +// DrawIn returns the row of t that p pins. Where p pins none, it draws one inside the nearest +// ancestor p pins, drawing t's parent there first when that ancestor is higher up; with no +// ancestor pinned, it draws over the whole table. It pins the row drawn and its ancestors' rows in p. func (t *Table[O]) DrawIn(s *drawstate.State, p *Pins[O]) int { if r, ok := p.Pinned(t); ok { return r diff --git a/internal/rows/rows_test.go b/internal/rows/rows_test.go index 16f893a..23c419e 100644 --- a/internal/rows/rows_test.go +++ b/internal/rows/rows_test.go @@ -16,7 +16,7 @@ func parse(t *testing.T, segment, data string, o Options) *Table[string] { return tb } -// family is a country table with two cities linked to it, each with a name only unique inside its country. +// family is a country table, SE and NO, and a city table linked to it, where Borg names a city in each country. func family(t *testing.T) (country, city *Table[string]) { t.Helper() country = parse(t, "country", "code\tname\nSE\tSweden\nNO\tNorway\n", Options{Key: "code"}) diff --git a/path.go b/path.go index 1667f71..81d0d5c 100644 --- a/path.go +++ b/path.go @@ -146,8 +146,8 @@ func repeatLevelError(level string) error { return fmt.Errorf("the level %q carries a repeat, so a path cannot read one draw of it; read %q whole", level, level) } -// pathPos is where a walk stands: the node reached, the tail left to walk from it, and whether -// it descended there, as route reads it. +// pathPos is where a walk stands: the node reached, the tail left to walk from it, and route's +// descended flag for it. type pathPos struct { n node tail []string @@ -156,9 +156,9 @@ type pathPos struct { func (p pathPos) more() bool { return len(p.tail) > 0 || p.descended } -// takeStep moves at past the step its tail starts with, from its node, which is no choice, and -// appends what it takes to steps: a field, or the route a table passes. whole is the full path, -// at.tail its unwalked end, and level names its head in errors. +// takeStep takes the first step of at.tail from at.n, which must not be a choice, moves at past +// it, and appends the step to steps: a field, or the route through a table. whole is the full +// path; level is the prefix an error puts before it. func takeStep(at *pathPos, whole []string, level string, steps []pathStep, pins *pinSet) ([]pathStep, error) { i := len(whole) - len(at.tail) switch x := at.n.(type) { diff --git a/path_test.go b/path_test.go index 5a3afe1..0120f0a 100644 --- a/path_test.go +++ b/path_test.go @@ -62,7 +62,6 @@ func TestDescendIntoStringErrors(t *testing.T) { } } -// TestPathRefusesALevelCarryingARepeat holds a caller's path to the rule a reference obeys. func TestPathRefusesALevelCarryingARepeat(t *testing.T) { dir := writeData(t, map[string]string{ "outer": `{"format":"{inner}","inner":{"format":"{a}","a":"v","repeat":3,"separator":","}}`, diff --git a/todo.md b/todo.md index d14c233..039bc7d 100644 --- a/todo.md +++ b/todo.md @@ -464,7 +464,7 @@ Its doc says render failure, and it wraps what `NewTemplate` and `NewRecordTempl ### 116. Turn a row index into its rows file's line in one function. -Today `namedNode`'s cell line in `graph.go` and each site in `internal/rows` add the header line and the one-based count. +Today `namedNode`'s cell line in `graph.go`, `table.checkCells` and each site in `internal/rows` add the header line and the one-based count. ### 56. Build on a manual run of `test.yml`.