CHANGELOG.md

@@ -16,39 +16,41 @@ and any release may change what a seed draws, so pin one exact version
 
 ### Added
 
-- The CLI, `fejkdata`, renders exactly the template on its stdin and adds nothing: `echo
+- The CLI, `fejkdata`, renders exactly the template on its stdin and adds nothing:
-  '{/sv_SE.person} hihi' | fejkdata` prints e.g. `Sara Eriksson hihi`. `--seed` makes a
+  `echo '{/sv_SE.person} hihi' | fejkdata` prints e.g. `Sara Eriksson hihi`. `--seed`
-  run reproducible for one version and data, `-n` repeats it, `--list` prints every
+  repeats a run's output while the version and data stay the same, `-n` renders the
-  path, and `--data-path` layers a directory of your own data over the shipped set, or
+  template that many times, and `--list` prints the paths the data offers.
-  alone with `--no-shipped-data`. `--format json|ndjson|csv|sql` writes a record's
+  `--data-path` layers a directory of your own data over the shipped set, and
-  columns, one record per row. It exits `0` on success, `1` on a runtime error such as
+  `--no-shipped-data` loads that directory alone. `--format json|ndjson|csv|sql` writes
-  data that fails to load, and `2` on misuse.
+  a record's columns, one record per row. The CLI exits `0` on success, `1` on a runtime
+  error such as data that fails to load, and `2` on misuse.
 - The library, `github.com/larvit/fejkdata`, for Go 1.22 or later on a 64-bit target.
   `New` loads the modules `WithDataFS` names and the folders `WithDataPath` names, and
-  fails, naming `WithDataFS`, where neither is given; `WithSeed` makes its draws
+  fails, naming `WithDataFS`, where neither is given. `WithSeed` makes its draws
-  reproducible for one version and data. `Fake` renders a path, `FakeTemplate` and
+  repeat while the version and data stay the same. `Fake` renders a path, and
-  `NewTemplate` a template, `FakeRecord`, `FakeRecordTemplate` and `NewRecordTemplate` a
+  `FakeTemplate` and `NewTemplate` render a template. `FakeRecord`, `FakeRecordTemplate`
-  record, whose columns `JSON`, `CSVHeader`, `CSVLine` and `SQLInsert` write as the CLI
+  and `NewRecordTemplate` render a record, whose `JSON`, `CSVHeader`, `CSVLine` and
-  does, and `FakeStruct` fills a struct's `fake:"…"` tagged fields. `List` gives every
+  `SQLInsert` methods write its columns as the CLI does. `FakeStruct` fills a struct's
-  path `Fake` renders, and `IsTemplate` tells an inline template from a path. Data that
+  `fake:"…"` tagged fields. `List` gives the paths `Fake` renders, direct descents only,
-  fails to load gives an error matching `ErrLoad`, and a record with no fields one
+  and `IsTemplate` tells an inline template from a path. Data that fails to load gives
-  matching `ErrNoColumns`.
+  an error matching `ErrLoad`, and a record with no fields gives one matching
+  `ErrNoColumns`.
 - Package `github.com/larvit/fejkdata/cli` is the `fejkdata` command:
   `cli.Main(modules...)` runs it over the modules given, so
   `cli.Main(append(data.Modules(), mydata)...)` builds a CLI carrying your own data.
   That CLI names itself by the file it runs from, and its `--version` prints its own
   module's version before fejkdata's.
-- The template language ([Data
+- The template language
-  format](https://github.com/larvit/fejkdata/blob/v0.1.0/README.md#data-format)). A node
+  ([Data format](https://github.com/larvit/fejkdata/blob/v0.1.0/README.md#data-format)).
-  is a string, a choice, a template, a table, a number or a boolean. A format string's
+  Every value in a data file is a string, a choice, a template, a table, a number or a
-  `{…}` tokens read sibling fields, references from the data root, the file's folder or
+  boolean. A `{…}` token reads a sibling field, a name, or a reference from the data
-  the folder above (`{/sv_SE.person.last}`, `{.x}`, `{..x}`), builtins and names. Every
+  root, the file's folder or the folder above (`{/sv_SE.person.last}`, `{.x}`, `{..x}`),
-  `{…}` draws afresh, and a name is the one way to keep a pick: `{/sv_SE.person as
+  or it calls a builtin. Every `{…}` draws afresh, and a name is the one way to keep a
-  p}{p.first} {p.last}` is one person. The builtins draw check digits (`luhn`, `mod11`,
+  pick: `{/sv_SE.person as p}{p.first} {p.last}` is one person. The builtins draw check
-  `ean`), samples (`digits`, `int`, `float`, `uuid`, `ulid`, `iban`, `date`, `time` and
+  digits (`luhn`, `mod11`, `ean`), samples (`digits`, `int`, `float`, `uuid`, `ulid`,
-  more), a counter (`seq`), arithmetic (`calc`) and transforms (`lowercase`,
+  `iban`, `date`, `time` and more), a counter (`seq`), arithmetic (`calc`) and
-  `uppercase`, `ascii`). `New` refuses data that breaks the grammar, could mean two
+  transforms (`lowercase`, `uppercase`, `ascii`). `New` refuses data that breaks the
-  things or cannot render a valid value.
+  grammar, could mean two things or cannot render a valid value.
 - Records ([Records](https://github.com/larvit/fejkdata/blob/v0.1.0/README.md#records)):
   a template seen as columns. A column is a string unless it declares a `datatype`,
   `integer`, `number` or `boolean`, and a `null` item draws it as null.
@@ -84,9 +86,10 @@ and any release may change what a seed draws, so pin one exact version
   - `geo.SE` and `geo.US`: five linked tables per country, `region`, `municipality`,
     `locality`, `postal-code` and `street`, weighted by population and address counts
     and built from SCB, GeoNames, Trafikverket NVDB, the US Census Bureau and Wikidata,
-    and an `address` record drawing a street and postal code inside one locality, which
+    and an `address` record that draws a street and a postal code inside one
-    `sv_SE.address` and `en_US.address` print. Every Swedish postort the import can
+    locality; `sv_SE.address` and `en_US.address` print it. Every Swedish postort
-    place ships with all its streets. Of the US incorporated places that hold most of
+    (postal town) the import can place ships with all its streets. A US place ships
-    some postal code's land, every state capital but Honolulu, every place of 100,000 or
+    only if it is incorporated and holds most of some postal code's land. Of those
-    more and a population-weighted tenth of them ship, each with a quarter of its
+    places, every state capital but Honolulu ships, as does every place of 100,000
-    streets, at least ten.
+    people or more and a tenth of all of them drawn by population. Each US place
+    carries a quarter of its streets, at least ten.

README.md

@@ -415,10 +415,10 @@ type Address struct {
 `FakeStruct` fills a struct through a pointer: each exported field tagged `fake:"…"` is
 a column of one record, its tag a path or an inline template — told apart by
 `IsTemplate` — and its Go type the column's
-[datatype](#datatype): a string, bool, integer or float kind, or a pointer to one,
+[datatype](#datatype): a string, bool, integer or float kind, or a pointer to one. A
-which a column that can be null requires and a [`null`](#null) item leaves nil. An integer stays within int64 whatever its
+column that can be null needs a pointer, which a [`null`](#null) item leaves nil. An
-kind, and a value the kind cannot hold, such as `{int(0,300)}` in a `uint8`, is refused
+integer stays within int64 whatever its kind, and a value the kind cannot hold, such as
-naming a kind that holds it. The tags are a record's columns, so they share its
+`{int(0,300)}` in a `uint8`, is refused naming a kind that holds it. The tags are a record's columns, so they share its
 [names](#names): `First` tagged `{/sv_SE.person as p}{p.first}` and `Sex` tagged `{p.sex}`
 describe one person, while two path tags into `sv_SE.person` are two draws. The fields an
 embedded struct promotes are columns of the same record; a named struct field, or a