From a2cbb6b85e79fbc59b0879362c0f853757d51c07 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Thu, 20 Aug 2026 15:09:49 +0200 Subject: feat(citation): render a parsed citation in a configurable style A style is a set of format strings, so punctuation convention is data. Values are unquoted here rather than in Overlay_ini: that parser trims every value and is shared with overlays and [defaults], so teaching it about quotes would change behaviour this feature has no business changing. --- lib/citation/render.ml | 107 ++++++++++++++++++++++++++++++++++++++++++++++++ lib/citation/render.mli | 48 ++++++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 lib/citation/render.ml create mode 100644 lib/citation/render.mli (limited to 'lib') diff --git a/lib/citation/render.ml b/lib/citation/render.ml new file mode 100644 index 0000000..c66a0ca --- /dev/null +++ b/lib/citation/render.ml @@ -0,0 +1,107 @@ +(* SPDX-License-Identifier: AGPL-3.0-or-later *) + +type style = { + book : [ `Full | `Abbr ]; + book_sep : string; + chapter_verse : string; + range : string; + part_sep : string; + verse_sep : string; +} + +let default_style = + { book = `Abbr; + book_sep = " "; + chapter_verse = "{chapter}:{verses}"; + range = "{first}-{last}"; + part_sep = "; "; + verse_sep = ", " } + +let part_sep st = st.part_sep +let range st = st.range +let book_sep st = st.book_sep + +(* Arabic -> Roman, for the {chapter_roman} placeholder. Lifted from + [Colitur_render.View.roman_numeral], which prints "Hebdomada I" week + headings -- roman numerals are idiomatic throughout this project's + output ("Feria IV"), so a citation style may want them too. *) +let roman_numeral n = + if n <= 0 then string_of_int n + else + let table = + [ (1000, "M"); (900, "CM"); (500, "D"); (400, "CD"); (100, "C"); + (90, "XC"); (50, "L"); (40, "XL"); (10, "X"); (9, "IX"); + (5, "V"); (4, "IV"); (1, "I") ] + in + let b = Buffer.create 8 in + let n = ref n in + List.iter + (fun (v, sym) -> + while !n >= v do + Buffer.add_string b sym; + n := !n - v + done) + table; + Buffer.contents b + +let with_book b st = { st with book = b } + +(* One matching pair of surrounding double quotes, and only that -- see the + .mli for why this is not in Overlay_ini. *) +let unquote s = + let n = String.length s in + if n >= 2 && s.[0] = '"' && s.[n - 1] = '"' then String.sub s 1 (n - 2) else s + +(* Replace {name} with its value. An UNKNOWN placeholder survives + literally: a typo in a hand-written style file must be visible in the + output, not silently swallowed. *) +let subst tmpl pairs = + let n = String.length tmpl in + let b = Buffer.create (n + 16) in + let i = ref 0 in + while !i < n do + if tmpl.[!i] = '{' then + match String.index_from_opt tmpl !i '}' with + | None -> + Buffer.add_char b tmpl.[!i]; + incr i + | Some j -> + let name = String.sub tmpl (!i + 1) (j - !i - 1) in + (match List.assoc_opt name pairs with + | Some v -> Buffer.add_string b v + | None -> Buffer.add_string b (String.sub tmpl !i (j - !i + 1))); + i := j + 1 + else begin + Buffer.add_char b tmpl.[!i]; + incr i + end + done; + Buffer.contents b + +let render st ~names (t : Parse.t) = + let one_range (r : Parse.verse_range) = + match r.Parse.last with + | None -> string_of_int r.Parse.first + | Some l -> + subst st.range + [ ("first", string_of_int r.Parse.first); + ("last", string_of_int l) ] + in + let one_part (p : Parse.part) = + let verses = String.concat st.verse_sep (List.map one_range p.Parse.verses) in + subst st.chapter_verse + [ ("chapter", string_of_int p.Parse.chapter); + ("chapter_roman", roman_numeral p.Parse.chapter); + ("verses", verses) ] + in + let body = String.concat st.part_sep (List.map one_part t.Parse.parts) in + names t.Parse.book st.book ^ st.book_sep ^ body + +let style_of_fields fields = + let get k d = match List.assoc_opt k fields with Some v -> unquote v | None -> d in + { book = (if get "book" "abbr" = "full" then `Full else `Abbr); + book_sep = get "book_sep" default_style.book_sep; + chapter_verse = get "chapter_verse" default_style.chapter_verse; + range = get "range" default_style.range; + part_sep = get "part_sep" default_style.part_sep; + verse_sep = get "verse_sep" default_style.verse_sep } diff --git a/lib/citation/render.mli b/lib/citation/render.mli new file mode 100644 index 0000000..d741931 --- /dev/null +++ b/lib/citation/render.mli @@ -0,0 +1,48 @@ +(* SPDX-License-Identifier: AGPL-3.0-or-later *) + +(** Turn a parsed citation back into text, in a configurable style. + + A style is data, not code, so a tradition of punctuation is a file + someone can write: [Luke 5:12-14], [Lk 5:12-14], [Luke 5.12-14], + [{L}k 5, 12-14] are all the same citation in different conventions. + + Placeholders: [{chapter}], [{chapter_roman}] and [{verses}] in + [chapter_verse]; [{first}] and [{last}] in [range]. An UNKNOWN + placeholder survives literally, so a typo is visible in the output + rather than silently swallowed. *) + +type style + +(** The Vulgate/Latin convention: abbreviated book, [chapter:verses], + [first-last], ["; "] between parts, [", "] between verse ranges. *) +val default_style : style + +(** Read a style from a language file's [\[sigla\]] section. + + Values are UNQUOTED here: one matching pair of surrounding double quotes + is stripped, so a separator's significant trailing space survives. + {!Colitur_kernel.Overlay_ini} trims every value and has no quote + handling, and it is shared with overlays and [\[defaults\]] -- so the + unquoting belongs here, not there. An unrecognised key is ignored; + a missing key keeps {!default_style}'s value. *) +val style_of_fields : (string * string) list -> style + +(** Override the book form, for the [sigla_book] config key. *) +val with_book : [ `Full | `Abbr ] -> style -> style + +val part_sep : style -> string +val range : style -> string + +(** What separates the book name from the reference. Default [" "]. + + Settable because a typeset booklet wants a NON-BREAKING space here -- a + line break between "Luc." and "3, 1" is exactly the ugliness this + prevents. Set it to a literal U+00A0: the escapers match ASCII bytes + only, so a UTF-8 multibyte sequence passes through every flavour + untouched (verified for latex, typst, groff, html, xml, ics). A LaTeX + tie [~] does NOT work -- {!Colitur_render.Escape} turns it into + [\textasciitilde{}]. *) +val book_sep : style -> string + +val render : + style -> names:(Book.id -> [ `Full | `Abbr ] -> string) -> Parse.t -> string -- cgit v1.3