cognomen
Cognomen is Latin for "an extra name given to a person or thing". This crate gives every enum variant a second, stable string label.
Downstream crates use it as the seam between a Rust ident and the string a
config file, log line, CLI flag, or wire protocol actually carries. Case
conversion runs at compile time and is emitted as a &'static str.
Labels and extras are trait items (Label, Reason, Blurb, ...), not
inherent methods on E. Import the trait to call e.reason(), or use UFCS
when a user fn or parent trait owns the same name.
Full API reference: https://docs.rs/cognomen
[]
= "0.5"
use ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert!;
assert_eq!;
The first case in #[cognomen(...)] is the default (label() / as_str() /
serde out). PartialEq<str> on E compares the label, not an extra.
Case styles
#[cognomen(...)] |
short aliases | VariantName becomes |
|---|---|---|
snake_case |
snake |
variant_name |
kebab-case / kebab_case |
kebab |
variant-name |
camelCase / camel_case |
camel |
variantName |
PascalCase / pascal_case |
pascal |
VariantName |
SCREAMING_SNAKE_CASE |
screaming |
VARIANT_NAME |
lower / lowercase |
variantname |
|
upper / uppercase |
VARIANTNAME |
|
title / title_case |
Variant Name |
Attributes
Container (required): #[cognomen(<case>, ...)]
- One or more cases, comma-separated. First is the default. Listed cases
are accepted by parse / serde-in;
Label::in_casecan still produce anyCase. prefix = "cfg": accepted for compatibility; case accessors live onLabel.crate = ::other::cognomen: generated path when you re-export this crate.
Variant (optional):
#[cognomen(rename = "io_error")]: sets the default label to that exact string and accepts it when parsing.Label::in_casestill converts from the ident.#[cognomen(alias = "main")]: extra parse-in string. Does not changelabel(),as_str(), serde-out,PartialEq<str>, orin_case. Repeat the key for more than one alias. Empty""is a compile error.#[cognomen(unknown)]: unmatched parse and serde-in become this unit variant. Fieldless enums only; exactly one such variant. The unmatched string is not stored. clapvalue_parserstill rejects unmatched input: unknown is a wire fallback, not a flag fallback. Do not default a catch-all; mark it explicitly.
use ;
assert_eq!;
assert_eq!;
assert_eq!;
An alias is parse-only. "" is not an alias; keep that mapping local.
use ;
assert_eq!;
assert_eq!;
assert!;
assert!;
An unknown variant receives unmatched wire tags. from_label is no longer
a bijection.
use ;
assert_eq!;
assert_eq!;
assert_eq!;
Any other name = "..." is an extra.
Violations (non-enum, missing case, collisions, empty alias, more than one
unknown, bad prefix, bad extra, unknown {field} placeholder) are compile
errors, pinned by trybuild tests under tests/ui/.
Extras
Any name = "..." in #[cognomen(...)] besides prefix, crate,
rename, and alias is an extra. Known keys (reason, blurb, hint, help)
implement a trait in this crate. Import it to call e.reason().
On a variant, that string is the variant's value. On the enum, that string
is the default for variants that omit the key. If the enum does not set a
default, omitted variants use as_str() / label() (including rename).
name() on the enum is the same as name = "".
Every extra returns Formatted. Static text is a single literal; {field}
on a variant extra appends that named (or tuple-index) payload. Adding a
placeholder does not change the signature. Write { / } as {{ / }}.
use ;
assert_eq!;
assert_eq!;
assert_eq!;
An enum-level default overrides as_str() for omitted variants:
use ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Fielded variants keep Label. Parse, Variants, and serde-in are omitted.
Interpolate extras from the fields:
use ;
let e = OpenFailed ;
assert_eq!;
assert_eq!;
A unit extra and a fielded extra with the same key share one trait and one
return type. A user inherent fn reason still compiles:
use ;
assert!;
assert_eq!;
Several extras can coexist. They are not accepted by FromLabel or serde.
Names that collide with generated items (label, as_str, ...) are compile
errors.
Generated API
For #[cognomen(snake_case, kebab-case)] on E. Nothing is inherent on E.
| item | notes |
|---|---|
Label |
label() / as_str() (default or rename); in_case(Case) |
Reason / Blurb / Hint / Help / Extra |
extras; always Formatted |
Variants |
E::VARIANTS / E::LABELS after use cognomen::Variants (non-generic, fieldless) |
AsRef<str>, PartialEq<str> |
compare against any declared label, not an alias |
TryFrom<&str>, FromStr, FromLabel |
fieldless; cases, rename, alias; unknown if marked |
Serialize / Deserialize |
feature serde, fieldless; out is label(), in accepts cases, rename, alias, and unknown |
T::value_parser() |
feature clap; declared cases, rename, alias; does not follow unknown |
numbered still has inherent number(); a follow-up should move that onto a
trait the same way.
Features
| feature | default | unlocks |
|---|---|---|
std |
yes | alloc + std::error::Error for FromLabelError |
alloc |
via std |
FromLabelError.input stores the unmatched string |
serde |
no | Serialize / Deserialize |
clap |
no | T::value_parser() for clap flags; implies std |
no_std, including embedded:
= { = "0.5", = false }
Labels, extras (Formatted), parse, AsRef, and Variants use only core.
Add features = ["alloc"] to keep the unmatched string on parse errors. Add
features = ["serde"] for wire formats. Enable clap in the binary that
owns the CLI, not in a no_std kernel:
use Parser;
use ArgType;
Word splitting
Idents split on ASCII camel-case boundaries. Acronyms stay together
(HTTPResponse -> http_response). Digits stay glued (Utf8 -> utf8,
IPv4 -> i_pv4). Re-Pascal of an acronym title-cases the run
(HTTPResponse -> HttpResponse).
MSRV
Rust 1.71.1 for default features, alloc, and serde. Floor is the
pinned proc-macro2 (rustc 1.71+). Cognomen itself only needs
Option::is_some_and (1.70).
The clap feature is not part of that floor. It needs a rustc that can
compile the resolved clap crate (clap 4.6 needs 1.85). CI checks clap on
stable with --all-features.
Publishing
cognomen depends on cognomen-macros by version. The first crates.io
upload must publish cognomen-macros first, then cognomen. New crate
names cannot use trusted publishing; that first upload is manual. Later
releases are prepared and published by release-plz on main.
License
Dual-licensed under MIT OR Apache-2.0, see
LICENSE-MIT and LICENSE-APACHE.
Copyright (c) 2026 Matheus Cardoso.