(* SPDX-License-Identifier: AGPL-3.0-or-later *)

(** Bible books: one canonical id per book, and the tradition that decides
    which book an id denotes.

    Ids follow the VULGATE structure ([kings_3], [esdras_2],
    [ecclesiasticus]), because the Vulgate is the default tradition and the
    shipped 1962 data is Vulgate throughout. An id is internal -- it is never
    shown to a reader, exactly as a slug is never shown. *)

type id

val to_string : id -> string

(** Resolve one spelling as it appears in the data. Returns [None] for
    anything not in {!tokens}.

    SIXTEEN books arrive in more than one spelling, surveyed across all
    three citation-bearing files ([lectionary.sexp], [sanctoral.sexp],
    [commons.sexp] -- not the lectionary alone, which undercounts: the
    sanctoral propers alone carry more citations than the lectionary does).
    Most are a dotted/undotted pair ([Isa]/[Isa.], [3 Kgs.]/[3 Kings], and
    others); two also carry a MODERN spelling sitting inside otherwise-
    Vulgate data ([Sir] alongside [Ecclus]/[Eccli], [Rev] alongside [Apoc]).
    All of this is INHERITED from lectio's own ini, which is itself
    generated from missalemeum/Divinum Officium -- it is not a colitur
    transcription error, and the data is deliberately left untouched. Every
    accepted spelling resolves here to the same, single Vulgate id: [Sir]
    resolves to [ecclesiasticus] and [Rev] to [apocalypse], never to the
    tradition-only targets [sirach]/[revelation] -- see those below. *)
val of_token : string -> id option

(** Every id this build knows, for coverage checks. *)
val all : id list

(** Every accepted spelling paired with its id. *)
val tokens : (string * id) list

(** The first spelling registered for an id -- the form the shipped data
    itself uses ([luke] -> ["Luke"], [kings_3] -> ["3 Kings"]).

    This is the FALLBACK display name, and it exists because the obvious
    alternative is actively worse. A language file's [\[bible\]] lookup is
    total and returns THE KEY on a miss, so a book with no entry would
    otherwise render as ["luke.abbr 5:12-14"]. Falling back here instead makes
    an unnamed book render as ["Luke 5:12-14"] -- exactly what colitur printed
    before this feature existed. The degraded case is the OLD behaviour, not a
    broken page, the same principle {!Colitur_naming.Lang} states for its own
    key-returning misses.

    An id with no registered spelling -- only a {!tradition} target such as
    [kings_1] or [sirach], which the Vulgate data never cites -- returns the id
    itself. Reachable only from a user language file that selects a tradition
    without naming its target books; every SHIPPED language file is asserted
    complete over {!all}. *)
val default_spelling : id -> string

(** A numbering tradition: which book an id denotes. Separate from NAMING
    (what a book is called), which lives in a language file's [\[bible\]]
    section, because naming varies by language and this does not -- "modern
    numbering" is the same decision in Latin, Polish and English. *)
type tradition

(** The identity tradition: the Vulgate, as the 1962 Missal prints it. The
    default; colitur never silently renumbers. *)
val vulgate : tradition

(** Build a tradition from an ini section's fields. An entry naming an
    unknown id on either side is IGNORED, not fatal: a traditions file
    written for a newer colitur must still work on an older one. Use
    {!unknown_fields} to report them. *)
val tradition_of_fields : (string * string) list -> tradition

(** The fields {!tradition_of_fields} silently dropped -- either side naming
    an id outside {!all}. Never raises; a caller that cares can report these,
    a caller that does not can ignore the return value entirely. *)
val unknown_fields : (string * string) list -> string list

val map : tradition -> id -> id