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
295
296
297
298
//! Wire fields that encode computes instead of taking from the caller.
use crate::{Absence, Count, Coverage, Discriminant, Kind, Len, Presence, Segment};
/// A wire field that encode computes from the value.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Derived {
/// `field = (collection.len() - offset) / scale`
Count {
/// The collection the field counts.
of: String,
scale: u32,
offset: i32,
/// The decode limit on elements, if any.
cap: Option<usize>,
},
/// `field = (isqrt(collection.len()) - offset) / scale`
///
/// Encode refuses a length that is not a square.
Squared {
/// The square collection whose order the field holds.
of: String,
scale: u32,
offset: i32,
/// The decode limit on `order * order`, if any.
cap: Option<usize>,
},
/// `field = (encoded byte length of the text field - offset) / scale`
TextLen {
/// The text field whose byte length this is.
of: String,
/// The text's `TextCodec`, which sets the byte count. `None` means UTF-8.
codec: Option<String>,
scale: u32,
offset: i32,
/// The decode limit on bytes, if any.
cap: Option<usize>,
},
/// `field = the byte position the segment was written at`
Offset {
/// The segment whose position this is.
of: String,
/// Whether the segment is a single record. Only error messages use it.
record: bool,
},
/// `field = (one element's wire width - offset) / scale`
///
/// Encode packs elements at `WIRE_BYTES` apart, with no gaps.
Stride {
/// The element [`Kind`].
elem: Kind,
scale: u32,
offset: i32,
},
/// `field = (the byte length the collection wrote - offset) / scale`
///
/// Reserved, like [`Offset`](Derived::Offset).
ByteLen {
/// The segment whose byte length this is.
of: String,
/// Whether the segment is a single record. Only error messages use it.
record: bool,
},
/// `field = (the arm's encoded byte length - offset) / scale`
///
/// Measured before the field is written, because a varint field has no fixed size to reserve.
ArmLen {
/// The switch whose byte length this is.
of: String,
scale: u32,
offset: i32,
/// The decode limit on bytes, if any.
cap: Option<usize>,
},
/// `field = the value of the switch's arm`
///
/// The open arm has no value. It keeps its raw bytes instead.
Discriminant {
/// The switch whose arm the field selects.
of: String,
/// The field the discriminant is written to.
field: String,
},
/// `field = field, with each mask bit set when its optional field is Some`, or for a mask that
/// marks absence, when it is None
Flags {
/// The flags field. Encode keeps the bits that no optional field uses.
field: String,
/// `(mask, optional field name, whether set bits mean present)`, in declaration order.
bits: Vec<(u64, String, bool)>,
},
/// `field = whether its optional field is Some`, or with `set` false, None
Presence {
/// The optional field the flag controls.
of: String,
/// Whether `true` means present.
set: bool,
},
/// `field = the algorithm's check value over the bytes it covers`
///
/// Reserved when the covered range extends past the field.
Checksum {
/// Rust path of the `layline::Checksum` type.
algorithm: String,
over: Coverage,
},
}
impl Derived {
/// The noun phrase an error message uses for this derivation.
pub(crate) fn what(&self) -> &'static str {
match self {
Derived::Count { .. } => "length of a collection",
Derived::Squared { .. } => "order of a square collection",
Derived::TextLen { .. } => "encoded length of a string",
Derived::Offset { record: false, .. } => "position of a collection",
Derived::Offset { record: true, .. } => "position of a record",
Derived::ByteLen { record: false, .. } => "byte length of a collection",
Derived::ByteLen { record: true, .. } => "byte length of a record",
Derived::Stride { .. } => "wire width of one element",
Derived::ArmLen { .. } => "byte length of a switch",
Derived::Discriminant { .. } => "discriminant of a switch",
Derived::Flags { .. } => "presence bits of optional fields",
Derived::Presence { .. } => "presence of an optional field",
Derived::Checksum { .. } => "check value over the bytes it covers",
}
}
/// The fix to suggest, for derivations that have one.
pub(crate) fn instead(&self) -> Option<&'static str> {
match self {
Derived::Flags { .. } => Some("Give the presence bits a word of their own"),
Derived::Presence { .. } => {
Some("Write a flags word with a mask per field (`#[when(w & 0x01)]`)")
}
Derived::Checksum { .. } => Some("Give the checksum a field of its own"),
Derived::Stride { .. } => Some("Give the stride a field of its own"),
_ => None,
}
}
/// The slot this derivation reserves, and the segment it describes.
///
/// Encode writes zeros to a reserved field, then fills in the number after the segment.
pub(crate) fn reserves(&self) -> Option<(SlotOf, &str)> {
match self {
Derived::Offset { of, .. } => Some((SlotOf::Position, of)),
Derived::ByteLen { of, .. } => Some((SlotOf::Length, of)),
_ => None,
}
}
}
/// What a reserved field holds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SlotOf {
/// The segment's byte position.
Position,
/// The segment's byte length.
Length,
}
/// Every computed field in the segments, as `(field, derivation)`.
pub(crate) fn derivations(segments: &[Segment]) -> Vec<(String, Derived)> {
let mut out = Vec::new();
for seg in segments {
match seg {
Segment::Repeat { name: coll, element, count, at, .. } => {
match count {
Count::Field { by, cap } | Count::Strided { by, cap, .. } => {
out.push((
by.field.clone(),
Derived::Count {
of: coll.clone(),
scale: by.scale,
offset: by.offset,
cap: *cap,
},
));
}
Count::Squared { by, cap } => {
out.push((
by.field.clone(),
Derived::Squared {
of: coll.clone(),
scale: by.scale,
offset: by.offset,
cap: *cap,
},
));
}
Count::Window(Len::Field { by, .. }) => {
out.push((
by.field.clone(),
Derived::ByteLen { of: coll.clone(), record: false },
));
}
_ => {}
}
if let Count::Strided { stride, .. } = count {
out.push((
stride.field.clone(),
Derived::Stride {
elem: element.clone(),
scale: stride.scale,
offset: stride.offset,
},
));
}
if let Some(field) = at {
out.push((field.clone(), Derived::Offset { of: coll.clone(), record: false }));
}
}
Segment::Placed { name, at, absent, .. } => {
out.push((at.clone(), Derived::Offset { of: name.clone(), record: true }));
if let Some(Absence::ZeroLength { by, .. }) = absent {
out.push((by.clone(), Derived::ByteLen { of: name.clone(), record: true }));
}
}
Segment::Value {
name: text,
kind: Kind::Text { len: Len::Field { by, cap, .. }, codec },
..
} => {
out.push((
by.field.clone(),
Derived::TextLen {
of: text.clone(),
codec: codec.clone(),
scale: by.scale,
offset: by.offset,
cap: *cap,
},
));
}
Segment::Switch { name: body, on, window, .. } => {
if let Discriminant::Field(field) = on {
out.push((
field.clone(),
Derived::Discriminant { of: body.clone(), field: field.clone() },
));
}
if let Some(Len::Field { by, cap, .. }) = window {
out.push((
by.field.clone(),
Derived::ArmLen {
of: body.clone(),
scale: by.scale,
offset: by.offset,
cap: *cap,
},
));
}
}
Segment::Opt {
when:
Presence::Mask { field: flag, mask } | Presence::MaskClear { field: flag, mask },
field,
} => {
let set = matches!(seg, Segment::Opt { when: Presence::Mask { .. }, .. });
let bit = (*mask, field.name.clone(), set);
match out
.iter_mut()
.find(|(df, d)| df == flag && matches!(d, Derived::Flags { .. }))
{
Some((_, Derived::Flags { bits, .. })) => bits.push(bit),
_ => out.push((
flag.clone(),
Derived::Flags { field: flag.clone(), bits: vec![bit] },
)),
}
}
Segment::Opt {
when: Presence::Flag { field: flag } | Presence::FlagClear { field: flag },
field,
} => {
let set = matches!(seg, Segment::Opt { when: Presence::Flag { .. }, .. });
out.push((flag.clone(), Derived::Presence { of: field.name.clone(), set }));
}
Segment::Checksum { name, algorithm, over, .. } => {
out.push((
name.clone(),
Derived::Checksum { algorithm: algorithm.clone(), over: over.clone() },
));
}
_ => {}
}
}
out
}
/// Reserved fields filled in after a later segment, as `(field, segment)`.
pub(crate) fn back_patched(segments: &[Segment]) -> Vec<(String, String)> {
derivations(segments)
.into_iter()
.filter_map(|(field, d)| d.reserves().map(|(_, of)| (field, String::from(of))))
.collect()
}