Skip to main content

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 {}