layline_codegen/model/choice.rs
1//! Choices: the arms a switch selects between.
2
3use alloc::string::String;
4use alloc::vec::Vec;
5
6use super::{Endian, Segment};
7
8/// What a switch selects on.
9#[derive(Debug, Clone, PartialEq, Eq)]
10#[non_exhaustive]
11pub enum Discriminant {
12 /// The value of an earlier field.
13 ///
14 /// `outer.inner` names a field of a nested layout.
15 Field(String),
16 /// The number of bytes left in the body.
17 BodyLength,
18}
19
20/// One arm of a switch.
21///
22/// An arm's fields can refer only to each other.
23#[derive(Debug, Clone, PartialEq, Eq)]
24#[non_exhaustive]
25pub struct Arm {
26 /// The discriminant value that selects this arm.
27 pub value: u64,
28 /// The arm's segments, in wire order.
29 pub body: Vec<Segment>,
30 /// The variant name.
31 pub name: String,
32 /// Documentation.
33 pub doc: Option<String>,
34}
35
36impl Arm {
37 /// An undocumented arm.
38 #[must_use]
39 pub fn new(value: u64, name: &str, body: Vec<Segment>) -> Self {
40 Self { value, body, name: String::from(name), doc: None }
41 }
42
43 /// Sets the documentation.
44 #[must_use]
45 pub fn with_doc(self, doc: &str) -> Self {
46 Self { doc: Some(String::from(doc)), ..self }
47 }
48
49 /// Whether the arm reads to the end of its input.
50 #[must_use]
51 pub fn open_ended(&self) -> bool {
52 self.body.iter().any(Segment::open_ended)
53 }
54}
55
56/// The arms of a [`Segment::Switch`].
57///
58/// With a fallback [`other`](Self::other) variant, an unmatched value keeps its bytes: the rest of
59/// the body, or [`other_bytes`](Self::other_bytes) of them.
60#[derive(Debug, Clone, PartialEq, Eq)]
61#[non_exhaustive]
62pub struct ChoiceDef {
63 /// The type name.
64 pub name: String,
65 /// Byte order of the arms' fields.
66 pub endian: Endian,
67 /// The arms, in declaration order.
68 pub arms: Vec<Arm>,
69 /// The fallback variant for an unmatched value. `None` makes it a decode error.
70 pub other: Option<String>,
71 /// The fallback's size in bytes, when the choice is a union.
72 ///
73 /// `None` takes the rest of the body, so no field can follow the switch.
74 pub other_bytes: Option<usize>,
75 /// Documentation.
76 pub doc: Option<String>,
77}
78
79impl ChoiceDef {
80 /// A little-endian choice with no fallback.
81 #[must_use]
82 pub fn new(name: &str, arms: Vec<Arm>) -> Self {
83 Self {
84 name: String::from(name),
85 endian: Endian::Le,
86 arms,
87 other: None,
88 other_bytes: None,
89 doc: None,
90 }
91 }
92
93 /// Sets the byte order.
94 #[must_use]
95 pub fn with_endian(self, endian: Endian) -> Self {
96 Self { endian, ..self }
97 }
98
99 /// Adds a fallback variant that keeps an unmatched value's bytes.
100 #[must_use]
101 pub fn with_other(self, other: &str) -> Self {
102 Self { other: Some(String::from(other)), ..self }
103 }
104
105 /// Makes the choice a union of `bytes` bytes.
106 ///
107 /// Every arm must fill exactly that size, and a field can follow the switch.
108 #[must_use]
109 pub fn with_other_bytes(self, bytes: usize) -> Self {
110 Self { other_bytes: Some(bytes), ..self }
111 }
112
113 /// Sets the documentation.
114 #[must_use]
115 pub fn with_doc(self, doc: &str) -> Self {
116 Self { doc: Some(String::from(doc)), ..self }
117 }
118
119 /// Whether the choice reads to the end of the body.
120 ///
121 /// True when any arm does, or when the fallback has no fixed size.
122 #[must_use]
123 pub fn open_ended(&self) -> bool {
124 (self.other.is_some() && self.other_bytes.is_none())
125 || self.arms.iter().any(Arm::open_ended)
126 }
127}