diff options
| -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 |
