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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
//! The construction every one of this crate's borrowed names is: [`borrowed_name`].
//!
//! [`FieldName`](crate::FieldName) names a column, [`SlotName`](crate::SlotName) names an index and
//! [`ReasonName`](crate::ReasonName) names a refusal. The three are one construction three times —
//! a `#[repr(transparent)]` view of a `str`, plus the borrow trio that makes a name and the string
//! it views interchangeable as a map key — and they stay separate types, because the construction
//! is the only thing they share: a slot name's whole content is that it passed a charset, while the
//! other two are deliberately unchecked and are apart from each other for what they are ABOUT. A
//! single type any of them could be built from would have to hold one policy and answer to every
//! role, so what they share is a macro.
//!
//! # The five that name a VARIANT, and why they are the same construction
//!
//! [`SqliteName`](crate::SqliteName) and its four siblings name the word one namespace spells a
//! vocabulary's member as. A vocabulary has as many of those words as it has faces, and they are not
//! one word: a variant may be stored as `lo` in Postgres, shown as `LOW` on the wire, and be `Low`
//! in Rust. Every one of them is a `str`, so a conversion taking one is a conversion taking all of
//! them — `impl TryFrom<&str> for Grade` can exist ONCE, and it would have to pick a namespace and
//! be wrong for the rest.
//!
//! So the namespace is the TYPE, and the conversion family is one impl per namespace with no
//! coherence collision between them. That is [`FieldName`](crate::FieldName)'s own argument applied
//! one level in: every `&str` is a legal name in every namespace, so nothing about the string says
//! which face it came from — only where it came from does, and a type is what records that. And
//! since it is that argument, it is that construction: a view of a `str` costing nothing, not a
//! wrapper of its own.
//!
//! # The conversion family takes a BORROW, and that is measured
//!
//! [`TryFrom`](core::convert::TryFrom)'s type parameter carries an implicit [`Sized`] bound, so
//! `impl TryFrom<SqliteName> for Grade` over a view does not compile: `E0277`, *the size for values
//! of type `str` cannot be known at compilation time … required by an implicit `Sized` requirement
//! on this type parameter in `TryFrom`* — reported twice, once at the `impl` header and once at
//! `try_from`'s own signature, since a function argument is sized too.
//!
//! The family is therefore spelled over the borrow — `impl TryFrom<&SqliteName> for Grade` — which
//! is what every reader of one of these already holds: [`new`](crate::SqliteName::new) hands back a
//! `&Self`, and a vocabulary's accessor hands back a `&'static Self`. Nothing is passed by value
//! anywhere on the path, so the reference in the bound is the reference that was already there.
//!
//! # [`borrowed_name`] emits the DECLARATION, not only the impls
//!
//! The `unsafe` view rests on one claim: the type is `#[repr(transparent)]` over `str` and holds
//! nothing besides it. Emitting the struct is what makes that claim the macro's OWN rather than a
//! precondition each caller has to remember — there is no way to reach the view through a
//! declaration the safety argument does not already cover.
//!
//! `Eq`, `Ord` and `Hash` travel with it for the second half of the same reason. They forward to
//! the inner `str` only because they are DERIVED on a single-field struct, and that forwarding is
//! exactly what the [`Borrow`](core::borrow::Borrow) impl below promises — so the promise and the
//! thing that makes it true are written in one place.
//!
//! # …and the FOLD, which is about a word rather than about a type
//!
//! [`folds_to`] and [`folded`] are here for what they are ABOUT: the words a vocabulary's faces
//! spell, read the way an OPEN vocabulary has to read them. They carry no name type and are reached
//! by emitted code alone — see [`fold`] for the relation and for why there is exactly one of it.
/// Declare a borrowed name type: a `#[repr(transparent)]` view of a `str`, its unchecked view
/// constructor, and its borrow trio.
///
/// The caller writes the documentation, the visibility, the name, and the type's own public
/// constructor — which is where a name type says what it refuses. What a name type cannot differ
/// in is here.
/// Declare a VARIANT-name type: [`borrowed_name`]'s construction, plus the one constructor every
/// namespace spells identically.
///
/// The five differ in nothing but which face they name, so their doors are written once here rather
/// than five times — which is [`borrowed_name`]'s own argument taken one step: what a group of names
/// shares is a macro. It is [`FieldName`](crate::FieldName)'s door verbatim, an infallible `const`
/// view, because a variant's word is in exactly that position.
variant_name!
variant_name!
variant_name!
variant_name!
variant_name!
pub use ;
pub use borrowed_name;