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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
//! The official Cyclone **attributes**.
//!
//! ```text
//! cyclone-attributes → your source → cyclonec → generated code
//! ```
//!
//! This crate defines [`network`] and [`codec`], and does nothing with them. It
//! is the syntax half of Cyclone: the part that makes annotated Rust *compile*,
//! so that `cyclonec` has something to read.
//!
//! ```
//! use cyclone_attributes::*;
//!
//! #[network]
//! #[codec]
//! struct DeviceState {
//! #[network(u32)]
//! #[codec(edge, unity)]
//! id: u32,
//!
//! #[network(f32)]
//! #[codec(edge)]
//! temperature: f32,
//!
//! #[network(string)]
//! #[codec(unity)]
//! display_name: String,
//! }
//! ```
//!
//! # What it does
//!
//! The attributes are **inert markers**. Applied to an item, they remove
//! themselves and every Cyclone attribute inside it, and hand back the item
//! otherwise untouched — same fields, same types, same derives, same doc
//! comments, same spans.
//!
//! That removal is the entire implementation, and it exists for one narrow
//! reason: Rust does not allow an attribute macro on a *field*, so
//! `#[network(u32)]` cannot compile on its own. An attribute on the struct is
//! what makes the ones on its fields legal, by consuming them.
//!
//! So the annotated struct above compiles to exactly:
//!
//! ```
//! struct DeviceState {
//! id: u32,
//! temperature: f32,
//! display_name: String,
//! }
//! ```
//!
//! # What it does not do
//!
//! Everything else. There is no `Reader`, no `Writer`, no `Encode`, no
//! `Decode`, no registry, no reflection, no dynamic dispatch, and no generated
//! code of any kind. It reads no Cyclone type, validates no annotation, and
//! knows no codec name.
//!
//! `cyclonec` reads the annotations out of your **source**, not out of this
//! crate's expansion, and every semantic question belongs to it:
//!
//! - Whether `u32` names a Cyclone type.
//! - Whether a field declared `u64` may carry `#[network(u32)]`.
//! - What `edge` or `unity` mean, and which fields each one covers.
//!
//! On the last of those especially: a codec name is an identifier **you**
//! invent. This crate has no list of them, no default, and no opinion — `edge`,
//! `unity`, `server`, `orange_pi` are all the same to it, which is to say
//! nothing at all.
//!
//! # Scope
//!
//! This crate is not a serialization runtime and not a networking library. It is
//! two attributes and the code that takes them back off.
use ;
/// Marks a struct as a Cyclone network model, and declares the Cyclone wire
/// type of a field.
///
/// # On a model
///
/// ```
/// # use cyclone_attributes::network;
/// #[network]
/// struct DeviceState {
/// #[network(u32)]
/// id: u32,
/// }
/// ```
///
/// # On a field
///
/// `#[network(TYPE)]` declares the field's Cyclone wire type. The declared type
/// is the schema: `cyclonec` believes the attribute and never infers a Cyclone
/// type from the Rust one, so this
///
/// ```
/// # use cyclone_attributes::network;
/// #[network]
/// struct Reading {
/// #[network(u32)]
/// value: u64,
/// }
/// ```
///
/// declares a `u32` on the wire, whatever the Rust field says. Whether the two
/// are compatible is a question for `cyclonec`'s validation, later, and not for
/// this crate at any point.
///
/// A field attribute is never expanded on its own — Rust does not permit that.
/// It is consumed by the attribute on the enclosing model, which is why a model
/// carrying annotated fields must itself be marked.
///
/// # Expansion
///
/// The item, with every Cyclone attribute removed and nothing else changed.
/// Marks a struct as taking part in codec generation, and declares which codec
/// profiles a field belongs to.
///
/// # On a model
///
/// ```
/// # use cyclone_attributes::codec;
/// #[codec]
/// struct DeviceState {
/// #[codec(edge)]
/// id: u32,
/// }
/// ```
///
/// # On a field
///
/// `#[codec(...)]` lists the profiles the field belongs to, in the order they
/// were written. A field may belong to one, or to many, and there is no limit:
///
/// ```
/// # use cyclone_attributes::codec;
/// #[codec]
/// struct DeviceState {
/// #[codec(edge, unity, admin)]
/// id: u32,
///
/// #[codec(edge)]
/// temperature: f32,
/// }
/// ```
///
/// A profile name is an identifier **you** invent. This crate holds no list of
/// them and gives none of them meaning: `edge`, `unity`, `server`, `client`,
/// `orange_pi` are identifiers and nothing more. Grouping fields by profile is
/// `cyclonec`'s job, done by reading your source.
///
/// # Expansion
///
/// The item, with every Cyclone attribute removed and nothing else changed.
/// Removes every Cyclone attribute from a token stream, at any depth.
///
/// Both attributes do exactly this, which makes the pair order-independent and
/// idempotent: `#[network] #[codec]` and `#[codec] #[network]` produce the same
/// item, and so does either one alone. Whichever macro the compiler expands
/// first takes all of them off; the other, if it survives to run, finds nothing
/// left to do.
///
/// Everything that is not a Cyclone attribute is passed through untouched —
/// derives, `cfg`, doc comments, other macros' attributes — and every token
/// keeps its span, so an error in an annotated struct still points at the line
/// the user wrote.
/// Whether an attribute's contents name `network` or `codec`.
///
/// Only the path is read, and only its last segment, so `#[network(u32)]` and
/// `#[cyclone_attributes::network(u32)]` are both recognised. Anything else —
/// `#[derive(Debug)]`, `#[doc = "…"]`, `#[serde(rename = "network")]` — stops at
/// the first token that cannot be part of a path and is left alone.