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
//! A refusal reason's LABEL, as a type a message cannot be passed as: [`ReasonName`].
use crate::name::borrowed_name;
borrowed_name! {
/// A skip reason's stable wire label — the string an operator's own vocabulary is recognised by
/// on the far side of an erased tap.
///
/// # What a `&str` here could not say
///
/// [`SkipLabel`](crate::SkipLabel) has two ends and a `&str` made them one type. A label is
/// matched, not read: `from_label` asks whether this exact string is one of the vocabulary's, and
/// the answer decides whether an app acts on the refusal. Every other string on the same path is
/// PROSE — the content a refusal names ([`Skip::about`](crate::Skip::about)), which is rendered
/// for a human and interpreted by nobody — so with both spelled `&str` an implementation could
/// hand its per-item detail back as its label and the compiler had nothing to check. The match
/// then fails for every item, silently, which is the failure a typed round-trip exists to prevent.
///
/// A type rather than a check, because there is no check to write. Every `&str` is a legal label,
/// so nothing about the string says which of the two roles it was in — only where it came from
/// does, and a type is what records that.
///
/// # It validates nothing
///
/// A label reaches no position where a character acquires a second meaning: it is compared for
/// equality and printed, never quoted, never spliced, never made into a path. That is
/// [`FieldName`](crate::FieldName)'s situation rather than
/// [`SlotName`](crate::SlotName)'s — the charset there exists because an index name becomes a
/// directory or a table, and nothing here becomes either.
///
/// It also has to stay permissive to be honest: a vocabulary spells its labels for its own
/// operators, and refusing a space or a hyphen would refuse names that read better than the ones
/// left. What makes a label good is that it is UNIQUE within its vocabulary and stable across
/// releases, and neither is a property of the string.
///
/// # Where the type earns its second keep
///
/// A tap is the only vantage an app has on a refusal, and the labels it observes are the natural
/// thing to COUNT, group and eventually store. At that moment a label is a key, and this crate
/// already keeps its keys apart by type — a stored label joins [`FieldName`](crate::FieldName)
/// and [`SlotName`](crate::SlotName) rather than arriving as the one loose string among them.
/// Nothing stores one today; the type is what keeps that from being a migration.
///
/// # It costs nothing
///
/// `#[repr(transparent)]` over `str` and holding nothing else, so `&ReasonName` is a `&str` at
/// the ABI and [`new`](Self::new) is a VIEW rather than a conversion — which is what lets
/// [`SkipReason::decode`](crate::SkipReason::decode) hand the erased wire spelling to a typed
/// `from_label` without copying it.
pub struct ReasonName;
}
impl ReasonName {
/// View `label` as a reason name.
///
/// `const`, so the labels a vocabulary spells in its own source can be built in constants — which
/// is where a closed set of labels belongs.
///
/// Infallible, and that is the type's content rather than an omission — see the type's note on
/// what it does not validate.
#[inline]
pub const fn new(label: &str) -> &Self {
Self::view(label)
}
}
#[cfg(test)]
mod tests;