From da833f8b157ae501c9f6eec827dd4a965bfa7265 Mon Sep 17 00:00:00 2001 From: Ralph Amissah Date: Thu, 24 Sep 2026 11:12:28 -0400 Subject: 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) --- src/report_unknown.d | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 src/report_unknown.d (limited to 'src/report_unknown.d') diff --git a/src/report_unknown.d b/src/report_unknown.d new file mode 100644 index 0000000..1d5238e --- /dev/null +++ b/src/report_unknown.d @@ -0,0 +1,41 @@ +module report_unknown; + +import std.algorithm : sort; +import std.array : array; +import std.stdio : writeln, writefln; +import ssp_types; + +/+ ↓ say what was read and not understood. + This is what makes the reader usable as a check on the format + specification: a reader that ignores what it does not know is + conforming, but one that cannot say what it ignored cannot tell you + whether the specification it was written from was complete. Silence + and understanding look the same from outside. ++/ +void reportUnknown(ref SspDocument doc) { + if (!doc.unknown.any) { + writeln("\nread and understood: every property, block and line was known"); + return; + } + writeln("\nread and NOT understood:"); + if (doc.unknown.property.length > 0) { + writeln(" properties ignored (", doc.unknown.property.length, " distinct):"); + foreach (name; doc.unknown.property.keys.sort) { + writefln(" .%-26s %8d", name, doc.unknown.property[name]); + } + } + if (doc.unknown.block.length > 0) { + writeln(" blocks ignored (", doc.unknown.block.length, " distinct):"); + foreach (name; doc.unknown.block.keys.sort) { + writefln(" @%-26s %8d", name, doc.unknown.block[name]); + } + } + if (doc.unknown.line.length > 0) { + writeln(" lines of no known shape, by first character:"); + foreach (c; doc.unknown.line.keys.sort) { + writefln(" %-27s %8d", "\"" ~ c ~ "\"", doc.unknown.line[c]); + } + } + writeln(" (ignoring these is conforming within a major version;", + " the count is so that it is not silent)"); +} -- cgit v1.2.3