cognomen_macros/lib.rs
1//! Proc-macro implementation for [`cognomen`](https://docs.rs/cognomen).
2//!
3//! Depend on the `cognomen` crate, not this one. This crate is the host
4//! proc-macro; generated items use `core` so the runtime can be `no_std`.
5
6mod cognomen;
7
8use proc_macro::TokenStream;
9
10/// Derive stable, case-configured string labels for an enum.
11///
12/// # Container attribute
13///
14/// ```ignore
15/// #[derive(Cognomen)]
16/// #[cognomen(snake_case, kebab-case, crate = ::cognomen)]
17/// enum Mode { SingleProcess }
18/// ```
19///
20/// - One or more case styles (required). The **first** is the default used by
21/// [`cognomen::Label`], and serde serialization.
22/// - `prefix = "..."`: accepted for compatibility; case accessors live on
23/// [`cognomen::Label`].
24/// - `crate = ::path`: crate path emitted in generated code. Default:
25/// `::cognomen`. Set this when you re-export cognomen from another crate.
26///
27/// # Variant attribute
28///
29/// ```ignore
30/// #[cognomen(rename = "io_error")]
31/// IoFailed,
32/// ```
33///
34/// Overrides the default label with that exact string and accepts it when
35/// parsing. [`cognomen::Label::in_case`] still converts from the ident.
36///
37/// `#[cognomen(alias = "main")]` adds a parse-in string only. It does not
38/// change `label()`, `as_str()`, serde-out, `PartialEq<str>`, or `in_case`.
39/// Repeat the key for more than one alias. Empty `""` is a compile error.
40///
41/// `#[cognomen(unknown)]` on exactly one unit variant of a fieldless enum
42/// sends unmatched parse and serde-in to that variant. The unmatched string
43/// is not stored. clap `value_parser` still rejects unmatched input.
44///
45/// # Extras
46///
47/// Any other `name = "..."` is an extra. Known keys implement a trait in
48/// `cognomen` (`Reason`, `Blurb`, `Hint`, `Help`). Every extra returns
49/// [`cognomen::Formatted`].
50///
51/// ```ignore
52/// #[derive(Cognomen)]
53/// #[cognomen(lower)]
54/// enum SourceKind {
55/// #[cognomen(blurb = "microphone / input device")]
56/// Mic,
57/// App, // App.blurb() == "app" (`as_str`)
58/// }
59/// ```
60///
61/// On the enum, `name = "..."` is the default for omitted variants.
62/// `name()` means `name = ""`. If the enum does not set a default, omitted
63/// variants use `as_str()` / `label()`. Extras are not used for parse or
64/// serde.
65///
66/// # Generated items
67///
68/// All of these are trait impls. Nothing is inherent on `E`.
69///
70/// - `cognomen::Label`: `label` / `as_str` / `in_case`
71/// - `cognomen::Reason` / `Blurb` / `Hint` / `Help` / `Extra`: extras
72/// - `cognomen::Variants` (non-generic, fieldless): `VARIANTS` / `LABELS`
73/// - `AsRef<str>`, `PartialEq<str>` (compares the label, not an alias)
74/// - `TryFrom<&str>`, `FromStr`, `cognomen::FromLabel` (fieldless enums;
75/// `alias` and optional `unknown` fallback)
76/// - `Serialize` / `Deserialize` (feature `serde`; fieldless enums)
77///
78/// See the [`cognomen`](https://docs.rs/cognomen) crate docs for case styles,
79/// extras, features, and `no_std`.
80#[proc_macro_derive(Cognomen, attributes(cognomen))]
81pub fn derive_cognomen(input: TokenStream) -> TokenStream {
82 cognomen::derive(input.into())
83 .unwrap_or_else(|e| e.to_compile_error())
84 .into()
85}