Skip to main content

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}