1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
//! One table per named choice, read in both directions.
//!
//! A closed set of variants that a caller *names* — on a command line, in a configuration
//! file — has three things to say about itself: the word each variant is written as, the
//! whole list of them for a message that offers the choice, and which variant a word means.
//! Written by hand those are three places one vocabulary lives, and the failure they invite
//! is silent: a variant added to two of them leaves a tool that prints a word it refuses, or
//! offers a list it does not accept.
//!
//! [`named_choice!`] generates all three from one table. The `as_str` arm it writes is an
//! exhaustive `match`, so a variant added to the enum and not to the table does not compile.
//!
//! This is for the choices a caller names. A variant that is only ever *rendered* — the
//! subsystem a finding was filed under, the direction a fidelity record runs — has one
//! projection and one site to edit, and spells it as an ordinary `match`.
/// A closed set of variants a caller names, in whichever direction it is being read.
///
/// Every type carrying this offers exactly the words it accepts: [`NAMES`](Self::NAMES) is
/// the list, [`as_str`](Self::as_str) writes one, and [`from_name`](Self::from_name) reads
/// one back. So a name a report prints can be typed straight into whatever takes one, and a
/// consumer building an argument parser writes one function for every choice this crate has
/// rather than one per choice.
///
/// Each implementor also carries the same three as inherent items, so reaching them does not
/// require this trait in scope. It is here for the caller that wants them generically.
/// Generate `as_str`, `NAMES`, and `from_name` for a closed set of named variants, as
/// inherent items and as a [`NamedChoice`] implementation.
///
/// The table is the whole vocabulary. `NAMES` lists the variants in the order written here,
/// which is the order a message offering the choice lists them, and `from_name` accepts
/// exactly the words `as_str` writes.
pub use named_choice;
/// Serialize a type as the word its `as_str` writes.
///
/// A variant's name in Rust is not a word this crate says anywhere else: `ExFat` is written
/// `exfat`, `ChangeTime` is written `change time`, `GroupDescriptor` is written
/// `group descriptor`. A derived `Serialize` emits the Rust name, which puts a second
/// spelling of the same vocabulary on a public surface for no one's benefit -- a consumer
/// embedding one of these values in its own document then reads a word this crate prints
/// nowhere. This writes the one word instead, from the one table that holds it.
///
/// Expands to nothing without the `serde` feature, so a caller writes it beside the type
/// unconditionally.
pub use serialize_as_name;