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
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
//! Derive macros for `layline`: `Layout`, `Message`, `FieldCodec` and `Dispatch`.
//!
//! Each attribute, and each key inside it, may appear once.
//! A rejected type still implements its trait, so the build reports only the real error.
use TokenStream;
/// Derives `Layout` for a fixed-size struct.
///
/// Fields are laid out in declaration order and must cover every bit.
/// `decode` returns `Result<Self, ParseError>` if the struct uses `#[magic]`, `#[checksum]`,
/// `#[range]`, `prefix_value` or `internal`. Otherwise it returns `Self`.
///
/// # Container attributes
///
/// Choose one size:
///
/// - `#[layout(bits = N)]`: `N` bits of bit fields. `N` is a multiple of 8.
/// - `#[layout(bytes = N)]`: `N` bytes of scalars, arrays and nested layouts.
/// - `#[layout(words = N)]`: `N` 16-bit words of bit fields.
///
/// Optional keys:
///
/// - `endian = le | be`: byte order. Default `le`.
/// - `order = lsb | msb`: bit order for `bits` and `words`. With `msb`, the first field takes the
/// most significant bits. Default `lsb`.
/// - `prefix = K`: the low `K` bits hold a `Dispatch` id. Sets `Layout::PREFIX_BITS`. `bits` only.
/// - `prefix_value = V`: the prefix value. Encode writes it and decode checks it. Needs `prefix`.
/// - `view`: also generates `<Name>View`, which reads and writes the fields in place in a byte
/// buffer. Not allowed with `#[magic]`, `#[checksum]` or `#[range]`.
/// - `internal`: marks a block that `Message` generates. Makes `decode` fallible.
/// - `crate = path`: the path to `layline`. Default `::layline`.
///
/// # Field attributes
///
/// - `#[bits(N)]`: the width in bits, for `bits` and `words`. The type is an integer, `bool`,
/// `U<N>`, `I<N>`, or a `FieldCodec` whose `BITS` is `N`. In `words`, a field fits in one word.
/// - `#[codec(N)]`: a `FieldCodec` stored as an 8, 16, 32 or 64-bit integer, or an array of
/// them. `bytes` only.
/// - `#[bytes(N)]`: a nested layout of `N` bytes, or an array of them. `N` must match its
/// `WIRE_BYTES`. `bytes` and `words` only.
/// - `#[at(bit = N)]`, `#[at(byte = N)]`: the field's expected position. The build fails if the
/// widths put it elsewhere. `STATED` lists these positions.
/// - `#[overlay(name: T)]`: adds `name` and `set_name`, which read and write the field's bits as
/// the `FieldCodec` `T`. `bits` and `words` only.
/// - `#[magic(0xAA55)]`, `#[magic(b"\x7fELF")]`: fixed bytes. Decode checks them and encode
/// writes them. `bytes` only.
/// - `#[checksum(Alg, over = a..=b)]`: a checksum over fields `a` to `b`. Decode verifies it and
/// encode computes it. `bytes` only.
/// - `#[range(lo..=hi)]`, `#[range(..=hi)]`, `#[range(lo..)]`: the allowed values. Decode rejects
/// others.
///
/// `Layout` rejects the `Message` attributes `#[count]`, `#[len]`, `#[stride]`, `#[fill]`,
/// `#[seek]`, `#[text]`, `#[until]`, `#[var]`, `#[message]`, `#[switch]` and `#[when]` with a
/// clear error.
///
/// ```
/// # use layline::{FieldCodec, Layout};
/// # #[derive(FieldCodec, Debug, Clone, PartialEq)] #[bits(4)] pub struct State(pub u8);
/// #[derive(Layout)]
/// #[layout(bits = 32)]
/// pub struct StatusWord {
/// #[bits(3)] pub version: u8,
/// #[bits(1)] pub urgent: bool,
/// #[bits(12)] #[at(bit = 4)] pub sequence: u16,
/// #[bits(4)] pub state: State,
/// #[bits(10)] pub payload_len: u16,
/// #[bits(2)] pub spare: u8,
/// }
/// ```
/// Derives `Dispatch` for an enum of `Layout` payloads selected by an id.
///
/// A payload type used by only one variant also gets `From<T>` and `Slot<T>`.
///
/// # Container attributes
///
/// - `#[dispatch(id = u16)]`: the id type.
/// - `prefix = K`: the id is the low `K` bits of each payload. Sets `Dispatch::PREFIX_BITS`.
/// Each payload must declare `#[layout(prefix = K)]`.
/// - `crate = path`: the path to `layline`. Default `::layline`.
///
/// # Variant attributes
///
/// - `#[value(N)]`: the variant's id.
/// - `#[other]`: the fallback `Unknown { id, body }`, for unknown ids and payloads that fail to
/// decode. `body` is `&'a [u8]` if the enum has a lifetime, and `Vec<u8>` otherwise.
///
/// ```
/// # use layline::{Dispatch, Layout};
/// # #[derive(Layout, Debug, Clone, PartialEq)] #[layout(bytes = 2)] pub struct Sample { pub a: u16 }
/// # #[derive(Layout, Debug, Clone, PartialEq)] #[layout(bytes = 2)] pub struct TimePulse { pub a: u16 }
/// #[derive(Dispatch)]
/// #[dispatch(id = u16)]
/// pub enum Payload<'a> {
/// #[value(4)] Sample(Sample),
/// #[value(13)] TimePulse(TimePulse),
/// #[other] Unknown { id: u16, body: &'a [u8] },
/// }
/// ```
/// Derives `FieldCodec` and `WireInt` for an integer newtype or an enum of named values.
///
/// Every `N`-bit value decodes.
///
/// # Container attributes
///
/// - `#[bits(N)]`: the width, 1 to 64. The newtype's integer and every variant's value must fit.
/// - `#[bits(N, crate = path)]`: the path to `layline`. Default `::layline`.
///
/// # Variant attributes
///
/// - `#[value(N)]`: the raw value of a unit variant.
/// - `#[other]`: a one-field variant, over an unsigned integer, for every unlisted value. Without
/// it, the variants must list every `N`-bit value.
///
/// ```
/// # use layline::FieldCodec;
/// #[derive(FieldCodec)]
/// #[bits(15)]
/// pub struct TrackNumber(u16);
///
/// #[derive(FieldCodec)]
/// #[bits(3)]
/// pub enum Identity {
/// #[value(0)] Pending,
/// #[value(2)] Friend,
/// #[other] Undefined(u8),
/// }
/// ```
/// Derives `Message` for a variable-size struct or enum, or `Choice` for an enum that
/// `#[switch]` selects.
///
/// Consecutive plain fields become a hidden `#[derive(Layout)]` struct. Encode fills in count,
/// length, offset, discriminant and flag fields from the fields they describe.
///
/// # Container attributes
///
/// - `#[message(endian = le | be)]`: byte order. Default `le`.
/// - `#[message(bits)]`, `#[message(bits, order = lsb | msb)]`: all fields are bit fields, padded
/// with zero bits to a whole byte. Default order `lsb`.
/// - `#[message(needs(a: u8, b: u16))]`: parameters the parent message supplies. They become
/// `Message::Ctx`, a generated `<Name>Ctx` struct.
/// - `#[message(closed)]`: on an enum, an unknown discriminant fails with
/// `ParseError::Malformed`.
/// - `#[message(crate = path)]`: the path to `layline`. Default `::layline`.
///
/// # Collection attributes
///
/// A `Vec<T>` or `Box<[T]>` field takes one of these:
///
/// - `#[count(f)]`: `f` elements. `f` is an earlier field, or `hdr.f` in an earlier nested layout.
/// - `#[count(f * f)]`: `f` squared elements.
/// - `#[count(f, scale = S, offset = O, cap = N)]`: `f * S + O` elements. Decode rejects more
/// than `N`.
/// - `#[len(f)]`: `f` bytes. Takes the same keys. Also sizes a `#[text]` string or a `#[switch]`
/// body.
/// - `#[fill]`, `#[fill(cap = N)]`: whole elements until the message ends.
/// - `#[until(b)]`: bytes up to the terminator `b`. Decode consumes it and encode appends it.
/// - `#[until(mask = M)]`: elements up to and including the first whose first byte has the `M`
/// bits set.
///
/// # Field attributes
///
/// - `#[stride(f)]`, `#[stride(f, scale = S, offset = O)]`: the byte size of one element. Use with
/// `#[count]`.
/// - `#[seek(f)]`: read at the byte offset in `f`, counted from the start of the message. An
/// `Option<T>` at offset zero is `None`.
/// - `#[at(byte = N)]`: the byte offset where the field starts.
/// - `#[bytes(N)]`: the size of a nested layout, one element, a `#[switch]` body, or a NUL-padded
/// `#[text]` string.
/// - `#[codec(N)]`: a `FieldCodec` stored as an 8, 16, 32 or 64-bit integer.
/// - `#[var]`: a `VarCodec` value, whose size is read from the wire.
/// - `#[text]`, `#[text(Codec)]`: a `String`, as UTF-8 or through the `TextCodec` `Codec`.
/// - `#[message]`: a nested `Message`, boxed or not.
/// - `#[with(f, g)]`: earlier fields passed, in order, as the nested message's `needs`. Use with
/// `#[message]`.
/// - `#[switch(f)]`: an enum whose variant `f` selects. `#[switch(..)]` selects by the remaining
/// length.
/// - `#[when(flags & MASK)]`, `#[when(flag)]`: an `Option<T>` present when the bits are set.
/// Encode sets them for `Some` and clears them for `None`.
/// - `#[when(n > 0)]`: an `Option<T>` present when `n` is non-zero. Use with `#[seek]`.
/// - `#[fill]` on an `Option<T>`: present when bytes remain.
/// - `#[magic(0xFE)]`, `#[magic(b"SEAL")]`: fixed bytes. Decode checks them and encode writes
/// them.
/// - `#[checksum(Alg, over = a..=b)]`: a checksum over fields `a` to `b`. Decode verifies it and
/// encode computes it.
/// - `#[range(lo..=hi)]`: the allowed values. Decode rejects others.
///
/// # Bit message attributes
///
/// With `#[message(bits)]`:
///
/// - `#[bits(N)]`: the width in bits, 1 to 64. `bool` is 1 bit. `U<N>` and `I<N>` are `N` bits.
/// - `#[present]`: an `Option<T>` preceded by its own presence bit.
/// - `#[when(..)]`: as above.
/// - `#[var]`: a `BitCodec` value, whose width is read from the wire.
///
/// # Variant attributes
///
/// - `#[value(N)]`: the discriminant. The payload is a `Message`, a scalar, or a `#[bytes(N)]`
/// layout.
/// - `#[other]`: a one-field variant for every unlisted discriminant. It holds `Vec<u8>`, or
/// `[u8; N]` in a fixed-size enum.
///
/// ```
/// # use layline::{Layout, Message};
/// # #[derive(Message, Debug, Clone, PartialEq)] #[message(closed)]
/// # pub enum Body { #[value(0)] A(u8), #[value(1)] B(u8) }
/// # #[derive(Layout, Debug, Clone, PartialEq)] #[layout(bytes = 2)] pub struct Entry { pub a: u16 }
/// #[derive(Layout, Debug, Clone, PartialEq)]
/// #[layout(bits = 24)]
/// pub struct Header {
/// #[bits(2)] pub kind: u8,
/// #[bits(4)] pub n_entries: u8,
/// #[bits(2)] pub flags: u8,
/// #[bits(6)] pub table_offset: u8,
/// #[bits(10)] pub spare: u16,
/// }
///
/// #[derive(Message)]
/// pub struct Packet {
/// #[bytes(3)] pub header: Header,
/// #[when(header.flags & 0x01)] pub stamp: Option<u16>,
/// #[switch(header.kind)] pub body: Body,
/// #[count(header.n_entries)] #[seek(header.table_offset)] #[bytes(2)]
/// pub entries: Vec<Entry>,
/// }
/// ```