module read.validate; /+ ↓ check a .ssp against the format specification. . Written from specs/sisudoc-abstraction-format/ssp-format-specification.md and from nothing else: the point of it is to be what the specification says, executed, so that a file can be held against the document rather than against an implementation. Each check names the section it comes from, so a disagreement can be taken back to the text. +/ import std.algorithm : canFind, startsWith; import std.array : array, split; import std.conv : to; import std.file : readText; import std.stdio : writeln, writefln; import std.string : indexOf, strip; struct SspFinding { size_t line; // 1-based string section; // the specification section the rule is from string detail; } /+ ↓ specification section 6.3: the properties, in the order they are emitted. A reader may rely on the order, so a validator can check it +/ private immutable string[] property_order = [ "identifier", "part", "section", "parent", "last_descendant", "ocn_range", "children", "ancestors", "ancestors_collapsed", "dom_status", "dom_status_collapsed", "heading_lev_collapsed", "parent_lev", "dummy", "ocn_off", "is_of_type", "attrib", "meta_lang", "meta_syntax", "sha256", "image", "indent", "bullet", "lang", "has", "table_cols", "table_widths", "table_aligns", "table_header", "code_linenumbers", "stow_link", "segment", "anchor", "segment_prev", "segment_next", "heading_lev_anchor", "segment_epub", "segment_html_is", "segment_epub_is", "segment_lv4_is", "heading_ancestors_text", "lev4_subtoc", "anchor_tag", ]; /+ ↓ section 6.1: the sixteen kinds +/ private immutable string[] kinds = [ "para", "heading", "toc", "bookindex", "endnote", "code", "bibliography", "comment", "verse", "glossary", "quote", "poem", "block", "table", "blurb", "group", ]; /+ ↓ section 4: the nine sections, in the order they appear +/ private immutable string[] section_order = [ "head", "toc", "body", "endnotes", "glossary", "bibliography", "bookindex", "blurb", "tail", ]; /+ ↓ section 4: the four preamble blocks, in the order they appear +/ private immutable string[] preamble_order = ["source", "meta", "make", "doc_has"]; /+ ↓ section 6.1: the heading levels +/ private immutable string[] levels = ["A", "B", "C", "D", "1", "2", "3", "4"]; private int propertyRank(string name) { foreach (i, p; property_order) { if (p == name) { return cast(int) i; } } return -1; } SspFinding[] validateSspFile(string filename, string major_known) { SspFinding[] found; auto lines = readText(filename).split("\n"); bool seen_banner = false; bool seen_source_line = false; string block = ""; // the block currently open, "" when none int preamble_at = -1; // how far through the preamble order int section_at = -1; // how far through the section order bool in_object = false; int prev_rank = -1; size_t doc_has_keys = 0; bool in_text = false; // text lines come after properties foreach (i, line; lines) { size_t no = i + 1; /+ ↓ section 2: the version, on the first line +/ if (no == 1) { enum banner = "% SiSU Document Abstraction v"; if (!line.startsWith(banner)) { found ~= SspFinding(no, "2", "first line is not the version banner"); } else { seen_banner = true; string v = line[banner.length .. $].strip; auto dot = v.indexOf('.'); string major = (dot > 0) ? v[0 .. dot] : v; if (major != major_known) { found ~= SspFinding(no, "2.1", "format major v" ~ major ~ ", this validator knows v" ~ major_known); } } continue; } if (no == 2) { if (!line.startsWith("% Source: ")) { found ~= SspFinding(no, "4", "second line is not \"% Source: \""); } else { seen_source_line = true; } continue; } if (line.length == 0) { in_object = false; in_text = false; prev_rank = -1; continue; } /+ ↓ section 3: a comment is the file header only +/ if (line[0] == '%') { found ~= SspFinding(no, "3", "a comment outside the two header lines"); continue; } /+ ↓ block open +/ if (line[0] == '@') { auto brace = line.indexOf(" {"); if (brace < 1 || line[$ - 1] != '{') { found ~= SspFinding(no, "3", "block open is not \"@name {\""); continue; } string name = line[1 .. brace]; if (preamble_order.canFind(name)) { int at = 0; foreach (k, p; preamble_order) { if (p == name) { at = cast(int) k; } } if (at <= preamble_at) { found ~= SspFinding(no, "4", "preamble block @" ~ name ~ " out of order"); } preamble_at = at; if (section_at >= 0) { found ~= SspFinding(no, "4", "preamble block @" ~ name ~ " after a section"); } } else if (section_order.canFind(name)) { int at = 0; foreach (k, sname; section_order) { if (sname == name) { at = cast(int) k; } } if (at <= section_at) { found ~= SspFinding(no, "4", "section @" ~ name ~ " out of order"); } section_at = at; } else { found ~= SspFinding(no, "4", "@" ~ name ~ " is neither a preamble block nor a section"); } block = name; doc_has_keys = 0; continue; } if (line[0] == '}') { if (line.length != 1) { found ~= SspFinding(no, "3", "block close carries more than \"}\""); } /+ ↓ section 5.4: ten keys, always +/ if (block == "doc_has" && doc_has_keys != 10) { found ~= SspFinding(no, "5.4", "@doc_has has " ~ doc_has_keys.to!string ~ " keys, the specification says ten"); } block = ""; in_object = false; prev_rank = -1; continue; } /+ ↓ section 5: inside a preamble block, " key: value" +/ if (preamble_order.canFind(block)) { if (!line.startsWith(" ") || line.indexOf(": ") < 3) { found ~= SspFinding(no, "5", "not \" key: value\" inside @" ~ block); } else if (block == "doc_has") { doc_has_keys++; } continue; } /+ ↓ section 6.1: the object declaration line +/ if (line[0] == '[') { auto close = line.indexOf("] "); if (close < 2) { found ~= SspFinding(no, "6.1", "declaration is not \"[ocn] ...\""); continue; } string ocn = line[1 .. close]; foreach (c; ocn) { if (c < '0' || c > '9') { found ~= SspFinding(no, "6.1", "ocn \"" ~ ocn ~ "\" is not a number"); break; } } auto rest = line[close + 2 .. $].split(" "); if (rest.length == 0 || !kinds.canFind(rest[0])) { found ~= SspFinding(no, "6.1", "\"" ~ ((rest.length > 0) ? rest[0] : "") ~ "\" is not one of the sixteen kinds"); } else if (rest[0] == "heading") { if (rest.length < 2 || rest[1].length < 2 || rest[1][0] != ':') { found ~= SspFinding(no, "6.1", "a heading declaration carries no \":level\""); } else if (!levels.canFind(rest[1][1 .. $])) { found ~= SspFinding(no, "6.1", "level \"" ~ rest[1][1 .. $] ~ "\" is not one of the eight"); } } in_object = true; in_text = false; prev_rank = -1; continue; } /+ ↓ section 6.3: properties, known and in order +/ if (line[0] == '.') { if (!in_object) { found ~= SspFinding(no, "6", "a property outside an object record"); continue; } if (in_text) { found ~= SspFinding(no, "6", "a property after the object text began"); } auto colon = line.indexOf(": "); if (colon < 2) { found ~= SspFinding(no, "3", "property is not \".name: value\""); continue; } string name = line[1 .. colon]; int rank = propertyRank(name); if (rank < 0) { found ~= SspFinding(no, "6.3", "." ~ name ~ " is not one of the " ~ property_order.length.to!string ~ " properties"); } else { /+ ↓ the four repeatable properties may recur at the same rank +/ if (rank < prev_rank) { found ~= SspFinding(no, "6.3", "." ~ name ~ " is out of the emitted order"); } prev_rank = rank; } continue; } /+ ↓ section 6.2: text lines +/ if (line[0] == '|') { if (!in_object) { found ~= SspFinding(no, "6.2", "a text line outside an object record"); } if (line.length < 2 || line[1] != ' ') { found ~= SspFinding(no, "6.2", "a text line is not \"| \" then the text"); } in_text = true; continue; } found ~= SspFinding(no, "3", "line of no shape the specification defines"); } if (!seen_banner) { found ~= SspFinding(0, "2", "no version banner"); } if (!seen_source_line) { found ~= SspFinding(0, "4", "no \"% Source:\" line"); } return found; } void reportValidation(string filename, SspFinding[] found) { if (found.length == 0) { writeln("\nvalid: ", filename, " conforms to the .ssp specification as this validator reads it"); return; } writefln("\n%d finding%s against the specification:", found.length, (found.length == 1) ? "" : "s"); foreach (f; found) { if (f.line > 0) { writefln(" line %-7d [%-4s] %s", f.line, f.section, f.detail); } else { writefln(" %-13s [%-4s] %s", "(file)", f.section, f.detail); } } }