# mla-titlecase
MLA-style title casing for Rust: a deterministic rule engine with optional,
opt-in lexicon support.
The built-in MLA rules are authoritative and need no downloaded data. External
lexicons (names, brands, stop words) only ever *add* to the defaults — they are
loaded explicitly by the caller and never change the baseline behavior.
```rust
use mla_titlecase::titlecase_mla;
assert_eq!(titlecase_mla("the wind in the willows"), "The Wind in the Willows");
```
## What it does
- Capitalizes the first and last words of the title and of each subtitle (after
a colon, question mark, or exclamation point), and any word that is not a
small word.
- Lowercases MLA small words (articles, coordinating conjunctions, prepositions
of any length) when they appear internally.
- Handles the awkward cases: subordinating conjunctions stay capitalized,
phrasal-verb particles are capitalized (`Turn Off the Lights`), acronyms and
dotted initialisms are preserved (`NASA`, `U.S.A.`), hyphenated compounds are
cased per segment, and contractions keep their spelling (`O'Neill`, `Don't`).
See [`docs/mla-rules.md`](../../docs/mla-rules.md) for the full rule set.
## The four entry points
| `titlecase_mla(input)` | One title, default MLA options. |
| `titlecase_with_options(input, &options)` | You need to change behavior (below). |
| `titlecase_into(&mut buf, input, &options)` | Bulk processing — reuse one `String` buffer across many titles to avoid a per-call allocation. |
| `titlecase_analyze(input)` | You want to know *why* each word was cased and how much to trust it. |
### Options
`TitleCaseOptions` controls behavior; every field has a sensible MLA default, so
override only what you need. It is `#[non_exhaustive]`, so start from
`Default`/a `with_*` constructor and mutate the public fields you care about
rather than building it with a struct literal:
```rust
use mla_titlecase::{titlecase_with_options, HyphenStyle, TitleCaseOptions};
let mut options = TitleCaseOptions::with_protected_words(&["PostgreSQL"]);
options.hyphen_style = HyphenStyle::CapitalizeBoth;
assert_eq!(
titlecase_with_options("learning postgresql with github", &options),
"Learning PostgreSQL with GitHub",
);
```
| `preserve_existing_caps` | `true` | Keep mixed-case input like `iPhone`. |
| `capitalize_after_subtitle_boundary` | `true` | Treat colons, question marks, and exclamation points as subtitle boundaries. |
| `capitalize_phrasal_particles` | `true` | Capitalize adverbial particles (`Give Up`). |
| `all_caps_policy` | `Normalize` | How to handle all-caps ("shouting") input. |
| `small_word_policy` | `Mla` | Which words to lowercase internally. |
| `hyphen_style` | `MlaLike` | Casing of hyphenated compounds. |
| `name_particle_policy` | `Disabled` | Lowercase `van`/`de`/`von` in personal names. |
| `locale` | `English` | Locale-aware casing (see below). |
| `protected_words` | `&[]` | Spellings that are never recased. |
| `external_lexicons` | `None` | Additive lexicon data (see below). |
`AllCapsPolicy` is worth calling out for catalog data: `Normalize` recases
`THE WIND` to `The Wind`; `Preserve` leaves intentional stylization like
`MONTERO` untouched; `NormalizeKnownWords` recases dictionary words but keeps
likely acronyms, given a word-set lexicon such as SCOWL.
### Locales
The default profile is English MLA. Opt-in profiles add locale-aware casing for
Dutch (`IJ` digraph), French, German, Italian, Spanish, and Turkish (dotted/
dotless `i`), and turn on sensible name-particle handling:
```rust
use mla_titlecase::{titlecase_with_options, LocaleProfile, TitleCaseOptions};
let options = TitleCaseOptions::with_locale(LocaleProfile::Dutch);
assert_eq!(
titlecase_with_options("ijsselmeer and jan van der heijden", &options),
"IJsselmeer and Jan van der Heijden",
);
```
### Rich analysis
`titlecase_analyze` returns the cased string plus, for every word, the rule that
decided its casing and how much to trust it — useful for flagging titles that
relied on a heuristic for human review:
```rust
use mla_titlecase::{titlecase_analyze, CasingRule, Confidence};
let analysis = titlecase_analyze("turn off the lights");
assert_eq!(analysis.output, "Turn Off the Lights");
// "off" is a phrasal-verb particle — a heuristic, so the title is flagged.
assert_eq!(analysis.confidence, Confidence::Heuristic);
`Confidence` has three tiers: `Solid` (structural rules and explicit matches),
`Unverified` (an ordinary word capitalized with no lexicon to confirm it isn't a
name), and `Heuristic` (a guess that could be wrong).
## External lexicons and plugins
`ExternalLexicons` holds additive data — canonical spellings, protected
spellings, multiword phrases, and word sets — that you register before casing:
```rust
use mla_titlecase::{titlecase_with_options, ExternalLexicons, TitleCaseOptions};
let mut lexicons = ExternalLexicons::default();
lexicons.add_multiword_map([("new york city", "New York City")]);
let options = TitleCaseOptions::with_external_lexicons(&lexicons);
assert_eq!(
titlecase_with_options("new york city stories", &options),
"New York City Stories",
);
```
Lexicon data can also be loaded from prebuilt plugin files (JSON or the compact
FST format). The companion [`mla-titlecase-cli`](../mla-titlecase-cli/README.md)
fetches upstream sources and builds those plugins; see
[`docs/plugin-format.md`](../../docs/plugin-format.md) for the on-disk schema.
## More
- [`docs/mla-rules.md`](../../docs/mla-rules.md) — the exact casing rules.
- [`docs/architecture.md`](../../docs/architecture.md) — how the engine is put together.
- [`docs/performance.md`](../../docs/performance.md) — the bulk-processing path.