Skip to main content

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}