1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
(** The config file: what the user wants by default, and where each value came
from.
Owns precedence and provenance and nothing else. Never reads the filesystem
-- callers hand it text -- so it is as testable as the language table.
A config file is OPTIONAL. With none, colitur behaves exactly as it does
without this feature, except that names resolve through the default
language. *)
type t
val empty : t
val of_string : string -> (t, string) result
(** [lang], [template] and [format] are each set from a single field. A
repeated key is LAST-WINS -- the opposite direction from
{!Colitur_kernel.Overlay_ini.get}'s first-wins over the same [section]
type -- because the natural reading of a config file a user edited by
hand and appended to is "the bottom line is the one that took effect".
This holds whether the repeat is within one [\[defaults\]] block or
across two of them: every section named [defaults] is merged, not only
the first, the same duplicate-section policy {!Lang.of_string} documents
for its own sections -- the two modules read the same underlying format
and must not disagree about what a repeated header means. *)
val lang : t -> string option
val overlays : t -> string list
val template : t -> string option
val format : t -> string option
(** Which citation style to render a reference in: a language CODE, looked
up the same way {!lang} is, or a path -- but a DIFFERENT axis from
{!lang}: a language file's own [\[sigla\]] section IS a style
({!Colitur_citation.Render.style_of_fields}), and this key SELECTS
which file's [\[sigla\]] section supplies it, independently of which
file's other sections supply names elsewhere (a booklet may want
Polish names but Latin-convention citations). Same last-wins duplicate
policy as {!lang}. *)
val sigla_style : t -> string option
(** [full] or [abbr] -- overrides the style's own [book] setting rather than
replacing the style outright, so a chosen style's punctuation survives
even when the book form is overridden ({!Colitur_citation.Render.with_book}).
Same last-wins duplicate policy as {!lang}. *)
val sigla_book : t -> string option
(** The name of a section in [lang/traditions.ini] -- which BOOK a reference
DENOTES (Vulgate numbering by default), a different question again from
both {!sigla_style} (how a reference is WRITTEN) and {!lang} (what
everything else is CALLED): naming and numbering both vary by
convention, but not together. Same last-wins duplicate policy as
{!lang}. *)
val sigla_tradition : t -> string option
(** Keys present in the [\[defaults\]] section that this build does not
understand. Reported, never fatal: a config written for a newer colitur
must still work on an older one, but silently ignoring a line the user
wrote is how a typo becomes invisible. *)
val unknown_keys : t -> string list
(** Section names other than [\[defaults\]], reported separately from
{!unknown_keys} so the CLI can word the two warnings differently (a
misspelled section, e.g. [\[deafults\]], versus a misspelled key inside a
recognised one). Also never fatal, and never silent: a section this build
does not recognise is exactly the highest-value typo this feature exists
to catch, because it silently discards the whole section -- [lang] and
everything else in it -- with no other way for the user to notice. *)
val unknown_sections : t -> string list
(** [resolve ~flag ~config ~default] returns [(value, source)] with source one of
["flag"], ["config"], ["default"]. Precedence is flag > config > default. *)
val resolve : flag:string option -> config:string option -> default:string -> string * string
|
