#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
extern crate self as cognomen;
#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;
mod extra;
mod formatted;
mod label;
#[doc(inline)]
pub use cognomen_macros::Cognomen;
pub use extra::{Blurb, BlurbKey, Extra, Help, HelpKey, Hint, HintKey, Reason, ReasonKey};
pub use formatted::Formatted;
#[doc(hidden)]
pub use label::__FromDeclared;
pub use label::{Case, FromLabel, Label};
#[cfg(feature = "clap")]
#[cfg_attr(docsrs, doc(cfg(feature = "clap")))]
pub mod clap;
pub trait Variants: Sized + 'static {
const VARIANTS: &'static [Self];
const LABELS: &'static [&'static str];
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct FromLabelError {
#[cfg(feature = "alloc")]
#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
pub input: alloc::string::String,
}
impl FromLabelError {
#[must_use]
pub fn new(input: &str) -> Self {
#[cfg(not(feature = "alloc"))]
let _ = input;
Self {
#[cfg(feature = "alloc")]
input: alloc::string::String::from(input),
}
}
}
impl core::fmt::Display for FromLabelError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
#[cfg(feature = "alloc")]
{
write!(f, "no cognomen label matches `{}`", self.input)
}
#[cfg(not(feature = "alloc"))]
{
f.write_str("no cognomen label matches")
}
}
}
#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
impl std::error::Error for FromLabelError {}
#[cfg(feature = "serde")]
#[doc(hidden)]
pub use serde as __serde;
#[cfg(test)]
mod tests {
extern crate std;
use std::string::ToString;
use super::*;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case, kebab-case)]
enum Mode {
SingleProcess,
MultiProcess,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(lower)]
enum Kind {
#[cognomen(blurb = "microphone / input device")]
Mic,
#[cognomen(blurb = "system-wide loopback", hint = "loopback")]
System,
App,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(lower, blurb = "", hint = "")]
enum KindEmpty {
#[cognomen(blurb = "microphone / input device")]
Mic,
App,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(lower)]
enum Shared {
Mic,
App,
}
impl core::fmt::Display for Shared {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str("user")
}
}
impl Shared {
pub const VARIANTS: &'static [&'static str] = &["mic", "app"];
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(lower)]
enum Status {
Error,
Err,
Ok,
}
#[test]
fn error_and_err_variants() {
assert_eq!(Status::Error.as_str(), "error");
assert_eq!(Status::try_from("err"), Ok(Status::Err));
assert_eq!("ok".parse::<Status>().unwrap(), Status::Ok);
}
#[test]
fn tables_do_not_clash_with_user_items() {
assert_eq!(Shared::VARIANTS, &["mic", "app"]);
assert_eq!(<Shared as Variants>::VARIANTS, &[Shared::Mic, Shared::App]);
assert_eq!(<Shared as Variants>::LABELS, &["mic", "app"]);
assert_eq!(Shared::Mic.to_string(), "user");
assert_eq!(Shared::Mic.as_str(), "mic");
}
#[derive(Debug, Clone, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum HostError {
#[cognomen(reason = "host backend unsupported {capability}")]
Unsupported { capability: &'static str },
#[cognomen(reason = "host open failed {cause}")]
OpenFailed { cause: &'static str },
#[cognomen(reason = "host refused request {why}")]
BadRequest { why: &'static str },
#[cognomen(reason = "host io failed {status}")]
Io { status: &'static str },
}
#[derive(Debug, Clone, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum Mixed {
#[cognomen(reason = "stdout write failed")]
Write,
#[cognomen(reason = "host open failed {cause}")]
OpenFailed { cause: &'static str },
#[cognomen(reason = "use {{braces}} {name}")]
Escaped { name: &'static str },
#[cognomen(reason = "open failed {0}")]
Tuple(u8),
}
#[test]
fn extra_methods() {
assert_eq!(Kind::Mic.as_str(), "mic");
assert_eq!(Kind::Mic.blurb(), "microphone / input device");
assert_eq!(Kind::System.blurb(), "system-wide loopback");
assert_eq!(Kind::App.blurb(), "app");
assert_eq!(Kind::Mic.hint(), "mic");
assert_eq!(Kind::System.hint(), "loopback");
assert_eq!(Kind::App.hint(), "app");
assert_eq!(KindEmpty::Mic.blurb(), "microphone / input device");
assert_eq!(KindEmpty::App.blurb(), "");
assert_eq!(KindEmpty::Mic.hint(), "");
assert_eq!(KindEmpty::App.hint(), "");
}
#[test]
fn interpolates_named_payload() {
let e = HostError::OpenFailed { cause: "busy" };
assert_eq!(e.as_str(), "open_failed");
assert_eq!(e.in_case(Case::Snake), "open_failed");
assert_eq!(e.reason(), "host open failed busy");
assert_eq!(
HostError::Unsupported { capability: "x" }.reason(),
"host backend unsupported x"
);
assert_eq!(
HostError::BadRequest {
why: "device name has interior NUL"
}
.reason(),
"host refused request device name has interior NUL"
);
assert_eq!(
HostError::Io {
status: "short write"
}
.reason(),
"host io failed short write"
);
assert!(e == "open_failed");
assert_eq!(core::convert::AsRef::<str>::as_ref(&e), "open_failed");
}
#[test]
fn interpolates_mixed_and_tuple() {
assert_eq!(Mixed::Write.reason(), "stdout write failed");
assert_eq!(
Mixed::OpenFailed { cause: "busy" }.reason(),
"host open failed busy"
);
assert_eq!(Mixed::Escaped { name: "mic" }.reason(), "use {braces} mic");
assert_eq!(Mixed::Tuple(7).reason(), "open failed 7");
assert_eq!(Mixed::Tuple(7).as_str(), "tuple");
}
#[derive(Cognomen)]
#[cognomen(snake_case)]
enum KindUnimplemented {
#[cognomen(reason = "not implemented")]
Unimplemented,
}
impl KindUnimplemented {
fn reason(&self) -> u8 {
0
}
fn as_str(&self) -> u8 {
1
}
}
#[test]
fn extras_share_one_trait_and_do_not_clash() {
fn sentence(e: &impl Reason) -> Formatted<'_> {
e.reason()
}
assert!(sentence(&HostError::OpenFailed { cause: "busy" }) == "host open failed busy");
assert!(sentence(&KindUnimplemented::Unimplemented) == "not implemented");
assert_eq!(KindUnimplemented::Unimplemented.reason(), 0);
assert_eq!(KindUnimplemented::Unimplemented.as_str(), 1);
assert_eq!(
<KindUnimplemented as Reason>::reason(&KindUnimplemented::Unimplemented),
"not implemented"
);
assert_eq!(
<KindUnimplemented as Label>::as_str(&KindUnimplemented::Unimplemented),
"unimplemented"
);
}
#[cfg(feature = "alloc")]
#[derive(Debug, Clone, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum OwnedHostError {
#[cognomen(reason = "host open failed {cause}")]
OpenFailed { cause: alloc::string::String },
}
#[cfg(feature = "alloc")]
#[test]
fn interpolates_owned_string() {
let e = OwnedHostError::OpenFailed {
cause: alloc::string::String::from("busy"),
};
assert_eq!(e.reason(), "host open failed busy");
assert_eq!(e.reason().to_string(), "host open failed busy");
}
#[test]
fn aliases_and_tables() {
assert_eq!(Mode::SingleProcess.label(), "single_process");
assert_eq!(Mode::MultiProcess.as_str(), "multi_process");
assert_eq!(Mode::SingleProcess.in_case(Case::Kebab), "single-process");
assert_eq!(
core::convert::AsRef::<str>::as_ref(&Mode::SingleProcess),
"single_process"
);
assert_eq!(Mode::VARIANTS, &[Mode::SingleProcess, Mode::MultiProcess]);
assert_eq!(Mode::LABELS, &["single_process", "multi_process"]);
assert!(Mode::SingleProcess == "single_process");
assert!(Mode::SingleProcess == "single-process");
assert!("multi-process" == Mode::MultiProcess);
}
#[test]
fn parse() {
assert_eq!(
Mode::from_label("single-process").unwrap(),
Mode::SingleProcess
);
assert!(Mode::try_from("nope").is_err());
assert_eq!("multi_process".parse::<Mode>().unwrap(), Mode::MultiProcess);
#[cfg(feature = "alloc")]
assert_eq!(Mode::try_from("nope").unwrap_err().input, "nope");
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum ProcessRole {
#[cognomen(alias = "main")]
Supervisor,
Worker,
}
#[test]
fn parse_alias_is_parse_only() {
assert_eq!(ProcessRole::Supervisor.label(), "supervisor");
assert_eq!(ProcessRole::Supervisor.as_str(), "supervisor");
assert_eq!(ProcessRole::Supervisor.in_case(Case::Snake), "supervisor");
assert_eq!(ProcessRole::Supervisor.in_case(Case::Kebab), "supervisor");
assert_eq!(ProcessRole::LABELS, &["supervisor", "worker"]);
assert_eq!(
ProcessRole::from_label("main").unwrap(),
ProcessRole::Supervisor
);
assert_eq!(
ProcessRole::from_label("supervisor").unwrap(),
ProcessRole::Supervisor
);
assert_eq!(
"main".parse::<ProcessRole>().unwrap(),
ProcessRole::Supervisor
);
assert!(ProcessRole::from_label("").is_err());
assert!(ProcessRole::Supervisor == "supervisor");
assert!(ProcessRole::Supervisor != "main");
assert!("main" != ProcessRole::Supervisor);
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum ChannelKind {
Trades,
L2Book,
#[cognomen(unknown)]
Other,
}
#[test]
fn unknown_variant_is_parse_fallback() {
assert_eq!(
ChannelKind::from_label("trades").unwrap(),
ChannelKind::Trades
);
assert_eq!(
ChannelKind::from_label("l2_book").unwrap(),
ChannelKind::L2Book
);
assert_eq!(ChannelKind::from_label("nope").unwrap(), ChannelKind::Other);
assert_eq!(ChannelKind::from_label("").unwrap(), ChannelKind::Other);
assert_eq!(
"mystery".parse::<ChannelKind>().unwrap(),
ChannelKind::Other
);
assert_eq!(ChannelKind::Other.label(), "other");
assert_eq!(ChannelKind::Other.as_str(), "other");
assert!(ChannelKind::Other == "other");
assert!(ChannelKind::Other != "nope");
assert_eq!(ChannelKind::try_from("nope"), Ok(ChannelKind::Other));
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case, kebab-case)]
enum MultiAlias {
#[cognomen(alias = "io", alias = "i/o")]
IoFailed,
OpenFailed,
}
#[test]
fn multiple_aliases_and_declared_cases() {
assert_eq!(MultiAlias::IoFailed.label(), "io_failed");
assert_eq!(MultiAlias::from_label("io").unwrap(), MultiAlias::IoFailed);
assert_eq!(MultiAlias::from_label("i/o").unwrap(), MultiAlias::IoFailed);
assert_eq!(
MultiAlias::from_label("io-failed").unwrap(),
MultiAlias::IoFailed
);
assert!(MultiAlias::IoFailed != "io");
assert!(MultiAlias::IoFailed == "io-failed");
assert!(MultiAlias::from_label("nope").is_err());
}
const fn mode_label_in_const() -> &'static str {
Mode::LABELS[0]
}
#[test]
fn works_in_const() {
assert_eq!(mode_label_in_const(), "single_process");
const TABLES: &[&str] = Mode::LABELS;
assert_eq!(TABLES, &["single_process", "multi_process"]);
}
#[test]
fn from_label_error_new() {
let err = FromLabelError::new("nope");
#[cfg(feature = "alloc")]
{
assert_eq!(err.input, "nope");
assert_eq!(err.to_string(), "no cognomen label matches `nope`");
}
#[cfg(not(feature = "alloc"))]
{
assert_eq!(err.to_string(), "no cognomen label matches");
}
#[cfg(feature = "std")]
{
let _: &dyn std::error::Error = &err;
}
}
#[test]
fn partial_eq_mismatch() {
assert!(Mode::SingleProcess != "nope");
assert!("nope" != Mode::SingleProcess);
assert!(Mode::MultiProcess != "single_process");
assert!(Mode::SingleProcess == "single-process");
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum Acronym {
HTTPResponse,
Utf8,
IPv4,
}
#[test]
fn word_splitting() {
assert_eq!(Acronym::HTTPResponse.as_str(), "http_response");
assert_eq!(Acronym::Utf8.as_str(), "utf8");
assert_eq!(Acronym::IPv4.as_str(), "i_pv4");
assert_eq!(
Acronym::from_label("http_response").unwrap(),
Acronym::HTTPResponse
);
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(lower, blurb())]
enum ParenExtra {
#[cognomen(blurb = "mic")]
Mic,
App,
}
#[test]
fn extra_paren_default_is_empty() {
assert_eq!(ParenExtra::Mic.blurb(), "mic");
assert_eq!(ParenExtra::App.blurb(), "");
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case)]
enum Generic<const N: usize> {
LeftHand,
RightHand,
}
#[test]
fn generic_has_labels_not_tables() {
assert_eq!(Generic::<1>::LeftHand.as_str(), "left_hand");
assert_eq!(
Generic::<2>::from_label("right_hand").unwrap(),
Generic::<2>::RightHand
);
}
impl Shared {
pub const LABELS: &'static [&'static str] = &["user-mic", "user-app"];
}
#[test]
fn user_labels_do_not_hide_trait_labels() {
assert_eq!(Shared::LABELS, &["user-mic", "user-app"]);
assert_eq!(<Shared as Variants>::LABELS, &["mic", "app"]);
}
#[test]
fn error_and_err_parse() {
assert_eq!(Status::from_label("error").unwrap(), Status::Error);
assert_eq!(Status::from_label("err").unwrap(), Status::Err);
assert!(Status::from_label("ok").is_ok());
assert!(Status::try_from("Error").is_err());
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(
snake, kebab, camel_case, pascal, screaming, lowercase, uppercase, title_case
)]
enum Alias {
SingleProcess,
}
#[test]
fn case_aliases() {
assert_eq!(Alias::SingleProcess.label(), "single_process");
assert_eq!(Alias::SingleProcess.in_case(Case::Snake), "single_process");
assert_eq!(Alias::SingleProcess.in_case(Case::Kebab), "single-process");
assert_eq!(Alias::SingleProcess.in_case(Case::Camel), "singleProcess");
assert_eq!(Alias::SingleProcess.in_case(Case::Pascal), "SingleProcess");
assert_eq!(
Alias::SingleProcess.in_case(Case::ScreamingSnake),
"SINGLE_PROCESS"
);
assert_eq!(Alias::SingleProcess.in_case(Case::Lower), "singleprocess");
assert_eq!(Alias::SingleProcess.in_case(Case::Upper), "SINGLEPROCESS");
assert_eq!(Alias::SingleProcess.in_case(Case::Title), "Single Process");
assert_eq!(
Alias::from_label("single-process").unwrap(),
Alias::SingleProcess
);
assert_eq!(
Alias::from_label("SINGLE_PROCESS").unwrap(),
Alias::SingleProcess
);
assert_eq!(
Alias::from_label("Single Process").unwrap(),
Alias::SingleProcess
);
assert!("singleProcess" == Alias::SingleProcess);
assert!(Alias::SingleProcess == *"single_process");
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
#[cognomen(snake_case, kebab-case, prefix = "cfg")]
enum Prefixed {
EnableLogging,
}
#[test]
fn prefix_and_as_ref() {
assert_eq!(Prefixed::EnableLogging.label(), "enable_logging");
assert_eq!(
Prefixed::EnableLogging.in_case(Case::Snake),
"enable_logging"
);
assert_eq!(
Prefixed::EnableLogging.in_case(Case::Kebab),
"enable-logging"
);
assert_eq!(
core::convert::AsRef::<str>::as_ref(&Prefixed::EnableLogging),
"enable_logging"
);
assert_eq!(
"enable-logging".parse::<Prefixed>().unwrap(),
Prefixed::EnableLogging
);
}
#[cfg(feature = "serde")]
#[test]
fn serde_roundtrip() {
let v = Mode::SingleProcess;
let s = serde_json::to_string(&v).unwrap();
assert_eq!(s, "\"single_process\"");
let back: Mode = serde_json::from_str(&s).unwrap();
assert_eq!(back, v);
let kebab: Mode = serde_json::from_str("\"single-process\"").unwrap();
assert_eq!(kebab, v);
let alias_in: ProcessRole = serde_json::from_str("\"main\"").unwrap();
assert_eq!(alias_in, ProcessRole::Supervisor);
assert_eq!(
serde_json::to_string(&ProcessRole::Supervisor).unwrap(),
"\"supervisor\""
);
let unknown_in: ChannelKind = serde_json::from_str("\"nope\"").unwrap();
assert_eq!(unknown_in, ChannelKind::Other);
assert_eq!(
serde_json::to_string(&ChannelKind::Other).unwrap(),
"\"other\""
);
let generic = Generic::<3>::LeftHand;
let gs = serde_json::to_string(&generic).unwrap();
assert_eq!(gs, "\"left_hand\"");
let gback: Generic<3> = serde_json::from_str(&gs).unwrap();
assert_eq!(gback, generic);
}
}