Skip to main content

ingraph_codegen/
plural.rs

1//! The ENGLISH PLURAL at expansion time — the word a list face is named from when a declaration
2//! wrote none.
3//!
4//! One entity is `Reel` and its page is `reels`, and nothing in `heck` knows that: casing is a
5//! mechanical transform over the characters a name already has, and a plural is a fact about the
6//! LANGUAGE. So the word comes from here, and the casing helpers keep their own job — this module
7//! never changes a letter's case, and no caller of it may pluralise by hand.
8//!
9//! # The dependency lives on the EXPANSION side, and that is the whole of its reach
10//!
11//! `ingraph-codegen` is reached only through `ingraph-derive`, which is a proc-macro crate — so this
12//! crate and everything it names are built for the HOST and linked into the compiler's macro tier,
13//! never into a consumer's binary. A declaring crate pays for the pluraliser once at build time and
14//! ships not one byte of it. The dep tree is what says so rather than this sentence:
15//! `cargo tree -p ingraph -e normal` reaches `pluralizer` only under the `(proc-macro)` node, and a
16//! build with `default-features = false` — the derive off — has no path to it at all.
17//!
18//! # WHICH crate, and the measurement that chose it
19//!
20//! Three carry an English plural: `pluralizer` 0.5.0, `cruet` 1.0.0 (the maintained Inflector fork)
21//! and `inflection-rs` 0.2.2. `inflections` is in the family by name only — it is a CASING library
22//! with no plural in it at all, which is also why taking it would have meant a second casing
23//! authority beside `heck`.
24//!
25//! All three were run over this repository's own entity names and over a wider English corpus. The
26//! two failure modes are not equally bad, and that is what decided it:
27//!
28//! | | `pluralizer` 0.5 | `cruet` 1.0 | `inflection-rs` 0.2 |
29//! |---|---|---|---|
30//! | `Splice` (a corpus record) | `Splices` | **`Splice`** | **`Splice`** |
31//! | `Slice` | `Slices` | **`Slice`** | `Slices` |
32//! | `Child` / `Life` / `Knife` | `Children` / `Lives` / `Knives` | **`Childs` / `Lifes` / `Knifes`** | `Children` / `Lives` / `Knives` |
33//! | `Person` / `Datum` / `Analysis` | `People` / `Data` / `Analyses` | **`Persons` / `Datums`** / `Analyses` | `People` / `Data` / `Analyses` |
34//! | `Media` / `Audio` (mass nouns) | `Media` / `Audio` | **`Medias` / `Audios`** | `Media` / `Audios` |
35//! | last release | 2025-01-17 | 2026-04-03 | 2025-05-16 |
36//! | dependencies | `once_cell`, `regex` | `regex` | `deunicode`, `lazy_static`, `regex` |
37//! | licence | MIT OR Apache-2.0 | BSD-2-Clause | MIT |
38//!
39//! `cruet` is the more recently released of the two, and it is the one this framework cannot use: a
40//! wrong plural that DIFFERS from the singular is silent — `childs` reaches a schema, no rule can
41//! see that it is wrong, and a client reads it forever. A word the pluraliser cannot inflect comes
42//! back UNCHANGED, which is loud: it is exactly the degenerate case the list face refuses by name,
43//! and the declaration answers it with `graphql(plural = "…")`. So the crate whose failures are the
44//! loud kind is the one that fits a design built on refusing silence — and `pluralizer` also has the
45//! better irregulars by a wide margin, which is the same argument one level down.
46//!
47//! Version `0.5` and no patch floor, per the deps law: `0.minor` IS a `0.x` crate's compatibility
48//! axis.
49//!
50//! # What this answers, and what it deliberately does not
51//!
52//! * **Multi-word names pluralise their LAST word**, and by construction rather than by a split
53//!   written here: the rules are anchored at the END of the word, so `MediaAsset` → `MediaAssets`
54//!   and `VideoChild` → `VideoChildren` fall out of asking the whole name. Nothing tokenises a
55//!   camel-cased name, so no second casing authority appears.
56//! * **Case is not this layer's business.** A few irregulars come back with a lower-case initial
57//!   (`Foot` → `feet`, `Man` → `men`) because the crate's table stores the replacement in lower
58//!   case. That never reaches a schema: a root field is spelled with a lower initial anyway, so
59//!   `feet` is the field name either way. Measured, and pinned in this module's tests.
60//! * **A degenerate answer is not refused here.** `Media` → `Media`, `Series` → `Series`,
61//!   `Dimensions` → `Dimensions`: the word has no distinct plural, or already is one. This function
62//!   reports what English gave it; whether that is usable is the CALLER's question, asked where the
63//!   word is spent — see [`RecordModel::degenerate_plural`](crate::model::RecordModel::degenerate_plural).
64
65/// The count that asks for the plural. `pluralizer`'s entry point inflects for a COUNT, one being
66/// the singular and anything else the plural, so the plural is asked for by naming a number that is
67/// not one rather than by a second function.
68const PLURAL: isize = 2;
69
70/// The English plural of one word, as the list face's default name is built from.
71///
72/// The word is answered VERBATIM where the language has no distinct plural for it — see the module
73/// note, which carries what that means for the caller and where the refusal lives.
74///
75/// ```
76/// assert_eq!(ingraph_codegen::plural::of("Reel"), "Reels");
77/// assert_eq!(ingraph_codegen::plural::of("VideoTrack"), "VideoTracks");
78/// assert_eq!(ingraph_codegen::plural::of("Analysis"), "Analyses");
79/// assert_eq!(ingraph_codegen::plural::of("Media"), "Media");
80/// ```
81#[must_use]
82pub fn of(word: &str) -> String {
83  // `false` is the INCLUSIVE flag: with it the crate answers "2 reels", counting the thing it
84  // inflected. A field name carries no count.
85  pluralizer::pluralize(word, PLURAL, false)
86}
87
88#[cfg(test)]
89mod tests;