summaryrefslogtreecommitdiffhomepage
path: root/src/main.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/main.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/main.d')
-rw-r--r--src/main.d148
1 files changed, 148 insertions, 0 deletions
diff --git a/src/main.d b/src/main.d
new file mode 100644
index 0000000..78ceb69
--- /dev/null
+++ b/src/main.d
@@ -0,0 +1,148 @@
+import std.getopt;
+import std.stdio : writeln, stderr;
+import ssp_parser;
+import ssp_types;
+import output_tree;
+import output_html;
+import output_llm_breadcrumbs;
+import output_llm_jsonl;
+import output_images;
+import verify_images;
+import report_unknown;
+
+int main(string[] args) {
+ bool do_tree = false;
+ bool do_html = false;
+ bool do_llm_text = false;
+ bool do_llm_jsonl = false;
+ bool do_images = false;
+ bool do_verify = false;
+ bool do_report_unknown = false;
+ bool any_version = false;
+ string image_dir = "";
+ string output_file = "";
+
+ auto helpInfo = getopt(args,
+ "tree", "output document tree outline", &do_tree,
+ "html", "output HTML scroll", &do_html,
+ "llm-text", "output plain text with heading breadcrumbs", &do_llm_text,
+ "llm-jsonl", "output JSONL with embeddings-ready chunks", &do_llm_jsonl,
+ "images", "output image manifest (digest, size, pixels)", &do_images,
+ "verify", "verify .image records against --image-dir", &do_verify,
+ "image-dir", "image directory to verify against", &image_dir,
+ "output", "output file (default: stdout)", &output_file,
+ "report-unknown", "list what was read and not understood", &do_report_unknown,
+ "any-version", "read a format major version this reader does not know", &any_version,
+ );
+
+ if (helpInfo.helpWanted || args.length < 2) {
+ defaultGetoptPrinter(
+ "ssp-reader - reads .ssp files and produces output\n\n"
+ ~ "Usage: ssp-reader [options] <file.ssp>\n",
+ helpInfo.options,
+ );
+ return 0;
+ }
+
+ string input_file = args[1];
+
+ SspDocument doc;
+ try {
+ doc = parseSspFile(input_file);
+ } catch (Exception e) {
+ stderr.writeln("Error reading ", input_file, ": ", e.msg);
+ return 2;
+ }
+
+ /+ ↓ the version gate. A reader checks the major part and refuses what it
+ does not know: an unknown major means a property may have changed
+ meaning or gone away, and loading it half populated in silence is the
+ failure this exists to prevent. --any-version overrides, for looking
+ at a file rather than trusting one.
+ +/
+ if (doc.format_version.length == 0) {
+ stderr.writeln("warning: ", input_file,
+ " declares no format version (no \"% SiSU Document Abstraction v\" line)");
+ } else if (doc.formatVersionMajor != ssp_format_major_read) {
+ if (any_version) {
+ stderr.writeln("warning: ", input_file, " is format v", doc.format_version,
+ ", this reader knows v", ssp_format_major_read, ".x; reading anyway");
+ } else {
+ stderr.writeln("error: ", input_file, " is format v", doc.format_version,
+ ", this reader knows v", ssp_format_major_read, ".x");
+ stderr.writeln(" a major version differs: a property may have",
+ " changed meaning or gone away.");
+ stderr.writeln(" --any-version reads it regardless.");
+ return 3;
+ }
+ }
+
+ writeln("Parsed: ", input_file);
+ if (doc.format_version.length > 0) {
+ writeln(" Format: v", doc.format_version);
+ }
+ if (auto _lang = "language" in doc.source) {
+ writeln(" Source: ", *_lang,
+ ("languages" in doc.source) ? " of " ~ doc.source["languages"] : "",
+ ("digest" in doc.source) ? ", markup digest " ~ doc.source["digest"][0 .. 16] ~ "..." : "");
+ }
+ writeln(" Title: ", doc.meta("title.main"));
+ writeln(" Author: ", doc.meta("creator.author"));
+ writeln(" Sections: head=", doc.head.length,
+ " toc=", doc.toc.length,
+ " body=", doc.body.length,
+ " endnotes=", doc.endnotes.length,
+ " glossary=", doc.glossary.length,
+ " bibliography=", doc.bibliography.length,
+ " bookindex=", doc.bookindex.length,
+ " blurb=", doc.blurb.length,
+ " tail=", doc.tail.length);
+ auto image_records = imageRecordCount(doc);
+ if (image_records > 0) {
+ writeln(" Images: ", image_records, " record",
+ (image_records == 1) ? "" : "s");
+ }
+
+ if (do_tree) {
+ outputTree(doc, output_file);
+ }
+
+ if (do_html) {
+ outputHtmlScroll(doc, output_file);
+ }
+
+ if (do_llm_text) {
+ outputLlmBreadcrumbs(doc, output_file);
+ }
+
+ if (do_llm_jsonl) {
+ outputLlmJsonl(doc, output_file);
+ }
+
+ if (do_images) {
+ outputImages(doc, output_file);
+ }
+
+
+ int _verify_failures = 0;
+ if (do_verify) {
+ if (image_dir.length == 0) {
+ stderr.writeln("--verify needs --image-dir=<path to the pod's media/image>");
+ return 2;
+ }
+ _verify_failures = verifyImages(doc, image_dir, output_file);
+ }
+
+ if (do_report_unknown) {
+ reportUnknown(doc);
+ }
+
+ if (!do_tree && !do_html && !do_llm_text && !do_llm_jsonl && !do_images
+ && !do_verify && !do_report_unknown) {
+ writeln("\nUse --tree, --html, --llm-text, --llm-jsonl, --images,"
+ ~ " --verify --image-dir=<dir>"
+ ~ " or --report-unknown to produce output.");
+ }
+
+ return (_verify_failures > 0) ? 1 : 0;
+}