nameparser/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2
3//! A faithful Rust port of the GBIF scientific name parser. [`parse_name`] turns a scientific name into
4//! its structured atoms — genus, epithets, authorship, rank, nomenclatural code, notes, warnings —
5//! as a [`model::ParsedName`]. Byte-for-byte cross-validated against the Java `name-parser`
6//! (`NameParserImpl`) over 11,302 + 6.4M names (0 diffs). The same engine also ships as a native
7//! CLI and as Java/Python/R bindings — see the repository README.
8
9pub mod format;
10pub mod model;
11pub mod pipeline;
12pub mod regexes;
13pub mod token;
14pub mod unicode;
15pub mod viral;
16
17use model::{Informal, NameType, NomCode, ParseError, ParsedName, Rank};
18
19/// The lower-level raw parse: a scientific name — optionally alongside a separately supplied
20/// authorship string, a requested [`Rank`] and a requested [`NomCode`] — into a [`ParsedName`], or
21/// `Err(`[`ParseError`]`)` when the input cannot be parsed into a meaningful name. Delegates to
22/// [`pipeline::run`].
23///
24/// This is the raw `ParsedName`/error path — informal names come back as `Ok(ParsedName)` with
25/// `type == INFORMAL`, NOT split off. It backs the golden snapshot, the FFI/CLI/R encoders (which
26/// need the full `ParsedName` and derive the three-way at their own boundary), and any caller that
27/// wants the structured atoms directly. **Most callers want [`parse`] instead** — the primary 5.0.0
28/// exceptionless entry point that returns the three-way [`ParseResult`].
29pub fn parse_name(
30 name: &str,
31 authorship: Option<&str>,
32 rank: Option<Rank>,
33 code: Option<NomCode>,
34) -> Result<ParsedName, ParseError> {
35 pipeline::run(name, authorship, rank, code)
36}
37
38/// The 5.0.0 exceptionless result of [`parse`], mirroring Java
39/// `org.gbif.nameparser.api.ParseResult`: a structurally [`Parsed`](ParseResult::Parsed) name, an
40/// [`Informal`](ParseResult::Informal) semistructured name (a taxon anchor carrying a provisional
41/// designation, e.g. `Rhizobium sp. RMCC TR1811`), or an [`Unparsable`](ParseResult::Unparsable)
42/// classification (virus, hybrid formula, placeholder, BOLD BIN, ...). The 5.5%-of-corpus informal
43/// band is split off from `Parsed` at the [`parse`] boundary — see the verbatim-corpus study.
44///
45/// `Parsed` is far larger than the other two variants (it wraps the ~1 KB [`ParsedName`] vs ~56 B
46/// for [`Informal`]/[`ParseError`]), so `clippy::large_enum_variant` fires — but `Parsed` is the
47/// dominant outcome (≈89% of the corpus) and the value is decomposed immediately at the call
48/// boundary, so boxing it would add a heap allocation to the common path for no real gain. This
49/// mirrors [`parse_name`]'s own `Result<ParsedName, ParseError>`, which carries the identical size
50/// profile unboxed.
51#[allow(clippy::large_enum_variant)]
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub enum ParseResult {
54 /// A structurally parsed name carrying the full [`ParsedName`] atoms.
55 Parsed(ParsedName),
56 /// An informal / semistructured name: a supraspecific anchor + a provisional, non-code
57 /// designation, with no species epithet. See [`Informal`].
58 Informal(Informal),
59 /// A string that is not a parsable scientific name (virus, hybrid formula, placeholder, ...).
60 Unparsable(ParseError),
61}
62
63impl ParseResult {
64 /// The name type, available on every variant (Java `ParseResult.type()`).
65 pub fn type_(&self) -> NameType {
66 match self {
67 ParseResult::Parsed(pn) => pn.type_,
68 ParseResult::Informal(_) => NameType::Informal,
69 ParseResult::Unparsable(e) => e.type_,
70 }
71 }
72
73 /// The nomenclatural code when known, else `None` — available on every variant (Java `code()`).
74 pub fn code(&self) -> Option<NomCode> {
75 match self {
76 ParseResult::Parsed(pn) => pn.code,
77 ParseResult::Informal(i) => i.code,
78 ParseResult::Unparsable(e) => e.code,
79 }
80 }
81
82 /// The parsed name if this is [`ParseResult::Parsed`], else `None` (Java `parsed()`).
83 /// [`ParseResult::Informal`] and [`ParseResult::Unparsable`] carry no [`ParsedName`].
84 pub fn parsed(&self) -> Option<&ParsedName> {
85 match self {
86 ParseResult::Parsed(pn) => Some(pn),
87 _ => None,
88 }
89 }
90
91 /// True iff this carries a structured [`ParsedName`] — i.e. is a [`ParseResult::Parsed`]
92 /// (Java `isParsable()`).
93 pub fn is_parsable(&self) -> bool {
94 matches!(self, ParseResult::Parsed(_))
95 }
96}
97
98/// The primary 5.0.0 exceptionless entry point (mirrors Java `NameParser.parse()`): classifies a
99/// scientific name into the three-way [`ParseResult`] (`Parsed | Informal | Unparsable`) that every
100/// binding exposes, never throwing. The informal split is applied here — a supraspecific taxon
101/// carrying a provisional designation with NO species epithet becomes [`ParseResult::Informal`]; a
102/// name with a species epithet (including cf./aff. and infraspecific-indeterminate binomials) stays
103/// [`ParseResult::Parsed`], so its `specific_authorship` — which a flat anchor could not represent —
104/// is preserved. For the raw `ParsedName`/error shape (no informal split), use [`parse_name`].
105pub fn parse(
106 name: &str,
107 authorship: Option<&str>,
108 rank: Option<Rank>,
109 code: Option<NomCode>,
110) -> ParseResult {
111 match pipeline::run(name, authorship, rank, code) {
112 Ok(pn) if is_informal(&pn) => ParseResult::Informal(to_informal(pn)),
113 Ok(pn) => ParseResult::Parsed(pn),
114 // `Unparsable` may only carry a non-parsable type (mirrors Java); the core's error path
115 // can still tag an informal-but-unrepresentable grouping as INFORMAL — clamp it to OTHER.
116 Err(e) => ParseResult::Unparsable(e.clamped_to_unparsable()),
117 }
118}
119
120/// The informal discriminator (settled via the 67.5M verbatim-corpus study): an `INFORMAL`-typed
121/// name with a real supraspecific anchor but NO species epithet is an [`ParseResult::Informal`];
122/// everything else parsable stays `Parsed`. Keying on `specific_epithet` routes cf./aff. and
123/// infraspecific-indeterminate binomials to `Parsed` automatically (they keep a species epithet),
124/// so their `epithet_qualifier` annotation and `specific_authorship` survive. The anchor guard keeps
125/// a degenerate anchor-less `INFORMAL` (should not occur on the `Ok` path) out of `Informal`.
126fn is_informal(pn: &ParsedName) -> bool {
127 pn.type_ == NameType::Informal
128 && pn.specific_epithet.is_none()
129 && (pn.genus.is_some() || pn.uninomial.is_some() || pn.infrageneric_epithet.is_some())
130}
131
132/// Derive the flat [`Informal`] anchor from an informal [`ParsedName`]. The anchor sits in the
133/// `genus` slot for the overwhelming `Genus sp. <tag>` majority (→ `taxon_rank = GENUS`, even when
134/// the word is really a family the unvalidated parser cannot know that); a bare supraspecific
135/// monomial falls back to `uninomial` (then `infrageneric`) at the name's own rank. Precondition:
136/// [`is_informal`] held, so at least one anchor slot is populated.
137fn to_informal(pn: ParsedName) -> Informal {
138 let (taxon, taxon_rank) = if let Some(g) = pn.genus.as_deref() {
139 (g.to_string(), Rank::Genus)
140 } else if let Some(u) = pn.uninomial.as_deref() {
141 (u.to_string(), pn.rank)
142 } else {
143 (pn.infrageneric_epithet.clone().unwrap_or_default(), pn.rank)
144 };
145 Informal {
146 taxon,
147 taxon_rank,
148 rank: pn.rank,
149 phrase: pn.phrase,
150 code: pn.code,
151 }
152}
153
154#[cfg(test)]
155mod tests {
156 use super::*;
157 use model::NameType;
158
159 #[test]
160 fn parse_delegates_to_pipeline_run() {
161 let pn = parse_name("Abies alba", None, None, None).expect("should parse");
162 assert_eq!(pn.type_, NameType::Scientific);
163 }
164
165 #[test]
166 fn parse_rejects_empty_input() {
167 let err = parse_name("", None, None, None).unwrap_err();
168 assert_eq!(err.type_, NameType::Other);
169 }
170
171 /// The three-way [`parse`] classifier + the flat [`Informal`] derivation, on cases whose
172 /// outcome is independent of the (separate) trailing-tag-capture parser change: an already-captured
173 /// phrase (`Serratia sp. RE1-2a`), a bare `Genus sp.`, and a numbered placeholder route to
174 /// `Informal`; a binomial core (species epithet present) and a bare determined genus stay `Parsed`;
175 /// empty input is `Unparsable`.
176 #[test]
177 fn parse_classifies_three_way() {
178 use model::Rank;
179
180 // --- Informal: supraspecific anchor + provisional designation, no species epithet ---
181 match parse("Serratia sp. RE1-2a", None, None, None) {
182 ParseResult::Informal(i) => {
183 assert_eq!(i.taxon, "Serratia");
184 assert_eq!(i.taxon_rank, Rank::Genus);
185 assert_eq!(i.rank, Rank::Species);
186 assert_eq!(i.phrase.as_deref(), Some("sp. RE1-2a"));
187 }
188 other => panic!("expected Informal, got {other:?}"),
189 }
190 // bare "Genus sp." — no distinguishing tag, but the verbatim marker is still the phrase
191 match parse("Rhizobium sp.", None, None, None) {
192 ParseResult::Informal(i) => {
193 assert_eq!(i.taxon, "Rhizobium");
194 assert_eq!(i.taxon_rank, Rank::Genus);
195 assert_eq!(i.rank, Rank::Species);
196 assert_eq!(i.phrase.as_deref(), Some("sp."));
197 }
198 other => panic!("expected Informal, got {other:?}"),
199 }
200 // numbered placeholder
201 match parse("Allium sp. 1", None, None, None) {
202 ParseResult::Informal(i) => {
203 assert_eq!(i.taxon, "Allium");
204 assert_eq!(i.phrase.as_deref(), Some("sp. 1"));
205 }
206 other => panic!("expected Informal, got {other:?}"),
207 }
208
209 // --- Parsed: a species epithet is present (binomial core), so it is NOT Informal ---
210 // infraspecific-indeterminate — authorship would land in specific_authorship, unrepresentable flat
211 assert!(
212 matches!(
213 parse("Salix alba subsp. B", None, None, None),
214 ParseResult::Parsed(_)
215 ),
216 "infraspecific-indet binomial must stay Parsed"
217 );
218 // cf. qualifier on a complete binomial — the qualifier is an annotation, not a reclassification
219 match parse("Salicornia cf. patula", None, None, None) {
220 ParseResult::Parsed(pn) => assert_eq!(pn.specific_epithet.as_deref(), Some("patula")),
221 other => panic!("expected Parsed, got {other:?}"),
222 }
223 // a plain determined binomial and a bare determined genus
224 assert!(parse("Abies alba", None, None, None).is_parsable());
225 assert!(parse("Rhizobium", None, None, None).is_parsable());
226
227 // --- Unparsable ---
228 match parse("", None, None, None) {
229 ParseResult::Unparsable(e) => assert_eq!(e.type_, NameType::Other),
230 other => panic!("expected Unparsable, got {other:?}"),
231 }
232 }
233
234 /// The 5.0.0 boundary clamp — a defensive invariant that `Unparsable` may only carry a
235 /// non-parsable type. Since the preflight informal-group rescue landed, NO real input produces an
236 /// error:INFORMAL anymore (anchored groupings are rescued to `Informal`; the rest emit OTHER —
237 /// see `pipeline::preflight`), so this exercises the clamp DIRECTLY on a synthetic `ParseError`,
238 /// then confirms an anchorless clade label is `Unparsable(OTHER)` end to end.
239 #[test]
240 fn clamped_to_unparsable_forces_a_nonparsable_type() {
241 use model::{NomCode, ParseError};
242
243 // a parsable error type is forced to OTHER; code preserved, message rebuilt for the new type
244 let clamped = ParseError::new(NameType::Informal, Some(NomCode::Bacterial), "X group")
245 .clamped_to_unparsable();
246 assert_eq!(clamped.type_, NameType::Other);
247 assert!(!clamped.type_.is_parsable());
248 assert_eq!(clamped.code, Some(NomCode::Bacterial));
249 assert_eq!(clamped.message, "Unparsable OTHER name: X group");
250
251 // a non-parsable error is left untouched
252 let other = ParseError::new(NameType::Other, None, "junk");
253 assert_eq!(other.clone().clamped_to_unparsable(), other);
254
255 // end to end: an anchorless clade label is Unparsable(OTHER)
256 match parse("Amauropeltoid clade", None, None, None) {
257 ParseResult::Unparsable(e) => assert_eq!(e.type_, NameType::Other),
258 other => panic!("expected Unparsable(OTHER), got {other:?}"),
259 }
260 }
261}