ingraph/lane/ident.rs
1//! [`LaneIdent`] — one lane's key, as a type a value cannot be passed as.
2
3use crate::name::borrowed_name;
4
5#[cfg(test)]
6mod tests;
7
8borrowed_name! {
9 /// ONE LANE'S KEY — the opaque word a backend block wrote, carried through the neutral layer
10 /// without being read.
11 ///
12 /// # It is OPAQUE, and that is the ruling rather than laziness
13 ///
14 /// A lane exists because one engine has a physics — a field has a tokenizer, a schema is
15 /// immutable — so the ruling that created it put the vocabulary INSIDE that engine's own block and
16 /// gave the neutral layer exactly one new thing: a slot publishes a roster of these. Path
17 /// validation, boot checks and merge provenance all ask the roster; none of them parses the block
18 /// it came from, and none of them knows what the word means.
19 ///
20 /// So what a reader may do with one is compare it, hash it, print it and hand it back. What no
21 /// reader may do is decide something from its SHAPE — that a two-letter word is a language, that a
22 /// four-letter one is a script — because the party that wrote it is the only one that knows.
23 ///
24 /// # It validates NOTHING, and its neighbour does
25 ///
26 /// [`FieldName`](crate::FieldName)'s own posture, for the same reason: every string is a legal
27 /// lane key as far as this layer is concerned, so there is no check to write here. What DOES
28 /// decide whether a word can ever be reached is [`LanguageTag`](super::LanguageTag), one seam
29 /// over — a key nothing reduces to is a key no tag arrives at, and that is a fact about the gate
30 /// rather than about the identifier.
31 ///
32 /// # It costs nothing
33 ///
34 /// `#[repr(transparent)]` over `str` and holding nothing else, so `&LaneIdent` is a `&str` at the
35 /// ABI and [`new`](Self::new) is a VIEW rather than a conversion. It is unsized for the reason
36 /// `str` is, which is why it carries neither [`Clone`] nor [`Copy`]: what a caller holds is the
37 /// borrow, and a roster is `&'static [Lane]` for exactly that reason.
38 ///
39 /// An OWNED lane word — one a refusal carries out of the gate — is
40 /// [`Utf8Bytes`](smol_bytes::Utf8Bytes), which is this workspace's text carrier and the one an
41 /// error may hold past the borrow that produced it. See [`UnknownLane`](super::UnknownLane).
42 pub struct LaneIdent;
43}
44
45impl LaneIdent {
46 /// **THE ZERO-CONFIGURATION LANE** — `und`, BCP-47's own *undetermined* primary subtag.
47 ///
48 /// A declaration that names no lanes has ONE, and this is its key. That keeps every reader
49 /// uniform: there is no *is this corpus fanned* fork anywhere, because an unfanned corpus is a
50 /// fanned one whose roster has a single entry — which is what
51 /// [`Lanes::LANES`](super::Lanes::LANES)' default says in one line.
52 ///
53 /// The standard's own word rather than one invented here, on
54 /// [`WritingSystem::Zzzz`](crate::WritingSystem::Zzzz)'s reasoning exactly: a vocabulary that already has a name
55 /// for *this is not determined* is a vocabulary whose name should be used.
56 pub const UND: &'static Self = Self::new("und");
57
58 /// View `key` as a lane key.
59 ///
60 /// `const`, so a roster known at compile time can be built in a constant — which is where a
61 /// declaration's lanes actually are.
62 ///
63 /// It refuses nothing, per the type's own note: the neutral layer does not read this word.
64 #[inline]
65 #[must_use]
66 pub const fn new(key: &str) -> &Self {
67 Self::view(key)
68 }
69
70 /// This key as a `str`.
71 ///
72 /// Beside [`Deref`](core::ops::Deref) and [`AsRef`](core::convert::AsRef) rather than instead of
73 /// them, and it earns its place by being `const`: a roster is a `const`, its collision audit is
74 /// spent AT THE DECLARATION, and neither trait road is callable in a constant.
75 #[inline]
76 #[must_use]
77 pub const fn as_str(&self) -> &str {
78 &self.0
79 }
80}