summaryrefslogtreecommitdiffhomepage
path: root/dlang/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'dlang/README.md')
-rw-r--r--dlang/README.md62
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
+```