Design

Condensed from docs/design.md. Code references: inflector-core/src/main/java/io/github/slayyyyer/morphex/inflector/.

Resolution pipeline (fixed precedence)

  1. Caller override — exact, case-sensitive whole-input match.
  2. Exact lexical entry — lower-cased lookup; C-flagged entries also require the exact caller spelling.
  3. Caller-declared initialism — explicit metadata, never an uppercase guess.
  4. Supported compound — exact entries, free tails (-in-law, -of-war…), curated postposed heads, guarded head-final and particle paths; nested depth is capped at 4. Heads retain provenance, so only unresolved rule results may be respelled.
  5. Productive rule — one of three, only for plain Latin tokens.
  6. Fallback — return input unchanged (fallback:unsupported), identified by analyze.

Three productive rules plus bounded backoffs

IDConditionEdit
rule:sibilant-esends s x z ch shappend es
rule:consonant-y-iesconsonant + y (incl. qu+y)y → ies
rule:default-sotherwiseappend s

Nothing word-specific is expressible as a rule — so carp can't cover scarp and louse can't reach blouse, unlike the stock 2.0 behaviour documented in the comparisons page.

Casing

Lookup normalization and output restoration are separate operations (stock 2.0 combines them, hence CHILD → CHILDren). PRESERVE (default) maps CHILD → CHILDREN, Child → Children, iPhone → iPhones; LOWERCASE/UPPERCASE force the shape. Initialisms append their attested suffix without whole-token re-casing (UFO → UFOs, SMS → SMSes).

Packed lexicon

7-column TSV artifact (diffable, regenerable offline). In memory: keys in one char[] + offsets, open-addressed int[] index, primitive metadata columns; full plural strings kept only for the ~14k entries diagnostics can expose (alternatives/classical). Rest is a derived (cut, append) edit — e.g. mouse/mice → cut 4 + ice. 55.5 MB → ~24 MB retained.

Countability & modes

MASS/PLURAL_ONLY/invariant return the lemma unchanged; MIXED pluralizes (waters). Alternatives preserved (person → people + persons; die → dice + dies, ambiguous). CLASSICAL only selects attested classical forms — never invented. No numeric confidence, by decision D8: an unvalidated score is not a probability.

Deliberately out of scope

Singularization, verbs, parsing, multilingual morphology, online learning, general multi-word rewriting. The rules-only runtime mode does not load the packaged data; the data remains in the JAR and its CC BY-SA terms still apply.