layline_codegen/model/dispatch.rs
1//! Dispatches: bodies selected by an id the enclosing message has already read.
2
3use alloc::string::String;
4use alloc::vec::Vec;
5
6use super::Derive;
7
8use super::Scalar;
9
10/// Bodies selected by an id the enclosing message has already read, as `#[derive(Dispatch)]`
11/// declares.
12#[derive(Debug, Clone, PartialEq, Eq)]
13#[non_exhaustive]
14pub struct DispatchDef {
15 /// The type name.
16 pub name: String,
17 /// The id's type: `#[dispatch(id = ..)]`.
18 pub id: Scalar,
19 /// The arms, in declaration order.
20 pub arms: Vec<DispatchArm>,
21 /// The fallback variant for an unlisted id.
22 pub other: String,
23 /// Documentation.
24 pub doc: Option<String>,
25 /// Derives for this catalogue, written after the module's.
26 pub derives: Vec<Derive>,
27 /// The id's width in bits inside every payload: `#[dispatch(.., prefix = K)]`.
28 ///
29 /// Zero reads the id from elsewhere, and each payload's `Layout::PREFIX_BITS` must match.
30 pub prefix: u32,
31 /// Documentation for the fallback variant. `None` writes a general sentence.
32 pub other_doc: Option<String>,
33 /// The fallback variant's body type. `None` is `Vec<u8>`.
34 ///
35 /// Any type that is `From<&[u8]>` and `Deref<Target = [u8]>` works, such as a fixed-size
36 /// type that keeps the body without allocating.
37 pub other_body: Option<String>,
38}
39
40impl DispatchDef {
41 /// A dispatch with its fallback variant named `Unknown`.
42 #[must_use]
43 pub fn new(name: &str, id: Scalar, arms: Vec<DispatchArm>) -> Self {
44 Self {
45 name: String::from(name),
46 id,
47 arms,
48 other: String::from("Unknown"),
49 doc: None,
50 derives: Vec::new(),
51 prefix: 0,
52 other_doc: None,
53 other_body: None,
54 }
55 }
56
57 /// Sets the fallback variant's documentation.
58 #[must_use]
59 pub fn with_other_doc(self, doc: &str) -> Self {
60 Self { other_doc: Some(String::from(doc)), ..self }
61 }
62
63 /// Sets the id's width in bits inside every payload.
64 ///
65 /// Each payload declares the same width with `Container::Word { prefix, .. }`, and the
66 /// generated code asserts that they agree.
67 #[must_use]
68 pub fn with_prefix(self, prefix: u32) -> Self {
69 Self { prefix, ..self }
70 }
71
72 /// Sets the fallback variant's body type, in place of `Vec<u8>`.
73 #[must_use]
74 pub fn with_other_body(self, ty: &str) -> Self {
75 Self { other_body: Some(String::from(ty)), ..self }
76 }
77
78 /// Sets the derives written on this catalogue, after the module's.
79 #[must_use]
80 pub fn with_derives(self, derives: Vec<Derive>) -> Self {
81 Self { derives, ..self }
82 }
83
84 /// Renames the fallback variant.
85 #[must_use]
86 pub fn with_other(self, other: &str) -> Self {
87 Self { other: String::from(other), ..self }
88 }
89
90 /// Sets the documentation.
91 #[must_use]
92 pub fn with_doc(self, doc: &str) -> Self {
93 Self { doc: Some(String::from(doc)), ..self }
94 }
95}
96
97/// One arm of a [`DispatchDef`].
98#[derive(Debug, Clone, PartialEq, Eq)]
99#[non_exhaustive]
100pub struct DispatchArm {
101 /// The id that selects this arm.
102 pub id: i64,
103 /// The variant name.
104 pub name: String,
105 /// The body type, which implements `Layout`.
106 pub ty: String,
107 /// Documentation.
108 pub doc: Option<String>,
109}
110
111impl DispatchArm {
112 /// `#[value(id)] name(ty)`, undocumented.
113 #[must_use]
114 pub fn new(id: i64, name: &str, ty: &str) -> Self {
115 Self { id, name: String::from(name), ty: String::from(ty), doc: None }
116 }
117
118 /// Sets the documentation.
119 #[must_use]
120 pub fn with_doc(self, doc: &str) -> Self {
121 Self { doc: Some(String::from(doc)), ..self }
122 }
123}