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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
//! Decorator attachment: an opt-in transform that folds standalone body
//! decorators onto the statement that follows them, producing a fully-attached
//! tree.
//!
//! In `.deq`, a decorator precedes the statement it modifies:
//!
//! ```text
//! @SIMULATE_ONLY
//! M 0 1
//! ```
//!
//! The parser keeps decorators as standalone body items (the `Decorator`
//! variant of each body-statement enum), so the parsed AST is purely syntactic:
//! a formatter or linter sees every decorator as its own spanned node, and the
//! `parse -> Display -> re-parse` roundtrip is exact. This module produces the
//! *attached* view that semantic consumers want — each statement paired with the
//! decorators that preceded it, recursively through `REPEAT` blocks.
//!
//! # Design trade-offs
//!
//! The attached tree is a **separate, derived structure**, not a mutation of the
//! parsed AST. Decorators are deliberately *not* stored as a field on the parsed
//! statement nodes, and the transform does not run during parsing. Two reasons:
//!
//! * **Roundtrip fidelity stays exact.** Displaying and re-parsing the parsed
//! AST must yield the same AST. Attaching decorators to nodes would make
//! `Display` reconstruct their position, and a *dangling* decorator (one with
//! no following statement, e.g. just before `}`) has nowhere to be rendered
//! from — it would be lost on the round trip. Keeping attachment out of the
//! parsed AST keeps that invariant total, not conditional.
//! * **The syntactic form remains available.** A linter wants the lossless
//! parsed shape — every decorator as an ordered, spanned node — and wants
//! dangling decorators *reported*, not silently dropped. This transform
//! preserves that by leaving the parsed AST untouched and returning dangling
//! decorators to the caller (see below).
//!
//! The attached tree ([`Attached<S>`]) re-types only the recursive spine — the
//! `REPEAT` block — and reuses the parsed statement enums unchanged for every
//! other (leaf) statement. This avoids duplicating the ~30 statement variants
//! into a parallel hierarchy, and means a new leaf statement added to the
//! grammar is carried through automatically with no change here. The one cost of
//! that reuse: [`Attached::Statement`] nominally holds the whole parsed enum, so
//! its type does not *statically* forbid the `Repeat`/`Decorator` variants even
//! though this module never constructs one there (`Repeat` becomes
//! [`Attached::Repeat`]; `Decorator` is consumed). Treat `Attached::Statement`
//! as "a leaf statement" by construction.
//!
//! # Dangling decorators
//!
//! A decorator with no statement to attach to — trailing at the end of a body,
//! or the only thing in a block — is **not** an error and is **not** dropped. It
//! is returned to the caller alongside the attached tree. Dangling decorators
//! found inside nested `REPEAT` blocks are bubbled up into the single returned
//! list; each retains its own [`Span`](crate::Span), so its source location is
//! preserved regardless of nesting depth. The caller decides the policy (for
//! example: warn and ignore, or emit a diagnostic).
use crateSpanned;
use crate;
/// A statement in an attached tree: either a leaf statement or a `REPEAT` block
/// whose body has itself been attached.
///
/// `S` is one of the parsed body-statement enums ([`GadgetStatement`],
/// [`ComposeStatement`], [`ProgramStatement`]). Leaf statements reuse that enum
/// directly; only the recursive `REPEAT` spine is re-typed here.
/// A statement together with the decorators attached to it, in source order.
/// The three shapes a body item can take once decorators are folded.
/// A body-statement enum whose decorator and repeat variants can be split out.
///
/// Implemented for the three `.deq` body-statement enums so the attachment
/// logic can be written once.
impl_body_statement!;
/// Folds standalone decorators onto the following statement, recursively through
/// nested `REPEAT` blocks.
///
/// Returns the attached tree and every dangling decorator found at any depth
/// (see the [module docs](self)).
/// Attaches decorators within a `GADGET` body. See the [module docs](self).
///
/// ```
/// use deqagram::ast::{Definition, DeqFile};
/// use deqagram::decorators::attach_gadget_body;
///
/// let file: DeqFile = "GADGET G {\n @SIMULATE_ONLY\n M 0\n}\n".parse().unwrap();
/// let Definition::Gadget(g) = file.definitions.into_iter().next().unwrap().node else {
/// unreachable!()
/// };
///
/// let (attached, dangling) = attach_gadget_body(g.body);
/// assert!(dangling.is_empty());
/// assert_eq!(attached[0].decorators[0].name, "SIMULATE_ONLY");
/// ```
/// Attaches decorators within a `COMPOSE` body. See the [module docs](self).
/// Attaches decorators within a `PROGRAM` body. See the [module docs](self).