nsi_intermediate/error.rs
1//! The error a recording call can fail with.
2
3use core::fmt;
4
5/// Why an ɴsɪ call could not be recorded.
6///
7/// One type across every [`Nsi`] method, so a consumer matches on one
8/// thing. It is `#[non_exhaustive]`: ɴsɪ has more rules than this crate
9/// enforces yet, and enforcing another one should not be a breaking
10/// change.
11///
12/// [`Nsi`]: nsi_trait::Nsi
13#[derive(Debug, Clone, PartialEq, Eq, Hash)]
14#[non_exhaustive]
15pub enum RecordError {
16 /// A call tried to create or delete one of ɴsɪ's reserved nodes.
17 ///
18 /// ɴsɪ: "it is not possible to delete the root or the global node",
19 /// and they "don't need to be created" because they already exist.
20 Reserved {
21 /// The reserved handle.
22 handle: String,
23 },
24 /// A motion sample was given a time that is not a finite number.
25 ///
26 /// 3Delight answers `E6026 invalid time`. Storing one produced a
27 /// `motion_times` a backend could not iterate meaningfully.
28 InvalidTime {
29 /// The node the sample was set on.
30 handle: String,
31 },
32 /// A `connect` or `disconnect` named a handle that does not exist.
33 ///
34 /// ɴsɪ: "the nodes on which the connection is performed must
35 /// exist." Recording the edge anyway builds a graph whose nodes are
36 /// missing, and resolution then answers for it as though it were
37 /// real.
38 UnknownHandle {
39 /// The handle that was never created.
40 handle: String,
41 },
42 /// `create` was called again for an existing handle with a
43 /// different node type.
44 ///
45 /// ɴsɪ: "the function does nothing if all other parameters match the
46 /// call which created that node. Otherwise, it emits an error."
47 /// Overwriting the type silently would leave the scene describing
48 /// something no consumer asked for.
49 TypeMismatch {
50 /// The handle that already exists.
51 handle: String,
52 /// The type it was created with.
53 existing: String,
54 /// The type this call asked for.
55 requested: String,
56 },
57}
58
59impl fmt::Display for RecordError {
60 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61 match self {
62 Self::Reserved { handle } => write!(
63 f,
64 "ɴsɪ node {handle:?} is reserved: it exists already and \
65 cannot be created or deleted"
66 ),
67 Self::InvalidTime { handle } => write!(
68 f,
69 "ɴsɪ motion sample on node {handle:?} has a time that is \
70 not a finite number"
71 ),
72 Self::UnknownHandle { handle } => write!(
73 f,
74 "ɴsɪ connection names node {handle:?}, which does not \
75 exist; the nodes a connection is made on must be \
76 created first"
77 ),
78 Self::TypeMismatch {
79 handle,
80 existing,
81 requested,
82 } => write!(
83 f,
84 "ɴsɪ node {handle:?} already exists as {existing:?}; \
85 re-creating it as {requested:?} is an error, not an \
86 overwrite"
87 ),
88 }
89 }
90}
91
92impl core::error::Error for RecordError {}