diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-29 20:04:55 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-10-21 19:12:17 -0400 |
| commit | 4dd9b15d2210e5661f9261acf113c22d4372ffc5 (patch) | |
| tree | 291dc10e1c839f084cb12ac615e1839b67807101 | |
| parent | Gleam: ocda-read, byte for byte the D reader's (diff) | |
README: the reader in D and Gleamclaude-main-prepare
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)
| -rw-r--r-- | README.md | 32 | ||||
| -rw-r--r-- | dlang/README.md | 43 | ||||
| -rw-r--r-- | gleam/README.md | 38 |
3 files changed, 93 insertions, 20 deletions
@@ -24,8 +24,36 @@ So this library holds the model and both loaders, and **a writer cannot tell which serialisation it was handed** - exactly as spine's own writers cannot, since spine 0.25.0. -That is the whole of the idea. The readers become thin programs over this, -and the writers are functions from the model to bytes. +That is the whole of the idea. The writers are functions from the model to +bytes, and the reader is a program over the model. + +## The reader + +```sh +ocda-read [--tree|--html|--llm-text|--llm-jsonl|--images|--verify --image-dir=<d>| + --languages|--files|--report-unknown|--validate] + <file>.ssp | <file>.ocda.db | <file>.sisupod [lang] +``` + +One reader, in each language, where `sisudoc-ssp-reader` and +`sisudoc-ocda-db-reader` were two, each with a parser of its own. Built on +this library, **every mode reads every form and says the same thing of a +document's `.ssp`, `.ocda.db` and `.sisupod`**, 36 of 36 document-languages. +The D reader has every mode of both old readers; the Gleam one the modes the +Gleam readers had (the summary, `--tree`, `--languages`, `--files`, +`--report-unknown`), and in those **its output is the D one's, byte for +byte**, 36 of 36. + +It is in each language's `src/read/`, and not part of the library: a +program using the library does not build it (in D, by dub configuration; +in Gleam a dependant compiles it and does not use it, Gleam building +everything in `src/`). + +Writing it found one defect in the library: **the database loader could +not say what it had not understood**. It asks for columns by name, and so +never saw the ones it did not ask for, and reported that it had understood +everything. It now counts them on the conditions under which the `.ssp` +writes the same property, and the report is the same from either form. ## The checks that matter diff --git a/dlang/README.md b/dlang/README.md index 302f874..96df8f4 100644 --- a/dlang/README.md +++ b/dlang/README.md @@ -4,14 +4,16 @@ The abstraction's model and both its loaders, as a dub library. ## Modules -|-----------------|---------------------------------------------------------------| -| `ocda.model` | the document, the object, the eight sections. Imports nothing | -| `ocda.load_ssp` | text -> model | -| `ocda.load_db` | sqlite -> model | -| `ocda.load` | what a path is, and loading it | -| `ocda.dump` | the model written out canonically, as an oracle | -| `ocda.sqlite` | the sqlite3 C API, declared rather than depended upon | ->>>>>>> 3ad58ce (ocda-lib in Gleam, and four agreements of 36 of 36) +|------------------|------------------------------------------------------------------------------------------------------------| +| `ocda.model` | the document, the object, the eight sections. Imports nothing | +| `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=<d>|--languages|--files|--report-unknown|--validate] + <file>.ssp|<file>.ocda.db|<file>.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 ``` diff --git a/gleam/README.md b/gleam/README.md index a43fe2d..1da1648 100644 --- a/gleam/README.md +++ b/gleam/README.md @@ -1,14 +1,17 @@ # ocda-lib, in Gleam -The abstraction's model and both its loaders, as a Gleam library, and the -two programs that put it to the question. - -|-----------------|----------------------------------------------------------------------------------| -| `ocda/model` | the document, the object, the image. Depends on nothing but the standard library | -| `ocda/load_ssp` | text -> model | -| `ocda/load_db` | sqlite -> model | -| `ocda/load` | what a path is, and loading it | -| `ocda/dump` | the model written out canonically, as an oracle | +The abstraction's model and both its loaders, as a Gleam library, with its +reader and the two programs that put it to the question. + +|------------------|-----------------------------------------------------------------------------------------| +| `ocda/model` | the document, the object, the image. Depends on nothing but the standard 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, and what a `.ocda.db` carries | +| `ocda/dump` | the model written out canonically, as an oracle | +| `read/main` | `ocda-read`, the reader | +| `ocda_ffi.erl` | a sha256, from OTP's crypto, which the standard library lacks | ## Use @@ -26,6 +29,23 @@ case load.load(path, "en", False) { } ``` +## The reader + +```sh +nix build +./result/bin/ocda-read [--tree|--outline|--languages|--files|--report-unknown] + <file>.ssp|<file>.ocda.db|<file>.zip [lang] +``` + +`ocda-lib read`, installed also as `ocda-read`. The modes the Gleam readers +had, over the library, so each reads every form this library reads; the +others are the D reader's. **Its output is the D `ocda-read`'s, byte for +byte**, in every mode both have. In `src/read/`, because Gleam compiles +nothing outside `src/`; a program depending on the library compiles it too, +and does not use it. + +A `.sisupod` it refuses, saying why: the zstd frame, below. + ## The two programs ```sh |
