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 /// The fallback variant's body type. `None` is `Vec<u8>`.
32 ///
33 /// Any type that is `From<&[u8]>` and `Deref<Target = [u8]>` works, such as a fixed-size
34 /// type that keeps the body without allocating.
35 pub other_body: Option<String>,
36}
37
38impl DispatchDef {
39 /// A dispatch with its fallback variant named `Unknown`.
40 #[must_use]
41 pub fn new(name: &str, id: Scalar, arms: Vec<DispatchArm>) -> Self {
42 Self {
43 name: String::from(name),
44 id,
45 arms,
46 other: String::from("Unknown"),
47 doc: None,
48 derives: Vec::new(),
49 prefix: 0,
50 other_body: None,
51 }
52 }
53
54 /// Sets the id's width in bits inside every payload.
55 ///
56 /// Each payload declares the same width with `Container::Word { prefix, .. }`, and the
57 /// generated code asserts that they agree.
58 #[must_use]
59 pub fn with_prefix(self, prefix: u32) -> Self {
60 Self { prefix, ..self }
61 }
62
63 /// Sets the fallback variant's body type, in place of `Vec<u8>`.
64 #[must_use]
65 pub fn with_other_body(self, ty: &str) -> Self {
66 Self { other_body: Some(String::from(ty)), ..self }
67 }
68
69 /// Sets the derives written on this catalogue, after the module's.
70 #[must_use]
71 pub fn with_derives(self, derives: Vec<Derive>) -> Self {
72 Self { derives, ..self }
73 }
74
75 /// Renames the fallback variant.
76 #[must_use]
77 pub fn with_other(self, other: &str) -> Self {
78 Self { other: String::from(other), ..self }
79 }
80
81 /// Sets the documentation.
82 #[must_use]
83 pub fn with_doc(self, doc: &str) -> Self {
84 Self { doc: Some(String::from(doc)), ..self }
85 }
86}
87
88/// One arm of a [`DispatchDef`].
89#[derive(Debug, Clone, PartialEq, Eq)]
90#[non_exhaustive]
91pub struct DispatchArm {
92 /// The id that selects this arm.
93 pub id: i64,
94 /// The variant name.
95 pub name: String,
96 /// The body type, which implements `Layout`.
97 pub ty: String,
98 /// Documentation.
99 pub doc: Option<String>,
100}
101
102impl DispatchArm {
103 /// `#[value(id)] name(ty)`, undocumented.
104 #[must_use]
105 pub fn new(id: i64, name: &str, ty: &str) -> Self {
106 Self { id, name: String::from(name), ty: String::from(ty), doc: None }
107 }
108
109 /// Sets the documentation.
110 #[must_use]
111 pub fn with_doc(self, doc: &str) -> Self {
112 Self { doc: Some(String::from(doc)), ..self }
113 }
114}