diff options
| author | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-24 11:12:28 -0400 |
|---|---|---|
| committer | Ralph Amissah <ralph.amissah@gmail.com> | 2026-09-24 11:12:28 -0400 |
| commit | da833f8b157ae501c9f6eec827dd4a965bfa7265 (patch) | |
| tree | 9368bbfe07dc130867dc8241d20bc3d125f3e510 /src/ssp_types.d | |
| parent | commencement: a reader for the .ssp (diff) | |
format 2.0: the version gate
The reader as it stood when the format reached 2.0, in D: a parser of
the .ssp with no dependency beyond phobos, and outputs from it - a
heading tree, an html scroll, breadcrumbed text, chunked jsonl for
embedding pipelines, an image manifest, and a check of image records
against the images on disk.
Brought to abstraction format 2.0, and made able to say what it does
not understand, so a reader can check that its format specification is
complete. Previously the reader ignored what it did not recognise and
reported nothing, which made it seem it had understood a 2.0 file (and
drop things in silence).
Now:
- the banner is read, and the major part checked. A major this
reader does not know is refused, exit 3, because an unknown major
means a property may have changed meaning or gone away and loading
it half populated in silence is the failure the check exists to
prevent. --any-version reads it regardless, for looking at a file
rather than trusting one. A file with no banner warns and is read.
- @source is a preamble block beside @meta, @make and @doc_has, and
the summary line shows the language and the markup digest.
- tail is a section like the rest.
- --report-unknown lists every property, block and line shape met and
not understood, with counts. Ignoring them remains the conforming
behaviour within a major version; the counting is so that it is not
silent.
Over the markup document samples that report names 18 properties,
from .is_of_type at 56,882 occurrences down to .attrib at
1. Several are legitimately of no interest to a renderer and several
are not. Deciding which is which is the next pass, and it now has a
measured work list rather than a guess.
(assisted by Claude-Code)
Diffstat (limited to 'src/ssp_types.d')
| -rw-r--r-- | src/ssp_types.d | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/src/ssp_types.d b/src/ssp_types.d new file mode 100644 index 0000000..f87da5b --- /dev/null +++ b/src/ssp_types.d @@ -0,0 +1,121 @@ +module ssp_types; + +struct SspImage { + string name; // image filename as referenced by the object + string sha256; // hex-encoded (uppercase) digest of the file + ulong bytes; // file size + int width; // file's own pixel width (not display width) + int height; // file's own pixel height + bool missing; // file absent or unreadable, no sha256/bytes + string[string] fields; // any further/unrecognised key:value fields +} + +struct SspObject { + int ocn; + string is_a; // heading, para, toc, table, code, group, block, verse, quote, endnote, glossary, bibliography, bookindex, blurb + string section; // head, toc, body, endnotes, glossary, bibliography, bookindex, blurb + string heading_level; // A, B, C, D, 1, 2, 3, 4 (for headings) + string identifier; // named segment (for headings) + string part; // frontmatter, body, backmatter + int parent_ocn; + int last_descendant_ocn; + int[] children; // direct child heading OCNs + int[] ancestors; // markedup_ancestors[8] + bool dummy_heading; + bool ocn_off; + int indent_base; + int indent_hang; + bool bullet; + string lang; + bool has_links; + bool has_notes_reg; + bool has_notes_star; + bool has_images; + string segment; + string segment_prev; + string segment_next; + string anchor; + int table_cols; + string table_widths; + bool table_header; + string code_syntax; + bool code_linenumbers; + string heading_ancestors_text; + string sha256; + SspImage[] images; // repeatable .image records, in order + string text; // content (lines joined with newline) +} + +/+ ↓ what the reader met and did not understand. + A reader that silently drops what it does not know cannot say whether + it understood the document, and cannot be used to check a + specification against an implementation: silence and understanding + look alike. So the parser counts what it ignored, and + --report-unknown prints it. ++/ +struct SspUnknown { + size_t[string] property; // .name -> times seen + size_t[string] block; // @name -> times seen + size_t[string] line; // first char -> times seen, lines of no known shape + + bool any() const { + return property.length > 0 || block.length > 0 || line.length > 0; + } +} + +struct SspDocument { + string format_version; // as declared on line 1, "" when absent + string[string] source; // @source: language, languages, digest + SspUnknown unknown; // what was met and not understood + string[string] metadata; // key -> value + string[string] make; // key -> value + string[string] doc_has; // key -> value + SspObject[] head; + SspObject[] toc; + SspObject[] body; + SspObject[] endnotes; + SspObject[] glossary; + SspObject[] bibliography; + SspObject[] bookindex; + SspObject[] blurb; + SspObject[] tail; + + /+ ↓ the major part of the declared version, "" when none was declared +/ + string formatVersionMajor() const { + import std.string : indexOf; + if (format_version.length == 0) { return ""; } + auto dot = format_version.indexOf('.'); + return (dot > 0) ? format_version[0 .. dot] : format_version; + } + + string meta(string key) { + if (auto p = key in metadata) return *p; + return ""; + } + + SspObject[]* sectionByName(string name) { + switch (name) { + case "head": return &head; + case "toc": return &toc; + case "body": return &body; + case "endnotes": return &endnotes; + case "glossary": return &glossary; + case "bibliography": return &bibliography; + case "bookindex": return &bookindex; + case "blurb": return &blurb; + case "tail": return &tail; + default: return null; + } + } +} + +/+ ↓ the format major version this reader knows. + The .ssp and the .ocda.db carry one version between them, declared in + band: the .ssp on its first line, the database in its schema.version + row. The minor part is raised when a property is added, and a reader of + the newer format still reads the older one, so only the major part is + checked here. Raise this when the reader has been brought to a new + major, not before: the point of the gate is to refuse what has not been + looked at. ++/ +enum ssp_format_major_read = "2"; |
