Skip to main content

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}