From adba2510db2e8abe1e13017eea2b03cc0f94583e Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 11 Oct 2026 21:00:44 +0200 Subject: [PATCH] Answer prose round 1: the CLI decision says what keeping cli off internal/ buys, the changelog and Library sentences hold one idea each, and item 185 names the three wordings its builder rules on --- CHANGELOG.md | 6 +++--- README.md | 5 ++--- cli/cli.go | 10 +++++----- cli/cli_test.go | 3 +-- docs/decisions.md | 6 +++--- todo.md | 4 ++-- 6 files changed, 16 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e56491a..9c4fab5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -139,9 +139,9 @@ replacement, and each removed path, column or flag. is given. A manifest's `namespace` mounts its source under a dot path. - Package `github.com/larvit/fejkdata/cli` is the `fejkdata` command: `cli.Main(modules...)` runs it over the modules given, and returns its exit code, so a `main` package calling - `cli.Main(append(data.Modules(), mydata)...)` builds a CLI carrying your own data, which - names itself by its file in its help and errors. `--version` prints the fejkdata - module's version, after the custom CLI's own where the CLI is one. + `cli.Main(append(data.Modules(), mydata)...)` builds a CLI carrying your own data. That + CLI names itself in its help and errors by the file it runs from, and its `--version` + prints its own module's version before fejkdata's. - A data source whose root holds a `.fejkdata.json` manifest with an `index` loads each category on the first call reaching it, as each shipped module does. Data failing to load, in `New` or on that first call, gives an error matching `ErrLoad`, and the CLI exits 1. diff --git a/README.md b/README.md index 93e9817..ee26ad4 100644 --- a/README.md +++ b/README.md @@ -362,8 +362,8 @@ ok, err := fejkdata.IsTemplate(arg) // an inline template by its shape, el | `WithDataPath(dir)` | layer a directory; repeat to layer several, the last wins a clash | | `WithDataFS(modules...)` | layer modules in order, each an `fs.FS`: a shipped package's `Modules()...`, or your own `embed.FS`; `WithDataFS()` loads none | -A shipped package's `Modules()` is its `FS` and every module it reads, a locale's country's -places among them, which its package imports, so your program links only what you read. +A shipped package's `Modules()` returns its own `FS` and every module it reads, such as a +locale's country's places. Your program links only the packages it imports. `data.Modules()`, from `github.com/larvit/fejkdata/data`, is every shipped module, and links all of them. Two locales, with `enus` from `github.com/larvit/fejkdata/data/en_US`, are `WithDataFS(append(svse.Modules(), enus.Modules()...)...)`. To stand in your @@ -450,7 +450,6 @@ func main() { os.Exit(cli.Main(append(data.Modules(), mydata)...)) } Add `*.tsv` to the embed where your data holds a table. The CLI takes `fejkdata`'s flags and exit codes, and names itself by the file it runs from in its help and errors. `--no-shipped-data` leaves out the modules passed to `Main`, and `--version` prints your module's version beside the fejkdata version it is built with. -`fejkdata`'s own `main` is `os.Exit(cli.Main(data.Modules()...))`. ## Data format diff --git a/cli/cli.go b/cli/cli.go index e8e5836..1687e1d 100644 --- a/cli/cli.go +++ b/cli/cli.go @@ -1,6 +1,6 @@ // Package cli is the fejkdata command: it renders the template on its stdin with fake // values from the modules it is given and any directories layered over them. A program -// passing its own modules to Main is a fejkdata CLI carrying them, as +// passing its own modules to Main is a fejkdata CLI carrying them, for example // os.Exit(cli.Main(append(data.Modules(), mydata)...)). package cli @@ -544,8 +544,8 @@ func spacedReference(template string, err error) error { return err } -// piped is the command piping template to the command name; some shells' echo reads a -// backslash as an escape, so a template holding one goes through printf. +// piped is the command piping template into the command called name; some shells' echo +// reads a backslash as an escape, so a template holding one goes through printf. func piped(template, name string) string { if strings.ContainsRune(template, '\\') { return "printf '%s' " + shellQuoted(template) + " | " + name @@ -673,8 +673,8 @@ func report(stderr io.Writer, name string, err error) { // the module's. var fejkdataModule = reflect.TypeOf((*fejkdata.Generator)(nil)).Elem().PkgPath() -// versionLine names the fejkdata version the binary is built with, after the main module's -// version under the command name where another module's main package carries the CLI. +// versionLine names the fejkdata version the binary is built with. Where another module's +// main package carries the CLI, the main module's version comes first, under the command name. func versionLine(name string, info *debug.BuildInfo) string { if info == nil { return "fejkdata devel" diff --git a/cli/cli_test.go b/cli/cli_test.go index fb86048..7cad4d4 100644 --- a/cli/cli_test.go +++ b/cli/cli_test.go @@ -17,8 +17,7 @@ import ( ) // shipped holds the shipped modules as read from the checkout, each folder under ../data -// holding a manifest, so these tests link no data package; cmd/fejkdata runs over the -// packages themselves. +// holding a manifest, so these tests link no data package. var shipped = func() []fs.FS { var modules []fs.FS err := filepath.WalkDir(filepath.Join("..", "data"), func(path string, d fs.DirEntry, err error) error { diff --git a/docs/decisions.md b/docs/decisions.md index ab4d34b..29961b5 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -98,9 +98,9 @@ template per run. 2026-10-07, Lilleman auf Larv; revised 2026-10-11 to name package `cli`. Serves goal 9.6: a CLI carrying your own modules is a few lines of Go over `cli.Main` and works just like -`fejkdata`, so `fejkdata`'s own CLI is such a CLI, and `cli`'s non-test code imports nothing -under `internal/`. Until `todo.md` item 129 moves it into -the library, the CLI copies how the grammar tells a lone reference, in `isPath`, +`fejkdata`. `cli`'s non-test code imports nothing under `internal/`, so whatever the CLI +does, a program of your own can do through the public API. Until `todo.md` item 129 moves +the lone-reference check into the library, the CLI copies how the grammar tells a lone reference, in `isPath`, `hasEmptySegment` and `withoutSelectors`, and a test pins the copy to the grammar. ## A template that does not compile is misuse (exit 2), including a reference that resolves to nothing, save a lone reference under the CLI's `--format` until item 129 diff --git a/todo.md b/todo.md index 2d0125b..775cb15 100644 --- a/todo.md +++ b/todo.md @@ -190,7 +190,7 @@ ### 185. Seat a panel of the README's audience personas to pull data in through the module API and build a custom CLI, and fix what it names. -0.1.0 is not cut before it. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". Seats: the Go test author, the bulk fixture author, a custom CLI's builder, and a data author with a `-d` folder and the replace flag, each in a scratch Go module against the checkout or a pre-release tag. Bench `data.Modules()` and the `.fejkdata.json` manifest a data author writes by hand in use; the package names, the manifest's `reads` and `namespace` and the errors naming the import set were benched on 2026-10-11. Decoding the manifest is most of `New`'s cost (about 0.55 ms and 2449 allocations on 2026-10-10, 2864 allocations once each module carried its own manifest). An entry lists every path below its category, its linked tables' paths too, so `geo.*.region` repeats its whole family. An entry holding only its own paths, with `List` composing a family from the entries naming it as `parent`, would shrink it. The custom CLI's builder also rules whether `--no-shipped-data`, `-d`'s "layer over the shipped data" and the help's `sv_SE` examples keep their wording where `cli.Main` carries their own modules, which the flag drops too. Record the ruling in `docs/`. +0.1.0 is not cut before it. Carries out the decision "The shipped data is Go packages a library imports by choice, and the CLI carries every one, from 0.1.0". Seats: the Go test author, the bulk fixture author, a custom CLI's builder, and a data author with a `-d` folder and the replace flag, each in a scratch Go module against the checkout or a pre-release tag. Bench `data.Modules()` and the `.fejkdata.json` manifest a data author writes by hand in use; the package names, the manifest's `reads` and `namespace` and the errors naming the import set were benched on 2026-10-11. Decoding the manifest is most of `New`'s cost (about 0.55 ms and 2449 allocations on 2026-10-10, 2864 allocations once each module carried its own manifest). An entry lists every path below its category, its linked tables' paths too, so `geo.*.region` repeats its whole family. An entry holding only its own paths, with `List` composing a family from the entries naming it as `parent`, would shrink it. The custom CLI's builder also rules whether the help keeps three wordings where `cli.Main` carries the builder's own modules: `--no-shipped-data`, which drops those modules too; `-d`'s "layer over the shipped data"; and the `sv_SE` examples. Record the ruling in `docs/`. ### 16. Add locale categories: company, phone, finance, vehicle, words. @@ -688,7 +688,7 @@ The check covers `data` and `testdata/shipped_shape.txt` alone, where `AGENTS.md ### 66. Cut the README's Layout block to the lines that say what a file name cannot. -`doc.go` and `cmd/fejkdata/` restate their names. +`doc.go` restates its name. ### 67. Cut `AGENTS.md` to the rules only it states, and explain every term its comprehension rule uses.