Skip to main content

ifc_author/
error.rs

1//! Why a construction attempt was refused.
2//!
3//! Every variant names the entity and, where meaningful, the attribute, because
4//! an authoring failure is a programming error in the *calling* application and
5//! the message is the whole diagnostic.
6
7use std::fmt;
8
9use ifc_model::EntityId;
10
11/// A refused construction.
12#[derive(Debug, Clone, PartialEq, Eq)]
13#[non_exhaustive]
14pub enum AuthorError {
15    /// The requested entity is not present in the model snapshot.
16    MissingEntity {
17        /// The missing entity id.
18        id: EntityId,
19    },
20    /// The schema does not declare this entity type.
21    ///
22    /// Reported rather than ignored: silently accepting an unknown type is how
23    /// a typo becomes a file other tools reject.
24    UnknownEntity {
25        /// The requested type name.
26        entity: String,
27    },
28    /// The schema declares the entity, but not this attribute.
29    UnknownAttribute {
30        /// The entity being built.
31        entity: String,
32        /// The attribute name the caller supplied.
33        attribute: String,
34        /// Attribute names the schema does declare, in positional order.
35        known: Vec<String>,
36    },
37    /// A required (non-`OPTIONAL`) attribute was never set.
38    MissingRequired {
39        /// The entity being built.
40        entity: String,
41        /// The unset attribute.
42        attribute: String,
43    },
44    /// The same attribute was set twice.
45    ///
46    /// A silent overwrite hides a copy-paste error in the caller.
47    DuplicateAttribute {
48        /// The entity being built.
49        entity: String,
50        /// The attribute set more than once.
51        attribute: String,
52    },
53    /// The value does not match the attribute's declared type.
54    TypeMismatch {
55        /// The entity being built.
56        entity: String,
57        /// The attribute that was set.
58        attribute: String,
59        /// The type the schema declares.
60        expected: String,
61        /// What the supplied value actually was.
62        found: String,
63    },
64    /// An enumeration constant that is not a member of the declared
65    /// enumeration, for example `.PIERCAP.` on an IFC4 `IfcBeam`.
66    NotEnumerationMember {
67        /// The entity being built or edited.
68        entity: String,
69        /// The attribute that was set.
70        attribute: String,
71        /// The enumeration(s) the declared type resolves to.
72        enumeration: String,
73        /// The rejected constant, without the surrounding dots.
74        constant: String,
75        /// The members the declared release allows.
76        allowed: Vec<String>,
77    },
78    /// A scalar was supplied where the schema declares an aggregate, or vice
79    /// versa.
80    AggregateMismatch {
81        /// The entity being built.
82        entity: String,
83        /// The attribute that was set.
84        attribute: String,
85        /// Whether the schema declares an aggregate.
86        expected_aggregate: bool,
87    },
88    /// A GlobalId was supplied that is not a valid 22-character IFC GUID.
89    InvalidGlobalId {
90        /// The entity being built.
91        entity: String,
92        /// The rejected text.
93        found: String,
94    },
95    /// A slot the schema derives for this entity was given a value.
96    ///
97    /// A subtype can redeclare an inherited attribute as `DERIVE`d, as
98    /// `IfcSIUnit` does with `Dimensions`. Part 21 writes such a slot as `*`:
99    /// neither a value nor `$` is valid there. The builder writes `*` itself
100    /// when the slot is left unset.
101    DerivedAttribute {
102        /// The entity being built or edited.
103        entity: String,
104        /// The derived attribute.
105        attribute: String,
106        /// What was supplied instead of `*`.
107        found: String,
108    },
109    /// `*` was supplied for a slot the schema does not derive for this entity.
110    NotDerived {
111        /// The entity being built or edited.
112        entity: String,
113        /// The attribute that was set.
114        attribute: String,
115    },
116    /// An existing entity does not have the arity declared by the schema.
117    ArityMismatch {
118        /// The entity being edited.
119        entity: String,
120        /// Number of attributes declared by the schema.
121        expected: usize,
122        /// Number of attributes present in the model.
123        found: usize,
124    },
125    /// A value of the declared type, written in the form ISO 10303-21 does
126    /// not use for it.
127    ///
128    /// A typed parameter (`IFCAREAMEASURE(12.5)`) is written exactly where the
129    /// declared type is a SELECT, which needs it to say which member the
130    /// value is (§12.1.8); everywhere else the bare value is written
131    /// (§12.1.6, §12.1.7). A wrapper naming a different type than the one
132    /// declared is a [`TypeMismatch`](Self::TypeMismatch) instead.
133    ValueForm {
134        /// The entity being built or edited.
135        entity: String,
136        /// The attribute that was set.
137        attribute: String,
138        /// The declared type, or the element type of a declared aggregate.
139        declared: String,
140        /// Whether the declared type requires the typed form: `true` for a
141        /// bare value in a SELECT slot, `false` for a wrapper elsewhere.
142        typed_required: bool,
143        /// What the supplied value actually was.
144        found: String,
145    },
146}
147
148impl fmt::Display for AuthorError {
149    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
150        match self {
151            Self::MissingEntity { id } => write!(f, "model has no entity `{id}`"),
152            Self::UnknownEntity { entity } => {
153                write!(f, "schema does not declare entity `{entity}`")
154            }
155            Self::UnknownAttribute {
156                entity,
157                attribute,
158                known,
159            } => write!(
160                f,
161                "`{entity}` has no attribute `{attribute}`; declared: {}",
162                known.join(", ")
163            ),
164            Self::MissingRequired { entity, attribute } => write!(
165                f,
166                "`{entity}` requires attribute `{attribute}`, which was not set"
167            ),
168            Self::DuplicateAttribute { entity, attribute } => {
169                write!(f, "`{entity}` attribute `{attribute}` was set twice")
170            }
171            Self::TypeMismatch {
172                entity,
173                attribute,
174                expected,
175                found,
176            } => write!(
177                f,
178                "`{entity}.{attribute}` expects {expected}, found {found}"
179            ),
180            Self::NotEnumerationMember {
181                entity,
182                attribute,
183                enumeration,
184                constant,
185                allowed,
186            } => write!(
187                f,
188                "`{entity}.{attribute}`: `.{constant}.` is not a member of {enumeration}; \
189                 allowed: {}",
190                allowed.join(", ")
191            ),
192            Self::ValueForm {
193                entity,
194                attribute,
195                declared,
196                typed_required: true,
197                found,
198            } => write!(
199                f,
200                "`{entity}.{attribute}` is declared {declared}, a SELECT, so a value \
201                 must be written as a typed parameter naming its type; found {found}"
202            ),
203            Self::ValueForm {
204                entity,
205                attribute,
206                declared,
207                typed_required: false,
208                found,
209            } => write!(
210                f,
211                "`{entity}.{attribute}` is declared {declared}, which is not a SELECT, \
212                 so its value is written bare; found {found}"
213            ),
214            Self::AggregateMismatch {
215                entity,
216                attribute,
217                expected_aggregate,
218            } => {
219                let (want, got) = if *expected_aggregate {
220                    ("an aggregate", "a scalar")
221                } else {
222                    ("a scalar", "an aggregate")
223                };
224                write!(f, "`{entity}.{attribute}` expects {want}, found {got}")
225            }
226            Self::InvalidGlobalId { entity, found } => write!(
227                f,
228                "`{entity}.GlobalId` must be a 22-character IFC GUID, found `{found}`"
229            ),
230            Self::DerivedAttribute {
231                entity,
232                attribute,
233                found,
234            } => write!(
235                f,
236                "`{entity}.{attribute}` is derived by the schema and must be written `*`, found {found}"
237            ),
238            Self::NotDerived { entity, attribute } => write!(
239                f,
240                "`{entity}.{attribute}` is not derived by the schema, so it cannot be written `*`"
241            ),
242            Self::ArityMismatch {
243                entity,
244                expected,
245                found,
246            } => write!(
247                f,
248                "`{entity}` declares {expected} attributes, but the model contains {found}"
249            ),
250        }
251    }
252}
253
254impl std::error::Error for AuthorError {}
255
256/// The result of a construction attempt.
257pub type AuthorResult<T> = Result<T, AuthorError>;