summaryrefslogtreecommitdiffhomepage
path: root/src/report_unknown.d
diff options
context:
space:
mode:
authorRalph Amissah <ralph.amissah@gmail.com>2026-09-24 11:12:28 -0400
committerRalph Amissah <ralph.amissah@gmail.com>2026-09-24 11:12:28 -0400
commitda833f8b157ae501c9f6eec827dd4a965bfa7265 (patch)
tree9368bbfe07dc130867dc8241d20bc3d125f3e510 /src/report_unknown.d
parentcommencement: 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/report_unknown.d')
-rw-r--r--src/report_unknown.d41
1 files changed, 41 insertions, 0 deletions
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)");
+}