diff options
Diffstat (limited to 'gleam/src')
| -rw-r--r-- | gleam/src/ssp/parse.gleam | 284 | ||||
| -rw-r--r-- | gleam/src/ssp/types.gleam | 109 | ||||
| -rw-r--r-- | gleam/src/ssp_reader.gleam | 199 |
3 files changed, 592 insertions, 0 deletions
diff --git a/gleam/src/ssp/parse.gleam b/gleam/src/ssp/parse.gleam new file mode 100644 index 0000000..9458317 --- /dev/null +++ b/gleam/src/ssp/parse.gleam @@ -0,0 +1,284 @@ +//// Parsing a .ssp. +//// +//// Specification section 3: the format is line oriented, and every line +//// is one of eight shapes told apart by its first character. So the +//// parser is a fold over the lines carrying the state the shapes need. + +import gleam/dict.{type Dict} +import gleam/int +import gleam/list +import gleam/option +import gleam/string +import ssp/types.{type Document, type Object, type Section, Object, Section} + +/// specification section 6.1: the sixteen kinds +pub const kinds = [ + "para", "heading", "toc", "bookindex", "endnote", "code", "bibliography", + "comment", "verse", "glossary", "quote", "poem", "block", "table", "blurb", + "group", +] + +/// specification section 4: the four preamble blocks +pub const preamble_blocks = ["source", "meta", "make", "doc_has"] + +/// specification section 4: the nine sections, in the order they appear +pub const section_names = [ + "head", "toc", "body", "endnotes", "glossary", "bibliography", "bookindex", + "blurb", "tail", +] + +/// specification section 6.3: the 42 properties, in the order emitted +pub const properties = [ + "identifier", "part", "section", "parent", "last_descendant", "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", +] + +/// The properties this reader makes use of. The rest are counted and +/// ignored, which is conforming behaviour within a major version +/// (specification section 8.1) so long as it is not done in silence. +const properties_used = [ + "part", "parent", "ancestors", "is_of_type", "identifier", +] + +type State { + State( + document: Document, + /// the block currently open, "" when none + block: String, + /// the section currently open, "" when in the preamble + section: String, + /// objects of the current section, newest first + objects: List(Object), + /// the object being read, if any + current: Result(Object, Nil), + /// sections completed, newest first + done: List(Section), + ) +} + +pub fn parse(content: String) -> Document { + let state = + content + |> string.split(on: "\n") + |> list.fold(from: initial_state(), with: line) + finish(state) +} + +fn initial_state() -> State { + State( + document: types.new_document(), + block: "", + section: "", + objects: [], + current: Error(Nil), + done: [], + ) +} + +fn line(state: State, raw: String) -> State { + case raw { + "" -> commit_object(state) + "% SiSU Document Abstraction v" <> version -> + State( + ..state, + document: types.Document( + ..state.document, + version: string.trim(version), + ), + ) + "% Source: " <> filename -> + State( + ..state, + document: types.Document( + ..state.document, + source_filename: string.trim(filename), + ), + ) + "%" <> _ -> state + "@" <> rest -> open_block(state, rest) + "}" -> close_block(state) + " " <> rest -> preamble_pair(state, rest) + "[" <> rest -> declaration(state, rest) + "." <> rest -> property(state, rest) + "| " <> rest -> text_line(state, rest) + _ -> + State( + ..state, + document: types.Document( + ..state.document, + malformed_lines: state.document.malformed_lines + 1, + ), + ) + } +} + +fn open_block(state: State, rest: String) -> State { + let name = case string.split_once(rest, " {") { + Ok(#(name, _)) -> name + Error(_) -> rest + } + case list.contains(preamble_blocks, name), list.contains(section_names, name) { + True, _ -> State(..state, block: name) + _, True -> State(..state, block: name, section: name, objects: []) + _, _ -> + State( + ..state, + block: name, + document: types.Document( + ..state.document, + unknown_blocks: bump(state.document.unknown_blocks, name), + ), + ) + } +} + +fn close_block(state: State) -> State { + let state = commit_object(state) + case state.section { + "" -> State(..state, block: "") + name -> + State( + ..state, + block: "", + section: "", + objects: [], + done: [Section(name: name, objects: list.reverse(state.objects)), ..state.done], + ) + } +} + +fn preamble_pair(state: State, rest: String) -> State { + case string.split_once(rest, ": ") { + Error(_) -> state + Ok(#(key, value)) -> { + let document = state.document + let document = case state.block { + "source" -> + types.Document(..document, source: dict.insert(document.source, key, value)) + "meta" -> + types.Document(..document, meta: dict.insert(document.meta, key, value)) + "make" -> + types.Document(..document, make: dict.insert(document.make, key, value)) + "doc_has" -> + types.Document( + ..document, + doc_has: dict.insert(document.doc_has, key, value), + ) + _ -> document + } + State(..state, document: document) + } + } +} + +/// specification section 6.1 +/// [<ocn>] <kind> +/// [<ocn>] heading :<level> +/// [<ocn>] heading :<level> <identifier> +fn declaration(state: State, rest: String) -> State { + let state = commit_object(state) + case string.split_once(rest, "] ") { + Error(_) -> state + Ok(#(ocn_text, tail)) -> { + let ocn = case int.parse(ocn_text) { + Ok(n) -> n + Error(_) -> 0 + } + let object = case string.split(tail, on: " ") { + ["heading", level, ..identifier] -> + Object( + ..types.new_object(), + ocn: ocn, + kind: "heading", + level: string.drop_start(level, 1), + identifier: string.join(identifier, " "), + ) + [kind, ..] -> Object(..types.new_object(), ocn: ocn, kind: kind) + [] -> types.new_object() + } + State(..state, current: Ok(object)) + } + } +} + +fn property(state: State, rest: String) -> State { + case state.current, string.split_once(rest, ": ") { + Ok(object), Ok(#(name, value)) -> { + let object = + Object(..object, properties: [#(name, value), ..object.properties]) + let object = case name { + "part" -> Object(..object, part: value) + "is_of_type" -> Object(..object, is_of_type: value) + "identifier" -> Object(..object, identifier: value) + "parent" -> + Object(..object, parent: case int.parse(value) { + Ok(n) -> n + Error(_) -> 0 + }) + "ancestors" -> Object(..object, ancestors: numbers(value)) + _ -> object + } + // a property this reader does not use, whether or not the + // specification names it, is counted rather than passed over: within + // a major version ignoring it is conforming, doing so in silence is + // what stops a reader being a check on the specification + let document = case list.contains(properties_used, name) { + True -> state.document + False -> + types.Document( + ..state.document, + unknown_properties: bump(state.document.unknown_properties, name), + ) + } + State(..state, current: Ok(object), document: document) + } + _, _ -> state + } +} + +fn text_line(state: State, rest: String) -> State { + case state.current { + Ok(object) -> State(..state, current: Ok(Object(..object, text: [rest, ..object.text]))) + Error(_) -> state + } +} + +fn commit_object(state: State) -> State { + case state.current { + Error(_) -> state + Ok(object) -> + State( + ..state, + current: Error(Nil), + objects: [Object(..object, text: list.reverse(object.text), + properties: list.reverse(object.properties)), ..state.objects], + ) + } +} + +fn finish(state: State) -> Document { + let state = close_block(commit_object(state)) + types.Document(..state.document, sections: list.reverse(state.done)) +} + +fn bump(counts: Dict(String, Int), key: String) -> Dict(String, Int) { + dict.upsert(counts, key, fn(existing) { + case existing { + option.Some(n) -> n + 1 + option.None -> 1 + } + }) +} + +fn numbers(value: String) -> List(Int) { + value + |> string.split(on: " ") + |> list.filter_map(int.parse) +} diff --git a/gleam/src/ssp/types.gleam b/gleam/src/ssp/types.gleam new file mode 100644 index 0000000..1e98886 --- /dev/null +++ b/gleam/src/ssp/types.gleam @@ -0,0 +1,109 @@ +//// The .ssp document abstraction, as Gleam types. +//// +//// Written from the doc-abstraction-format specification, +//// ssp-format-specification.md and ocda-model.md, and from nothing else: the exercise is to find out +//// whether the specification suffices to write a reader from. + +import gleam/dict.{type Dict} +import gleam/string + +/// The format major version this reader knows. +/// +/// Specification section 2.1: a reader checks the major part and refuses +/// what it does not know, rather than loading an unfamiliar artefact half +/// populated in silence. +pub const format_major_read = "2" + +/// One object of the abstraction. +/// +/// Model section 2: an object carries a citation number, a kind and a +/// type, its place in the structure, its text and a digest of the text. +pub type Object { + Object( + ocn: Int, + /// section 6.1: one of the sixteen kinds + kind: String, + /// headings only: A B C D 1 2 3 4 + level: String, + identifier: String, + /// section 6.3: how the text behaves, para / block / comment + is_of_type: String, + part: String, + parent: Int, + ancestors: List(Int), + /// every property as read, in the order read, including the ones + /// this reader has no use for + properties: List(#(String, String)), + /// section 6.2, in order, without the "| " prefix + text: List(String), + ) +} + +pub fn new_object() -> Object { + Object( + ocn: 0, + kind: "", + level: "", + identifier: "", + is_of_type: "", + part: "", + parent: 0, + ancestors: [], + properties: [], + text: [], + ) +} + +/// Model section 2.1: the type says how the text behaves, and "comment" +/// is markup commentary that no output carries. +pub fn renders(object: Object) -> Bool { + object.is_of_type != "comment" +} + +/// One section of a document, in the order of section 4. +pub type Section { + Section(name: String, objects: List(Object)) +} + +pub type Document { + Document( + /// as declared on the first line, "" when absent + version: String, + source_filename: String, + /// the four preamble blocks of section 5 + source: Dict(String, String), + meta: Dict(String, String), + make: Dict(String, String), + doc_has: Dict(String, String), + sections: List(Section), + /// what was met and not understood, counted rather than dropped in + /// silence: a reader that cannot say what it ignored cannot show that + /// a specification is complete + unknown_properties: Dict(String, Int), + unknown_blocks: Dict(String, Int), + malformed_lines: Int, + ) +} + +pub fn new_document() -> Document { + Document( + version: "", + source_filename: "", + source: dict.new(), + meta: dict.new(), + make: dict.new(), + doc_has: dict.new(), + sections: [], + unknown_properties: dict.new(), + unknown_blocks: dict.new(), + malformed_lines: 0, + ) +} + +/// The major part of the declared version, "" when none was declared. +pub fn version_major(document: Document) -> String { + case string.split_once(document.version, ".") { + Ok(#(major, _)) -> major + Error(_) -> document.version + } +} diff --git a/gleam/src/ssp_reader.gleam b/gleam/src/ssp_reader.gleam new file mode 100644 index 0000000..d8c4c78 --- /dev/null +++ b/gleam/src/ssp_reader.gleam @@ -0,0 +1,199 @@ +//// ssp-reader, in Gleam. +//// +//// Reads a .ssp, the object-centric document abstraction written as text, +//// and says what it found and what it did not understand. +//// +//// Written from the specification alone: +//// ssp-format-specification.md, of the doc-abstraction-format spec +//// ocda-model.md, of the same + +import argv +import gleam/dict +import gleam/int +import gleam/io +import gleam/list +import gleam/result +import gleam/string +import simplifile +import ssp/parse +import ssp/types.{type Document, type Object} + +pub fn main() -> Nil { + case argv.load().arguments { + [] -> usage() + args -> { + let any_version = list.contains(args, "--any-version") + let outline = list.contains(args, "--outline") + let report = list.contains(args, "--report-unknown") + case list.filter(args, fn(a) { !string.starts_with(a, "--") }) { + [path, ..] -> run(path, any_version, outline, report) + [] -> usage() + } + } + } +} + +fn usage() -> Nil { + io.println("ssp-reader - reads a .ssp and says what is in it") + io.println("") + io.println(" ssp_reader [options] <file.ssp>") + io.println("") + io.println(" --outline the headings, as a tree") + io.println(" --report-unknown what was read and not understood") + io.println(" --any-version read a format major this reader does not know") +} + +fn run(path: String, any_version: Bool, outline: Bool, report: Bool) -> Nil { + case simplifile.read(from: path) { + Error(_) -> io.println("error: cannot read " <> path) + Ok(content) -> { + let document = parse.parse(content) + case version_ok(document, any_version) { + False -> Nil + True -> { + summary(document, path) + case outline { + True -> print_outline(document) + False -> Nil + } + case report { + True -> print_unknown(document) + False -> Nil + } + } + } + } + } +} + +/// Specification section 2.1: check the major part and refuse what is not +/// known, rather than loading an unfamiliar artefact half populated. +fn version_ok(document: Document, any_version: Bool) -> Bool { + let major = types.version_major(document) + case document.version, major == types.format_major_read, any_version { + "", _, _ -> { + io.println("warning: no version banner, reading anyway") + True + } + _, True, _ -> True + _, False, True -> { + io.println( + "warning: format v" + <> document.version + <> ", this reader knows v" + <> types.format_major_read + <> ".x; reading anyway", + ) + True + } + _, False, False -> { + io.println( + "error: format v" + <> document.version + <> ", this reader knows v" + <> types.format_major_read + <> ".x", + ) + io.println( + " a major version differs: a property may have changed meaning", + ) + io.println(" --any-version reads it regardless.") + False + } + } +} + +fn summary(document: Document, path: String) -> Nil { + io.println("Parsed: " <> path) + io.println(" Format: v" <> document.version) + io.println(" Source: " <> document.source_filename) + case dict.get(document.source, "language") { + Ok(language) -> io.println(" Language: " <> language) + Error(_) -> Nil + } + io.println(" Title: " <> meta(document, "title.main")) + io.println(" Author: " <> meta(document, "creator.author")) + let counts = + document.sections + |> list.map(fn(s) { s.name <> "=" <> int.to_string(list.length(s.objects)) }) + |> string.join(" ") + io.println(" Sections: " <> counts) +} + +fn meta(document: Document, key: String) -> String { + document.meta |> dict.get(key) |> result.unwrap("") +} + +/// The headings, indented by level. Model section 4: the eight levels are +/// A to D for the title matter and 1 to 4 for the body. +fn print_outline(document: Document) -> Nil { + io.println("") + document.sections + |> list.each(fn(section) { + section.objects + |> list.filter(fn(o) { o.kind == "heading" && types.renders(o) }) + |> list.each(fn(o) { io.println(heading_line(o)) }) + }) +} + +fn heading_line(object: Object) -> String { + let depth = case object.level { + "A" -> 0 + "B" -> 1 + "C" -> 2 + "D" -> 3 + "1" -> 4 + "2" -> 5 + "3" -> 6 + "4" -> 7 + _ -> 8 + } + string.repeat(" ", depth) + <> object.level + <> "~ [" + <> int.to_string(object.ocn) + <> "] " + <> first_line(object.text) +} + +fn first_line(text: List(String)) -> String { + case text { + [line, ..] -> line + [] -> "" + } +} + +/// A reader that drops what it does not know is conforming; one that +/// cannot say what it dropped cannot show a specification to be complete. +fn print_unknown(document: Document) -> Nil { + io.println("") + case dict.size(document.unknown_properties) { + 0 -> io.println("read and understood: every property was used") + n -> { + io.println("read and not used (" <> int.to_string(n) <> " distinct):") + document.unknown_properties + |> dict.to_list + |> list.sort(fn(a, b) { string.compare(a.0, b.0) }) + |> list.each(fn(pair) { + io.println( + " ." <> pair.0 <> " " <> int.to_string(pair.1), + ) + }) + } + } + case dict.size(document.unknown_blocks) { + 0 -> Nil + _ -> { + io.println("blocks not understood:") + document.unknown_blocks + |> dict.to_list + |> list.each(fn(pair) { + io.println(" @" <> pair.0 <> " " <> int.to_string(pair.1)) + }) + } + } + case document.malformed_lines { + 0 -> Nil + n -> io.println("lines of no known shape: " <> int.to_string(n)) + } +} |
