summaryrefslogtreecommitdiffhomepage
path: root/dlang/README.md
blob: 65d762e54f8cc9d9fa1f39f7f9ddbdcfd026a64e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
# 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.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.

## 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 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, where it describes the document, **says the same thing of its `.ssp`,
`.ocda.db` and `.sisupod`**. `--languages` lists the one language a `.ssp`
holds and every language of the other two; `--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
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                 # 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, zstd
dub build                 # the library
dub build --config=ocda-read   # the reader
```