summaryrefslogtreecommitdiffhomepage
path: root/gleam/src
diff options
context:
space:
mode:
Diffstat (limited to 'gleam/src')
-rw-r--r--gleam/src/ssp/parse.gleam284
-rw-r--r--gleam/src/ssp/types.gleam109
-rw-r--r--gleam/src/ssp_reader.gleam199
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))
+ }
+}