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