/////+ ////- Name: SisuDoc Spine, Doc Reform [a part of] //// - Description: documents, structuring, processing, publishing, search //// - static content generator //// //// - Author: Ralph Amissah //// [ralph.amissah@gmail.com] //// //// - Copyright: (C) 2015 (continuously updated, current 2026) Ralph Amissah, All Rights Reserved. //// //// - License: AGPL 3 or later: //// //// Spine (SiSU), a framework for document structuring, publishing and //// search //// //// Copyright (C) Ralph Amissah //// //// This program is free software: you can redistribute it and/or modify it //// under the terms of the GNU AFERO General Public License as published by the //// Free Software Foundation, either version 3 of the License, or (at your //// option) any later version. //// //// This program is distributed in the hope that it will be useful, but WITHOUT //// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or //// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for //// more details. //// //// You should have received a copy of the GNU General Public License along with //// this program. If not, see [https://www.gnu.org/licenses/]. //// //// If you have Internet connection, the latest version of the AGPL should be //// available at these locations: //// [https://www.fsf.org/licensing/licenses/agpl.html] //// [https://www.gnu.org/licenses/agpl.html] //// //// - Spine (by Doc Reform, related to SiSU) uses standard: //// - docReform markup syntax //// - standard SiSU markup syntax with modified headers and minor modifications //// - docReform object numbering //// - standard SiSU object citation numbering & system //// //// - Homepages: //// [https://www.sisudoc.org] //// [https://www.doc-reform.org] //// //// - Git //// [https://git.sisudoc.org/] //// ////+/ //// ocda-read, in Gleam: reads the abstraction, in any of the forms the //// library reads, and says what is in it. //// //// ocda-read [--tree|--outline|--languages|--files|--report-unknown] //// .ssp | .ocda.db | .zip [lang] //// //// The modes the Gleam readers had (the summary, the outline, the unknown //// report, and the database's languages and files), over the library, so //// that each reads every form. Their output is the D ocda-read's, byte for //// byte: two readers in unrelated languages, neither written from the other //// line by line, agreeing is what says each has read the model and not its //// own idea of it. A `.sisupod` is the one form the Gleam library cannot //// open (its zstd frame; see `ocda/load_pod`), and it says so. import gleam/dict import gleam/int import gleam/io import gleam/list import gleam/result import gleam/string import ocda/inventory.{type Language} import ocda/load import ocda/model.{type Document, type Object} /// The format major this reader knows. const major_read = "2" type Options { Options( tree: Bool, languages: Bool, files: Bool, report_unknown: Bool, any_version: Bool, lang: String, positional: List(String), ) } /// Run with the arguments after the program name; returns the exit status. pub fn run(args: List(String)) -> Int { case parse(args, Options(False, False, False, False, False, "", [])) { Error(message) -> { io.println_error("ocda-read: " <> message <> "; --help lists the options") 2 } Ok(Options(positional: [], ..)) -> { help() 0 } Ok(options) -> read(options) } } fn parse(args: List(String), o: Options) -> Result(Options, String) { case args { [] -> Ok(Options(..o, positional: list.reverse(o.positional))) ["--help", ..] | ["-h", ..] -> Ok(Options(..o, positional: [])) ["--tree", ..rest] | ["--outline", ..rest] -> parse(rest, Options(..o, tree: True)) ["--languages", ..rest] -> parse(rest, Options(..o, languages: True)) ["--files", ..rest] -> parse(rest, Options(..o, files: True)) ["--report-unknown", ..rest] -> parse(rest, Options(..o, report_unknown: True)) ["--any-version", ..rest] -> parse(rest, Options(..o, any_version: True)) ["--lang", code, ..rest] -> parse(rest, Options(..o, lang: code)) [flag, ..rest] -> case string.starts_with(flag, "--lang=") { True -> parse(rest, Options(..o, lang: string.drop_start(flag, 7))) False -> case string.starts_with(flag, "-") { True -> case list.contains( [ "--html", "--llm-text", "--llm-jsonl", "--images", "--verify", "--validate", ], flag, ) { True -> Error(flag <> " is a mode of the D ocda-read, not of this one") False -> Error("Unrecognized option " <> flag) } False -> parse(rest, Options(..o, positional: [flag, ..o.positional])) } } } } fn help() -> Nil { io.println("ocda-read - reads the document abstraction, in any of its forms") io.println("") io.println( "Usage: ocda-read [options] .ssp|.ocda.db|.zip [lang]", ) io.println("") io.println(" --tree the headings, as a tree") io.println(" --outline the same as --tree") io.println(" --languages the languages the file holds") io.println(" --files what a .ocda.db carries besides the abstraction") io.println(" --report-unknown what was read and not understood") io.println(" --lang= the language to read (default: the first)") io.println(" --any-version read a format major this reader does not know") } fn read(o: Options) -> Int { let assert [path, ..more] = o.positional let lang = case o.lang, more { "", [given, ..] -> given l, _ -> l } let lang_named = lang != "" let loaded = { use held <- result.try(inventory.languages(path)) let lang = case lang, held { "", [first, ..] -> first.lang l, _ -> l } use _ <- result.try(case held != [] && !list.any(held, fn(l) { l.lang == lang }) { True -> Error( "no language '" <> lang <> "' in " <> path <> "; it holds: " <> string.join(list.map(held, fn(l) { l.lang }), " "), ) False -> Ok(Nil) }) use doc <- result.try(load.load(path, lang, o.any_version)) Ok(#(held, lang, doc)) } case loaded { Error(message) -> { io.println_error("Error reading " <> path <> ": " <> message) 2 } Ok(#(held, lang, doc)) -> case gate(path, doc, o.any_version) { False -> 3 True -> { summary(path, doc, held, lang, lang_named) case o.languages { True -> print_languages(held) False -> Nil } case o.files { True -> print_files(path) False -> Nil } case o.tree { True -> tree(doc) False -> Nil } case o.report_unknown { True -> report_unknown(doc) False -> Nil } case o.tree || o.languages || o.files || o.report_unknown { True -> Nil False -> io.println( "\n(this is the summary: --help lists the modes, each adding its output)", ) } 0 } } } } /// The major part, and refuse what is not known. fn gate(path: String, doc: Document, any_version: Bool) -> Bool { case doc.format_version, model.version_major(doc) == major_read, any_version { "", _, _ -> { io.println_error("warning: " <> path <> " declares no format version") True } _, True, _ -> True v, False, True -> { io.println_error( "warning: " <> path <> " is format v" <> v <> ", this reader knows v" <> major_read <> ".x; reading anyway", ) True } v, False, False -> { io.println_error( "error: " <> path <> " is format v" <> v <> ", this reader knows v" <> major_read <> ".x", ) io.println_error( " a major version differs: a property may have changed meaning or gone away.", ) io.println_error(" --any-version reads it regardless.") False } } } const sections = [ "head", "toc", "body", "endnotes", "glossary", "bibliography", "bookindex", "blurb", "tail", ] /// The sections whose images are counted: every one but the tail, as the D /// reader counts them. const image_sections = [ "head", "toc", "body", "endnotes", "glossary", "bibliography", "bookindex", "blurb", ] fn summary( path: String, doc: Document, held: List(Language), lang: String, lang_named: Bool, ) -> Nil { io.println("Read: " <> path) case doc.format_version { "" -> Nil v -> io.println(" Format: v" <> v) } case dict.get(doc.source, "language") { Error(_) -> Nil Ok(language) -> { let of = case dict.get(doc.source, "languages") { Ok(ls) -> " of " <> ls Error(_) -> "" } let digest = case dict.get(doc.source, "digest") { Ok(d) -> ", markup digest " <> string.slice(d, 0, 16) <> "..." Error(_) -> "" } io.println(" Source: " <> language <> of <> digest) } } case list.length(held) > 1 && !lang_named { True -> io.println(" (reading " <> lang <> "; --lang= for another)") False -> Nil } io.println(" Title: " <> model.meta(doc, "title.main")) io.println(" Author: " <> model.meta(doc, "creator.author")) io.println( " Sections: " <> string.join( list.map(sections, fn(s) { s <> "=" <> int.to_string(list.length(model.section(doc, s))) }), " ", ), ) let records = list.fold(image_sections, 0, fn(n, s) { list.fold(model.section(doc, s), n, fn(n, o) { n + list.length(o.images) }) }) case records { 0 -> Nil 1 -> io.println(" Images: 1 record") n -> io.println(" Images: " <> int.to_string(n) <> " records") } } fn print_languages(held: List(Language)) -> Nil { io.println("") io.println(" lang source ssp digest") list.each(held, fn(l) { let digest = case string.length(l.ssp_digest) > 16 { True -> string.slice(l.ssp_digest, 0, 16) <> "..." False -> l.ssp_digest } io.println( " " <> string.pad_end(l.lang, 7, " ") <> " " <> string.pad_end(l.source_filename, 31, " ") <> " " <> digest, ) }) } fn print_files(path: String) -> Nil { io.println("") case inventory.is_carrier(path) { False -> io.println( " carried files: only a .ocda.db carries files; this is " <> load.source_name(load.source_of(path)), ) True -> case inventory.carried(path) { Error(message) -> io.println_error("error: " <> message) Ok([]) -> io.println(" carries no files") Ok(rows) -> { io.println(" carried files:") io.println(" role stored n original in the file") list.each(rows, fn(r) { io.println( " " <> string.pad_end(r.role, 9, " ") <> " " <> string.pad_end(r.compression, 7, " ") <> " " <> string.pad_end(r.count, 5, " ") <> " " <> string.pad_end(r.bytes, 13, " ") <> " " <> r.stored, ) }) } } } } /// The headings, as a tree: from the document's root heading, down the /// children each heading lists, as the D reader walks it. fn tree(doc: Document) -> Nil { io.println("Document: " <> model.meta(doc, "title.main")) case model.meta(doc, "title.subtitle") { "" -> Nil sub -> io.println(" " <> sub) } io.println("Author: " <> model.meta(doc, "creator.author")) io.println("") let headings = model.section(doc, "body") |> list.filter(fn(o) { o.is_a == "heading" && o.ocn > 0 }) |> list.map(fn(o) { #(o.ocn, o) }) |> dict.from_list case model.section(doc, "head") { [root, ..] if root.is_a == "heading" -> { io.println(heading_line(root, 0)) walk(root, headings, 1) } _ -> Nil } } fn walk(parent: Object, headings: dict.Dict(Int, Object), depth: Int) -> Nil { list.each(parent.children, fn(ocn) { case dict.get(headings, ocn) { Ok(child) -> { io.println(heading_line(child, depth)) walk(child, headings, depth + 1) } Error(_) -> Nil } }) } fn heading_line(o: Object, depth: Int) -> String { let level = case o.heading_level { "" -> "?" l -> l } let ocn = case o.ocn > 0 { True -> " [" <> int.to_string(o.ocn) <> "]" False -> "" } string.repeat(" ", depth) <> level <> "~" <> ocn <> " " <> strip_markup(o.text) } /// The internal markers a heading's text may carry, removed for display, as /// the D reader removes them. fn strip_markup(text: String) -> String { text |> string.replace("⑆*", "") |> string.replace("⑆!", "") |> string.replace("⑆/", "") |> string.replace("⑆_", "") |> string.replace("⑆^", "") |> string.replace("⑆,", "") |> string.replace("┨", "") |> string.replace("┣", "") |> string.replace("┙", " ") |> string.replace("┘", "\n") } /// Say what was read and not understood. fn report_unknown(doc: Document) -> Nil { let u = doc.unknown case model.any_unknown(u) { False -> io.println( "\nread and understood: every property, block and line was known", ) True -> { io.println("\nread and NOT understood:") section_of_unknown(u.property, " properties ignored (", fn(name, n) { " ." <> string.pad_end(name, 26, " ") <> " " <> string.pad_start(int.to_string(n), 8, " ") }) section_of_unknown(u.block, " blocks ignored (", fn(name, n) { " @" <> string.pad_end(name, 26, " ") <> " " <> string.pad_start(int.to_string(n), 8, " ") }) case dict.size(u.line) { 0 -> Nil _ -> { io.println(" lines of no known shape, by first character:") dict.to_list(u.line) |> list.sort(fn(a, b) { string.compare(a.0, b.0) }) |> list.each(fn(e) { io.println( " " <> string.pad_end("\"" <> e.0 <> "\"", 27, " ") <> " " <> string.pad_start(int.to_string(e.1), 8, " "), ) }) } } io.println( " (ignoring these is conforming within a major version; the count is so that it is not silent)", ) } } } fn section_of_unknown( counts: dict.Dict(String, Int), heading: String, line: fn(String, Int) -> String, ) -> Nil { case dict.size(counts) { 0 -> Nil n -> { io.println(heading <> int.to_string(n) <> " distinct):") dict.to_list(counts) |> list.sort(fn(a, b) { string.compare(a.0, b.0) }) |> list.each(fn(e) { io.println(line(e.0, e.1)) }) } } }