Skip to main content

matter_model/
schema.rs

1//! The shapes of the generated tables.
2
3use crate::names_match;
4
5/// A cluster: its attributes, commands and events.
6#[derive(Debug)]
7pub struct Cluster {
8    /// Cluster id.
9    pub id: u32,
10    /// IDL name, `UpperCamelCase`.
11    pub name: &'static str,
12    /// Cluster revision the IDL describes.
13    pub revision: u16,
14    /// Attributes, sorted by id, global attributes included.
15    pub attributes: &'static [Attribute],
16    /// Commands the server accepts, sorted by id.
17    pub commands: &'static [Command],
18    /// Events, sorted by id.
19    pub events: &'static [Event],
20    /// Response commands the server sends, by command id.
21    pub responses: &'static [(u32, &'static StructDef)],
22}
23
24impl Cluster {
25    /// The attribute with `id`.
26    pub fn attribute(&self, id: u32) -> Option<&'static Attribute> {
27        self.attributes
28            .binary_search_by_key(&id, |a| a.id)
29            .ok()
30            .map(|i| &self.attributes[i])
31    }
32
33    /// The attribute named `name` (case and `_` ignored).
34    pub fn attribute_by_name(&self, name: &str) -> Option<&'static Attribute> {
35        self.attributes.iter().find(|a| names_match(a.name, name))
36    }
37
38    /// The command with `id`.
39    pub fn command(&self, id: u32) -> Option<&'static Command> {
40        self.commands
41            .binary_search_by_key(&id, |c| c.id)
42            .ok()
43            .map(|i| &self.commands[i])
44    }
45
46    /// The command named `name` (case and `_` ignored).
47    pub fn command_by_name(&self, name: &str) -> Option<&'static Command> {
48        self.commands.iter().find(|c| names_match(c.name, name))
49    }
50
51    /// The event with `id`.
52    pub fn event(&self, id: u32) -> Option<&'static Event> {
53        self.events
54            .binary_search_by_key(&id, |e| e.id)
55            .ok()
56            .map(|i| &self.events[i])
57    }
58
59    /// The event named `name` (case and `_` ignored).
60    pub fn event_by_name(&self, name: &str) -> Option<&'static Event> {
61        self.events.iter().find(|e| names_match(e.name, name))
62    }
63
64    /// The structure of the response command `id` the server sends.
65    pub fn response(&self, id: u32) -> Option<&'static StructDef> {
66        self.responses
67            .iter()
68            .find(|(rid, _)| *rid == id)
69            .map(|(_, s)| *s)
70    }
71}
72
73/// An attribute of a cluster.
74#[derive(Debug)]
75pub struct Attribute {
76    /// Attribute id.
77    pub id: u32,
78    /// IDL name, `lowerCamelCase`.
79    pub name: &'static str,
80    /// Value type (of each element, for a list).
81    pub ty: Type,
82    /// Whether the value is a list of `ty`.
83    pub list: bool,
84    /// Whether the value can be null.
85    pub nullable: bool,
86    /// Whether a server may leave the attribute out.
87    pub optional: bool,
88    /// Whether a client may write it.
89    pub writable: bool,
90    /// Whether a write must be timed.
91    pub timed_write: bool,
92}
93
94impl Attribute {
95    /// The attribute's shape, for conversion.
96    pub const fn shape(&self) -> Shape {
97        Shape {
98            ty: Some(self.ty),
99            list: self.list,
100        }
101    }
102}
103
104/// A command a server accepts.
105#[derive(Debug)]
106pub struct Command {
107    /// Command id.
108    pub id: u32,
109    /// IDL name, `UpperCamelCase`.
110    pub name: &'static str,
111    /// The request's fields, or `None` for a command without any.
112    pub request: Option<&'static StructDef>,
113    /// The response command's fields, or `None` when the server answers with
114    /// a status only.
115    pub response: Option<&'static StructDef>,
116    /// Whether the command must be invoked in a timed interaction.
117    pub timed: bool,
118}
119
120/// An event of a cluster.
121#[derive(Debug)]
122pub struct Event {
123    /// Event id.
124    pub id: u32,
125    /// IDL name, `UpperCamelCase`.
126    pub name: &'static str,
127    /// The event's payload: a structure of its fields.
128    pub payload: &'static StructDef,
129}
130
131impl Event {
132    /// The payload's shape, for conversion.
133    pub const fn shape(&self) -> Shape {
134        Shape {
135            ty: Some(Type::Struct(self.payload)),
136            list: false,
137        }
138    }
139}
140
141/// A field of a structure, a command or an event.
142#[derive(Debug)]
143pub struct Field {
144    /// Context tag.
145    pub tag: u8,
146    /// IDL name, `lowerCamelCase`.
147    pub name: &'static str,
148    /// Value type (of each element, for a list).
149    pub ty: Type,
150    /// Whether the value is a list of `ty`.
151    pub list: bool,
152    /// Whether the value can be null.
153    pub nullable: bool,
154    /// Whether the field can be left out.
155    pub optional: bool,
156}
157
158impl Field {
159    /// The field's shape, for conversion.
160    pub const fn shape(&self) -> Shape {
161        Shape {
162            ty: Some(self.ty),
163            list: self.list,
164        }
165    }
166}
167
168/// A structure.
169#[derive(Debug)]
170pub struct StructDef {
171    /// IDL name.
172    pub name: &'static str,
173    /// Fields, sorted by tag.
174    pub fields: &'static [Field],
175    /// Whether the structure is fabric-scoped.
176    pub fabric_scoped: bool,
177}
178
179impl StructDef {
180    /// The field with context tag `tag`.
181    pub fn field(&self, tag: u8) -> Option<&'static Field> {
182        self.fields.iter().find(|f| f.tag == tag)
183    }
184
185    /// The field named `name` (case and `_` ignored).
186    pub fn field_by_name(&self, name: &str) -> Option<&'static Field> {
187        self.fields.iter().find(|f| names_match(f.name, name))
188    }
189
190    /// The structure's shape, for conversion.
191    pub fn shape(&'static self) -> Shape {
192        Shape {
193            ty: Some(Type::Struct(self)),
194            list: false,
195        }
196    }
197}
198
199/// An enumeration.
200#[derive(Debug)]
201pub struct EnumDef {
202    /// IDL name.
203    pub name: &'static str,
204    /// Values and their names.
205    pub values: &'static [(u64, &'static str)],
206}
207
208impl EnumDef {
209    /// The name of `value`.
210    pub fn name_of(&self, value: u64) -> Option<&'static str> {
211        self.values
212            .iter()
213            .find(|(v, _)| *v == value)
214            .map(|(_, n)| *n)
215    }
216
217    /// The value named `name` (case and `_` ignored, with or without a `k`
218    /// prefix as the IDL writes them).
219    pub fn value_of(&self, name: &str) -> Option<u64> {
220        self.values
221            .iter()
222            .find(|(_, n)| {
223                names_match(n, name) || n.strip_prefix('k').is_some_and(|n| names_match(n, name))
224            })
225            .map(|(v, _)| *v)
226    }
227}
228
229/// A bitmap.
230#[derive(Debug)]
231pub struct BitmapDef {
232    /// IDL name.
233    pub name: &'static str,
234    /// Bit masks and their names.
235    pub bits: &'static [(u64, &'static str)],
236}
237
238/// The type of a value, as far as JSON conversion needs it.
239#[derive(Debug, Clone, Copy)]
240pub enum Type {
241    /// `boolean`.
242    Bool,
243    /// An unsigned integer of any width, or a semantic type over one.
244    Uint,
245    /// A signed integer of any width, or a semantic type over one.
246    Int,
247    /// `single`.
248    Float,
249    /// `double`.
250    Double,
251    /// A UTF-8 string.
252    String,
253    /// An octet string; hex in JSON.
254    Octets,
255    /// An enumeration: a number, or its name when encoding.
256    Enum(&'static EnumDef),
257    /// A bitmap: a number.
258    Bitmap(&'static BitmapDef),
259    /// A structure: an object keyed by field name.
260    Struct(&'static StructDef),
261    /// A type the tables do not know; converted by its TLV type.
262    Unknown(&'static str),
263}
264
265/// What a value is expected to be: its type (if known) and whether it is a
266/// list of it.
267#[derive(Debug, Clone, Copy)]
268pub struct Shape {
269    /// The element type, if known.
270    pub ty: Option<Type>,
271    /// Whether the value is a list.
272    pub list: bool,
273}
274
275impl Shape {
276    /// A value of unknown shape, converted by its TLV or JSON type alone.
277    pub const ANY: Shape = Shape {
278        ty: None,
279        list: false,
280    };
281
282    /// A single value of `ty`.
283    pub const fn of(ty: Type) -> Shape {
284        Shape {
285            ty: Some(ty),
286            list: false,
287        }
288    }
289}