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
//! The FOLD an open vocabulary reads every word through — the ONE relation, and the one place it is
//! written.
//!
//! A closed vocabulary's parse is an exact match: its words are its own, a client writes one of
//! them, and a word that is not one of them is a refusal. An OPEN one meets its words in whichever
//! spelling a producer happens to use — `leftShoulder` from a Swift enum, `left_shoulder` from a
//! Python model, `LEFT_SHOULDER` from a protobuf, `Left Shoulder` from a label file — and every one
//! of those is the SAME value. So the door folds before it compares, and what it folds is ASCII case
//! and the three separators.
//!
//! # Why the SEPARATORS go and not just the case
//!
//! A fold that dropped only case would put three of those four spellings on the escape, where they
//! would compare unequal to the variant they name and to each other. The four are not four values;
//! they are four languages writing one.
//!
//! # It is not a SYNONYM table, and the line is the rule
//!
//! `leftShoulder` and `left_shoulder` are one word in two spellings — a fact about a producer's
//! language. `pinky_mcp` and `little_mcp` are two words somebody decided meant the same thing, which
//! is a claim this layer has no authority to make. The fold covers the first and nothing of the
//! second: a vocabulary that wants the second writes a variant for it, or spells it with
//! `#[ingraph(rename = "…")]`.
//!
//! # ONE definition, workspace-wide
//!
//! Both halves of an open vocabulary's door read this module: [`folds_to`] is what the emitted
//! `new` compares each roster word with, and [`folded`] is what it builds the escape's carried word
//! out of. There is no second fold in `ingraph-codegen`, in an expansion, or beside a declaration —
//! an emitted door names `__private::name::folds_to` and calls THIS function, so a change to the
//! relation moves every vocabulary at once and two of them cannot come to disagree.
/// The three bytes a fold drops wherever they appear.
///
/// A separator and not a character: what they carry is a producer's word BOUNDARY, which every
/// language writes differently and none of them means.
const
/// Does `spelling` name the value whose canonical word is `canonical`?
///
/// The comparison IS the fold, WALKED rather than materialised: ASCII case is ignored on both sides
/// and `_`, `-` and a space are skipped wherever they appear, so `leftShoulder`, `left_shoulder`,
/// `LEFT-SHOULDER` and `Left Shoulder` all answer `true` against `left_shoulder`.
///
/// # Why it is a walk and not a normalised copy
///
/// A door that folded its input into a buffer would need a buffer wide enough for every spelling and
/// an answer for the ones that overran it. Walking has neither: the operand is read once per
/// candidate, nothing is allocated, and a spelling of any length is answered.
///
/// # It is BYTE-WISE, and that is the ASCII half of the relation stated honestly
///
/// Only ASCII letters are lowered — `to_ascii_lowercase`'s own domain — so two spellings differing
/// in a non-ASCII letter's case are two words. That is the same line [`folded`] draws, which is what
/// makes the two agree: a folded copy and a folded comparison answer alike, because they drop the
/// same three bytes and lower the same letters.
///
/// # `const`, and the walk is INDEXED for exactly that
///
/// A roster of lanes is a `const`, and the ruling that created it asks for its collisions to be
/// refused AT THE DECLARATION — which means this relation has to be spendable in a constant. So the
/// walk advances two byte INDEXES rather than two filtered iterators; `Iterator::next` is not
/// callable in a constant and `str::as_bytes` is. Nothing else moved: the same three bytes are
/// skipped, the same ASCII case is ignored, and the same pairs answer alike — which this module's
/// own suite pins, unedited, across the widening.
pub const
/// The fold, MATERIALISED — what an escape carries.
///
/// The escape holds a FOLDED word rather than the spelling it arrived in, which is what keeps an
/// open vocabulary's [`Eq`] and [`Hash`] about NAMES rather than about spellings: two producers
/// writing `left_paw_extra` and `leftPawExtra` for one word this vocabulary does not name are one
/// value here, compare equal, and land in one bucket.
///
/// It is the same relation [`folds_to`] walks, and it is worth saying which way round they agree:
/// two spellings fold to the same [`String`] exactly when `folds_to` answers `true` for either
/// against the other.
///
/// A [`String`] rather than a carrier, because the carrier is the DECLARATION'S: an escape variant's
/// field type is whatever it was written as, and the emitted door reaches it through
/// [`From<&str>`](From) — so this hands back the one form every carrier is built from.