macroonz_compiler/token/generation/
types.rs

1//! The generation home's declarations.
2//!
3//! Declarations only.
4//! The invariant nucleus lives in `type_guard.rs`, and nonsemantic source restoration lives in `provenance.rs`; both are this file's children so no public field is opened.
5
6use crate::bounded::{Bounded, NonEmptyError};
7use crate::token::SpanHandle;
8
9#[path = "type_guard.rs"]
10mod guard;
11
12#[path = "provenance.rs"]
13mod provenance;
14
15/// Tokens one generated tree may carry at any one nesting level.
16pub const GENERATED_TOKEN_LIMIT: usize = 4096;
17
18/// Whether one generated punctuation mark joins the token after it.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
20pub enum GeneratedSpacing {
21    /// It joins what follows: `::`, `->`, `'static`.
22    Joint,
23    /// It stands alone.
24    Alone,
25}
26
27/// The delimiter one generated group is written with.
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29pub enum GeneratedDelimiter {
30    /// `( … )`.
31    Parenthesis,
32    /// `{ … }`.
33    Brace,
34    /// `[ … ]`.
35    Bracket,
36    /// A compiler token group with no written delimiter.
37    ///
38    /// This row exists for preserving an invisible group the compiler supplied, not for inventing grouping a caller did not declare.
39    Bare,
40}
41
42/// One exact literal form carried from declared Rust into generated Rust.
43///
44/// The private value is admitted only through its typed constructors or the preserved-fragment road.
45#[derive(Debug, Clone, PartialEq, Eq, Hash)]
46pub struct GeneratedLiteral {
47    value: GeneratedLiteralValue,
48}
49
50/// The exact literal forms that need more custody than the older semantic constructors provide.
51#[derive(Debug, Clone, PartialEq, Eq, Hash)]
52enum GeneratedLiteralValue {
53    Number(String),
54    Character(char),
55    Byte(u8),
56    NulTerminatedText(Vec<u8>),
57}
58
59/// A crate-internal read of one admitted generated literal.
60#[derive(Clone, Copy)]
61pub(crate) enum GeneratedLiteralForm<'literal> {
62    Number(&'literal str),
63    Character(char),
64    Byte(u8),
65    NulTerminatedText(&'literal [u8]),
66}
67
68/// Why an exact literal could not be admitted for generation.
69#[must_use = "a generated-literal refusal names the exact literal contract that disagreed"]
70#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
71pub enum GeneratedLiteralRefusal {
72    /// The spelling is not one numeric literal admitted by the capture owner.
73    NotANumber,
74    /// C-string material contains an interior NUL and therefore has no lawful C-string literal value.
75    InteriorNul,
76}
77
78/// Why one preserved captured fragment could not become a generated tree.
79#[must_use = "a fragment-generation issue names the exact token conversion that refused"]
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
81pub enum FragmentGenerationIssue {
82    /// One captured literal could not enter its generated literal form.
83    Literal(GeneratedLiteralRefusal),
84    /// The generated tree would exceed its declared token magnitude.
85    Unbounded,
86}
87
88/// One refused captured-fragment projection with the exact source span it belongs to.
89#[must_use = "a fragment-generation refusal carries its issue and exact captured span"]
90#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
91pub struct FragmentGenerationRefusal {
92    pub(super) issue: FragmentGenerationIssue,
93    pub(super) at: Option<SpanHandle>,
94}
95
96/// Why one flat keyed-row projection could not produce exactly one non-empty item run.
97#[must_use = "a generated-row refusal names the exact row and non-empty token disagreement"]
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
99pub struct GeneratedRowRefusal {
100    position: usize,
101    cause: NonEmptyError,
102}
103
104/// One token a renderer writes.
105///
106/// A renderer states a literal's value and never its spelling, and the quoting, the escaping, and the absence of a suffix are the tree's business.
107///
108/// # Ordering
109///
110/// The roster grows at its end and nowhere else: each arm's slot is a byte of [`GeneratedTree::canonical_bytes`], which is what a rendered unit's identity is derived over.
111#[derive(Debug, Clone, PartialEq, Eq, Hash)]
112pub enum GeneratedToken {
113    /// An ordinary identifier-shaped word.
114    Word(String),
115    /// One punctuation character and whether it joins what follows.
116    Punct {
117        /// The character.
118        mark: char,
119        /// Whether it joins what follows.
120        spacing: GeneratedSpacing,
121    },
122    /// A text literal, stated as its text; the quoting is the tree's business.
123    Text(String),
124    /// A delimited group.
125    Group {
126        /// The delimiter.
127        delimiter: GeneratedDelimiter,
128        /// The tokens inside.
129        tokens: Bounded<GeneratedToken, GENERATED_TOKEN_LIMIT>,
130    },
131    /// A byte-string literal's material, written `b"…"`.
132    ByteText(Vec<u8>),
133    /// An unsuffixed integer literal.
134    Number(u64),
135    /// A raw identifier's name without its `r#` spelling marker.
136    RawIdentifier(String),
137    /// An exact caller-authored literal admitted through [`GeneratedLiteral`].
138    Literal(GeneratedLiteral),
139}
140
141/// One generated token tree: the artifact a renderer produces.
142#[derive(Clone)]
143pub struct GeneratedTree {
144    tokens: Bounded<GeneratedToken, GENERATED_TOKEN_LIMIT>,
145    source_spans: Vec<Option<SpanHandle>>,
146}
macroonz_compiler/token/generation/types.rs

macroonz_compiler/token/generation/
types.rs
