mla_titlecase/analysis.rs
1//! Rich analysis output: per-word casing decisions and their confidence.
2//!
3//! [`crate::titlecase_analyze`] returns a [`TitleCaseAnalysis`] alongside the
4//! cased string, recording which rule decided every word token and how much to
5//! trust it (with a `changed` flag per span for callers that only want edits).
6
7use core::ops::Range;
8
9/// How much to trust a casing decision.
10///
11/// The tiers are ordered by concern for review: [`Confidence::Solid`] is safest,
12/// [`Confidence::Heuristic`] most warrants a human look.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum Confidence {
15 /// A structural MLA rule or an explicit lexicon/protected match. Not a guess.
16 Solid,
17 /// An ordinary word capitalized with no lexicon to confirm it is not a name
18 /// or brand that should be spelled differently. Correct under MLA, but the
19 /// open-world "a lexicon might disagree" case applies.
20 Unverified,
21 /// A heuristic that could genuinely be wrong: particle detection, all-caps
22 /// word-versus-acronym classification, or a dual-role preposition.
23 Heuristic,
24}
25
26impl Confidence {
27 fn rank(self) -> u8 {
28 match self {
29 Confidence::Solid => 0,
30 Confidence::Unverified => 1,
31 Confidence::Heuristic => 2,
32 }
33 }
34
35 /// Returns the more concerning (less confident) of two tiers.
36 #[must_use]
37 pub fn most_concerning(self, other: Self) -> Self {
38 if other.rank() > self.rank() {
39 other
40 } else {
41 self
42 }
43 }
44}
45
46/// The rule that decided a word's casing.
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
48#[non_exhaustive]
49pub enum CasingRule {
50 /// Capitalized as the first significant word of the title.
51 FirstWord,
52 /// Capitalized as the last significant word of the title.
53 LastWord,
54 /// Capitalized as the first or last word across a subtitle boundary
55 /// (colon, question mark, or exclamation point).
56 SubtitleBoundary,
57 /// Capitalized as part of a hyphenated compound.
58 HyphenatedCompound,
59 /// Lowercased as an MLA small word (article, conjunction, preposition).
60 SmallWord,
61 /// Capitalized as the adverbial particle of a phrasal verb (heuristic).
62 AdverbialParticle,
63 /// Lowercased as a name particle inside a likely personal name (heuristic).
64 NameParticle,
65 /// Lowercased as the `'n'` contraction of "and".
66 ContractedAnd,
67 /// Kept as a protected spelling (user, built-in, or external).
68 ProtectedSpelling,
69 /// Rendered from the built-in abbreviation list (e.g. `NASA`).
70 Abbreviation,
71 /// Rendered as a dotted initialism (e.g. `U.S.A.`).
72 DottedAbbreviation,
73 /// Rendered from an external canonical-spelling lexicon.
74 CanonicalLexicon,
75 /// Rendered from an external multiword-phrase lexicon.
76 MultiwordLexicon,
77 /// Recased from all-caps input to title case (heuristic).
78 AllCapsNormalized,
79 /// Left all-caps as a likely acronym under a dictionary-gated policy (heuristic).
80 AllCapsPreservedAcronym,
81 /// Left all-caps as a likely acronym among mixed-case words (heuristic).
82 AcronymPreserved,
83 /// Preserved because the input already had internal capitals (e.g. `iPhone`).
84 MixedCasePreserved,
85 /// Capitalized as an ordinary word with no lexicon confirmation.
86 Capitalized,
87}
88
89impl CasingRule {
90 /// The confidence for this rule, before any word-specific refinement.
91 #[must_use]
92 pub fn confidence(self) -> Confidence {
93 match self {
94 CasingRule::FirstWord
95 | CasingRule::LastWord
96 | CasingRule::SubtitleBoundary
97 | CasingRule::HyphenatedCompound
98 | CasingRule::SmallWord
99 | CasingRule::ContractedAnd
100 | CasingRule::ProtectedSpelling
101 | CasingRule::Abbreviation
102 | CasingRule::DottedAbbreviation
103 | CasingRule::CanonicalLexicon
104 | CasingRule::MultiwordLexicon
105 | CasingRule::MixedCasePreserved => Confidence::Solid,
106
107 CasingRule::AdverbialParticle
108 | CasingRule::NameParticle
109 | CasingRule::AllCapsNormalized
110 | CasingRule::AllCapsPreservedAcronym
111 | CasingRule::AcronymPreserved => Confidence::Heuristic,
112
113 CasingRule::Capitalized => Confidence::Unverified,
114 }
115 }
116}
117
118/// One word's casing decision: the rule behind it, how much to trust it, and
119/// whether it actually changed the input.
120///
121/// `source` and `output` are byte ranges into the original input and the
122/// [`TitleCaseAnalysis::output`] string respectively.
123#[derive(Debug, Clone, PartialEq, Eq)]
124#[non_exhaustive]
125pub struct CasingSpan {
126 /// Byte range of the word in the original input.
127 pub source: Range<usize>,
128 /// Byte range of the word in the produced output.
129 pub output: Range<usize>,
130 /// The rule that decided this word's casing.
131 pub rule: CasingRule,
132 /// How much to trust the decision.
133 pub confidence: Confidence,
134 /// Whether the output text differs from the source text. `false` means the
135 /// rule confirmed the input was already correct (still useful to know a
136 /// heuristic was involved).
137 pub changed: bool,
138}
139
140/// The result of [`crate::titlecase_analyze`]: the cased string, one span per
141/// casing decision, and an overall confidence.
142#[derive(Debug, Clone, PartialEq, Eq)]
143#[non_exhaustive]
144pub struct TitleCaseAnalysis {
145 /// The title-cased output.
146 pub output: String,
147 /// The least-confident tier across the recorded spans;
148 /// [`Confidence::Solid`] when there are none.
149 pub confidence: Confidence,
150 /// One entry per casing decision, in order. Usually one span per word token,
151 /// but a multiword lexicon match records a single span covering the whole
152 /// phrase, and [`crate::AllCapsPolicy::Preserve`] on shouting input records
153 /// none (the input is returned verbatim). Filter on [`CasingSpan::changed`]
154 /// for just the edits.
155 pub spans: Vec<CasingSpan>,
156}