diff options
Diffstat (limited to 'dlang/README.md')
| -rw-r--r-- | dlang/README.md | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/dlang/README.md b/dlang/README.md new file mode 100644 index 0000000..124e4d6 --- /dev/null +++ b/dlang/README.md @@ -0,0 +1,62 @@ +# ocda-lib, in D + +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 | + +`ocda.model` importing nothing is the property that matters: a writer +depends on the model and on neither loader. + +## Use + +```json +"dependencies": { "ocda-lib": { "path": "../../sisudoc-ocda-lib/dlang" } } +``` + +```d +import ocda.load; +auto doc = load("document.ocda.db", "de"); // or "document.ssp" +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 two checks + +```sh +nix build .#ocda-agree && ./result/bin/ocda-agree <doc>.ssp <doc>.ocda.db [lang] +nix build .#ocda-dump && ./result/bin/ocda-dump [--unknown] <file> [lang] +``` + +`agree` loads both and compares ten fields of each object, naming the field +where they part company. `agree` found the blank-first-text-line defect and +was not enough for anything subtler. + +**`ocda-dump` is the stronger check**: the whole loaded model, every field, +written out in a form fully determined by the model, so that two +implementations can be compared with `diff`. It is an oracle, not an output +format; anything reading it to reconstruct a document has misunderstood it. +It agrees byte for byte with the Gleam library's `ocda-lib dump`, which is +the point of having it. + +It found four disagreements `agree` could not see. They are in the +repository README and in the history. + +## Build + +```sh +nix build .#ocda-agree # the agreement check +nix build .#ocda-dump # the canonical dump +nix develop # ldc, dub, dtools, sqlite +dub build # the library +``` |
