From e4ae72a1e57af96054581f4339557ccaebaac501 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Tue, 29 Sep 2026 20:04:55 -0400 Subject: README: the reader, in each language, and what writing it found The library's reader, ocda-read: where it lives and why (src/read/, kept out of the library in D by dub configuration, in Gleam because nothing outside src/ is compiled), its modes in each language, and the two properties it holds, the same output from every form and D == Gleam byte for byte. And the one defect it found in the library, the database loader unable to say what it had not read. The module tables gain ocda.inventory and the reader, the build notes the three programs in one result. (assisted by Claude-Code) --- dlang/README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) (limited to 'dlang/README.md') diff --git a/dlang/README.md b/dlang/README.md index 262162f..047c2fc 100644 --- a/dlang/README.md +++ b/dlang/README.md @@ -10,8 +10,10 @@ The abstraction's model and both its loaders, as a dub library. | `ocda.load_ssp` | text -> model | | `ocda.load_db` | sqlite -> model | | `ocda.load` | what a path is, and loading it | +| `ocda.inventory` | what a file holds beyond the one document: its languages (every form alike), and what a `.ocda.db` carries | | `ocda.dump` | the model written out canonically, as an oracle | | `ocda.sqlite` | the sqlite3 C API, declared rather than depended upon | +| `read.*` | `ocda-read`, the reader: in `src/read/`, and *not* part of the library (below) | `ocda.model` importing nothing is the property that matters: a writer depends on the model and on neither loader. @@ -31,6 +33,26 @@ foreach (obj; doc.body) { ... } Link `sqlite3`; the library declares the dozen functions it needs rather than taking a binding from the registry, so there is nothing to fetch. +## The reader + +```sh +nix build .#ocda-read && ./result/bin/ocda-read [--tree|--html|--llm-text|--llm-jsonl| + --images|--verify --image-dir=|--languages|--files|--report-unknown|--validate] + .ssp|.ocda.db|.sisupod [lang] +``` + +The library's reader, one program where `sisudoc-ssp-reader` and +`sisudoc-ocda-db-reader` were two. Its output modules are the `.ssp` +reader's, moved onto the library's model, so every mode reads every form +and **says the same thing of a document's `.ssp`, `.ocda.db` and +`.sisupod`**. `--files` answers for a `.ocda.db`, the one form that carries +files; `--validate` checks a `.ssp` as text and refuses anything else. + +It lives in `src/read/` beside the library, and dub keeps it out of the +library: the configuration `library` excludes `src/read/*`, the +configuration `ocda-read` builds it. A program using the library by dub, or +by naming `src/ocda/*.d` as the writer's flake does, never compiles it. + ## The two checks ```sh @@ -55,8 +77,11 @@ repository README and in the history. ## Build ```sh +nix build # all three programs, in one result/bin +nix build .#ocda-read # the reader nix build .#ocda-agree # the agreement check nix build .#ocda-dump # the canonical dump -nix develop # ldc, dub, dtools, sqlite +nix develop # ldc, dub, dtools, sqlite, zstd dub build # the library +dub build --config=ocda-read # the reader ``` -- cgit v1.2.3