diff options
Diffstat (limited to 'gleam/README.md')
| -rw-r--r-- | gleam/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/gleam/README.md b/gleam/README.md new file mode 100644 index 0000000..32d4cf7 --- /dev/null +++ b/gleam/README.md @@ -0,0 +1,82 @@ +# ssp-reader, in Gleam + +Reads a `.ssp`, the object-centric document abstraction written as text, +and says what it found and what it did not understand. + +**Written from the specification alone**, as an experiment in whether that +specification suffices: + +- `ssp-format-specification.md`, from the **doc-abstraction-format** + specification +- `ocda-model.md`, from the same + +No reference was made to spine's emitter or to the D reader while writing +it. The constants it carries (the sixteen kinds, the nine sections, the +four preamble blocks, the 42 properties in their emitted order) were taken +from the specification's own tables. + +## Building and running + +```sh +nix build # the reader, as a single-file escript +./result/bin/ssp_reader <file.ssp> +``` + +`nix build` works **sandboxed and without network**. There is no Gleam +builder in nixpkgs and `gleam build` fetches from Hex, so the build uses +nix-gleam's builder, kept in `nix-gleam/` (MIT, see its README), which +fetches each Hex package on its own by the checksum `manifest.toml` already +carries. There is no hash in `flake.nix` to keep up to date. The result +needs only what it carries: run it with an empty environment and it works. + +For development: + +```sh +nix develop # gleam, erlang, rebar3 +gleam run -- <file.ssp> +gleam run -- --outline <file.ssp> +gleam run -- --report-unknown <file.ssp> +gleam run -- --any-version <file.ssp> +``` + +## What it does + +- Reads the version banner and **checks the major part**, refusing a major + it does not know (specification section 2.1). `--any-version` overrides. +- Parses the four preamble blocks, the nine sections, and the object + records: declaration line, properties, text. +- `--outline` prints the headings indented by level. +- `--report-unknown` lists every property it did not use, with counts. + +## Agreement with the D reader + +Both implementations were run over the 36 document reference collection +and **agree on the section counts of all 36**. + +## Tests + +```sh +gleam test +``` + +Ten, against small literals rather than files, since the parser is a pure +function from text to a document. Each names the specification section it +holds the parser to: the version banner, the `% Source:` line, `@source` +being preamble and not a section, the object declaration, text line order, +ancestors as numbers, that a `comment` object does not render, that an +unused property is counted rather than dropped, and that a line of no known +shape is counted. + +## What it does not do + +- The `.ocda.db`, which would want an Erlang sqlite binding. +- HTML, JSONL or plain-text output. +- Packaging as an escript, so it needs `gleam run`. + +## Layout + +``` +src/ssp_reader.gleam the program: arguments, version gate, output +src/ssp/types.gleam the document, the object, the version rule +src/ssp/parse.gleam the parser, a fold over the lines +``` |
