1//! # Generic builder type implementations
2//!
3//! This module contains [`FromEventsBuilder`] implementations for types from
4//! foreign libraries (such as the standard library).
5//!
6//! In order to not clutter the `xso` crate's main namespace, they are
7//! stashed away in a separate module.
8
9// Copyright (c) 2024 Jonas Schäfer <jonas@zombofant.net>
10//
11// This Source Code Form is subject to the terms of the Mozilla Public
12// License, v. 2.0. If a copy of the MPL was not distributed with this
13// file, You can obtain one at http://mozilla.org/MPL/2.0/.
14
15use crate::error::{Error, FromEventsError};
16use crate::{FromEventsBuilder, FromXml};
17
18/// Helper struct to construct an `Option<T>` from XML events.
19pub struct OptionBuilder<T: FromEventsBuilder>(T);
20
21impl<T: FromEventsBuilder> FromEventsBuilder for OptionBuilder<T> {
22 type Output = Option<T::Output>;
23
24 fn feed(&mut self, ev: rxml::Event) -> Result<Option<Self::Output>, Error> {
25 self.0.feed(ev).map(|ok| ok.map(|value| Some(value)))
26 }
27}
28
29/// Parsers `T` into `Some(.)`.
30///
31/// Note that this never generates `None`: The main use case is to allow
32/// external (i.e. without calling `from_events`) defaulting to `None` and
33/// for optional serialisation (the [`AsXml`][`crate::AsXml`] implementation
34/// on `Option<T>` emits nothing for `None`).
35impl<T: FromXml> FromXml for Option<T> {
36 type Builder = OptionBuilder<T::Builder>;
37
38 fn from_events(
39 name: rxml::QName,
40 attrs: rxml::AttrMap,
41 ) -> Result<Self::Builder, FromEventsError> {
42 Ok(OptionBuilder(T::from_events(name, attrs)?))
43 }
44}
45
46/// Helper struct to construct an `Box<T>` from XML events.
47pub struct BoxBuilder<T: FromEventsBuilder>(Box<T>);
48
49impl<T: FromEventsBuilder> FromEventsBuilder for BoxBuilder<T> {
50 type Output = Box<T::Output>;
51
52 fn feed(&mut self, ev: rxml::Event) -> Result<Option<Self::Output>, Error> {
53 self.0.feed(ev).map(|ok| ok.map(|value| Box::new(value)))
54 }
55}
56
57/// Parsers `T` into a `Box`.
58impl<T: FromXml> FromXml for Box<T> {
59 type Builder = BoxBuilder<T::Builder>;
60
61 fn from_events(
62 name: rxml::QName,
63 attrs: rxml::AttrMap,
64 ) -> Result<Self::Builder, FromEventsError> {
65 Ok(BoxBuilder(Box::new(T::from_events(name, attrs)?)))
66 }
67}
68
69#[derive(Debug)]
70enum FallibleBuilderInner<T: FromEventsBuilder, E> {
71 Processing { depth: usize, builder: T },
72 Failed { depth: usize, err: Option<E> },
73 Done,
74}
75
76/// Build a `Result<T, E>` from XML.
77///
78/// This builder, invoked generally via the [`FromXml`] implementation on
79/// `Result<T, E> where T: FromXml, E: From<Error>`, allows to fallably parse
80/// an XSO from XML.
81///
82/// If an error occurs while parsing the XSO, the remaining events which
83/// belong to that XSO are discarded. Once all events have been seen, the
84/// error is returned as `Err(.)` value.
85///
86/// If parsing succeeds, the parsed XSO is returned as `Ok(.)` value.
87#[derive(Debug)]
88pub struct FallibleBuilder<T: FromEventsBuilder, E>(FallibleBuilderInner<T, E>);
89
90impl<T: FromEventsBuilder, E: From<Error>> FromEventsBuilder for FallibleBuilder<T, E> {
91 type Output = Result<T::Output, E>;
92
93 fn feed(&mut self, ev: rxml::Event) -> Result<Option<Self::Output>, Error> {
94 match self.0 {
95 FallibleBuilderInner::Processing {
96 ref mut depth,
97 ref mut builder,
98 } => {
99 let new_depth = match ev {
100 rxml::Event::StartElement(..) => match depth.checked_add(1) {
101 // I *think* it is OK to return an err here
102 // instead of panicking. The reason is that anyone
103 // who intends to resume processing at the level
104 // of where we started to parse this thing in case
105 // of an error either has to:
106 // - Use this fallible implementation and rely on
107 // it capturing the error (which we don't in
108 // this case).
109 // - Or count the depth themselves, which will
110 // either fail in the same way, or they use a
111 // wider type (in which case it's ok).
112 None => {
113 self.0 = FallibleBuilderInner::Done;
114 return Err(Error::Other("maximum XML nesting depth exceeded"));
115 }
116 Some(v) => Some(v),
117 },
118 // In case of an element end, underflow means that we
119 // have reached the end of the XSO we wanted to process.
120 // We handle that case at the end of the outer match's
121 // body: Either we have returned a value then (good), or,
122 // if we reach the end there with a new_depth == None,
123 // something went horribly wrong (and we panic).
124 rxml::Event::EndElement(..) => depth.checked_sub(1),
125
126 // Text and XML declarations have no influence on parsing
127 // depth.
128 rxml::Event::XmlDeclaration(..) | rxml::Event::Text(..) => Some(*depth),
129 };
130
131 match builder.feed(ev) {
132 Ok(Some(v)) => {
133 self.0 = FallibleBuilderInner::Done;
134 return Ok(Some(Ok(v)));
135 }
136 Ok(None) => {
137 // continue processing in the next round.
138 }
139 Err(e) => {
140 // We are now officially failed ..
141 match new_depth {
142 // .. but we are not done yet, so enter the
143 // failure backtracking state.
144 Some(depth) => {
145 self.0 = FallibleBuilderInner::Failed {
146 depth,
147 err: Some(e.into()),
148 };
149 return Ok(None);
150 }
151 // .. and we are done with parsing, so we return
152 // the error as value.
153 None => {
154 self.0 = FallibleBuilderInner::Done;
155 return Ok(Some(Err(e.into())));
156 }
157 }
158 }
159 };
160
161 *depth = match new_depth {
162 Some(v) => v,
163 None => unreachable!("fallible parsing continued beyond end of element"),
164 };
165
166 // Need more events.
167 Ok(None)
168 }
169 FallibleBuilderInner::Failed {
170 ref mut depth,
171 ref mut err,
172 } => {
173 *depth = match ev {
174 rxml::Event::StartElement(..) => match depth.checked_add(1) {
175 // See above for error return rationale.
176 None => {
177 self.0 = FallibleBuilderInner::Done;
178 return Err(Error::Other("maximum XML nesting depth exceeded"));
179 }
180 Some(v) => v,
181 },
182 rxml::Event::EndElement(..) => match depth.checked_sub(1) {
183 Some(v) => v,
184 None => {
185 // We are officially done, return a value, switch
186 // states, and be done with it.
187 let err = err.take().expect("fallible parsing somehow lost its error");
188 self.0 = FallibleBuilderInner::Done;
189 return Ok(Some(Err(err)));
190 }
191 },
192
193 // Text and XML declarations have no influence on parsing
194 // depth.
195 rxml::Event::XmlDeclaration(..) | rxml::Event::Text(..) => *depth,
196 };
197
198 // Need more events
199 Ok(None)
200 }
201 FallibleBuilderInner::Done => {
202 panic!("FromEventsBuilder called after it returned a value")
203 }
204 }
205 }
206}
207
208/// Parsers `T` fallibly. See [`FallibleBuilder`] for details.
209impl<T: FromXml, E: From<Error>> FromXml for Result<T, E> {
210 type Builder = FallibleBuilder<T::Builder, E>;
211
212 fn from_events(
213 name: rxml::QName,
214 attrs: rxml::AttrMap,
215 ) -> Result<Self::Builder, FromEventsError> {
216 match T::from_events(name, attrs) {
217 Ok(builder) => Ok(FallibleBuilder(FallibleBuilderInner::Processing {
218 depth: 0,
219 builder,
220 })),
221 Err(FromEventsError::Mismatch { name, attrs }) => {
222 Err(FromEventsError::Mismatch { name, attrs })
223 }
224 Err(FromEventsError::Invalid(e)) => Ok(FallibleBuilder(FallibleBuilderInner::Failed {
225 depth: 0,
226 err: Some(e.into()),
227 })),
228 }
229 }
230}
231
232#[cfg(test)]
233mod tests {
234 use super::*;
235
236 use rxml::{parser::EventMetrics, Event, Namespace, NcName};
237
238 macro_rules! null_builder {
239 ($name:ident for $output:ident) => {
240 #[derive(Debug)]
241 enum $name {}
242
243 impl FromEventsBuilder for $name {
244 type Output = $output;
245
246 fn feed(&mut self, _: Event) -> Result<Option<Self::Output>, Error> {
247 unreachable!();
248 }
249 }
250 };
251 }
252
253 null_builder!(AlwaysMismatchBuilder for AlwaysMismatch);
254 null_builder!(InitialErrorBuilder for InitialError);
255
256 #[derive(Debug)]
257 struct AlwaysMismatch;
258
259 impl FromXml for AlwaysMismatch {
260 type Builder = AlwaysMismatchBuilder;
261
262 fn from_events(
263 name: rxml::QName,
264 attrs: rxml::AttrMap,
265 ) -> Result<Self::Builder, FromEventsError> {
266 Err(FromEventsError::Mismatch { name, attrs })
267 }
268 }
269
270 #[derive(Debug)]
271 struct InitialError;
272
273 impl FromXml for InitialError {
274 type Builder = InitialErrorBuilder;
275
276 fn from_events(_: rxml::QName, _: rxml::AttrMap) -> Result<Self::Builder, FromEventsError> {
277 Err(FromEventsError::Invalid(Error::Other("some error")))
278 }
279 }
280
281 #[derive(Debug)]
282 struct FailOnContentBuilder;
283
284 impl FromEventsBuilder for FailOnContentBuilder {
285 type Output = FailOnContent;
286
287 fn feed(&mut self, _: Event) -> Result<Option<Self::Output>, Error> {
288 Err(Error::Other("content error"))
289 }
290 }
291
292 #[derive(Debug)]
293 struct FailOnContent;
294
295 impl FromXml for FailOnContent {
296 type Builder = FailOnContentBuilder;
297
298 fn from_events(_: rxml::QName, _: rxml::AttrMap) -> Result<Self::Builder, FromEventsError> {
299 Ok(FailOnContentBuilder)
300 }
301 }
302
303 fn qname() -> rxml::QName {
304 (Namespace::NONE, NcName::try_from("test").unwrap())
305 }
306
307 fn attrs() -> rxml::AttrMap {
308 rxml::AttrMap::new()
309 }
310
311 #[test]
312 fn fallible_builder_missmatch_passthrough() {
313 match Result::<AlwaysMismatch, Error>::from_events(qname(), attrs()) {
314 Err(FromEventsError::Mismatch { .. }) => (),
315 other => panic!("unexpected result: {:?}", other),
316 }
317 }
318
319 #[test]
320 fn fallible_builder_initial_error_capture() {
321 let mut builder = match Result::<InitialError, Error>::from_events(qname(), attrs()) {
322 Ok(v) => v,
323 other => panic!("unexpected result: {:?}", other),
324 };
325 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
326 Ok(None) => (),
327 other => panic!("unexpected result: {:?}", other),
328 };
329 match builder.feed(Event::EndElement(EventMetrics::zero())) {
330 Ok(Some(Err(Error::Other("some error")))) => (),
331 other => panic!("unexpected result: {:?}", other),
332 };
333 }
334
335 #[test]
336 fn fallible_builder_initial_error_capture_allows_nested_stuff() {
337 let mut builder = match Result::<InitialError, Error>::from_events(qname(), attrs()) {
338 Ok(v) => v,
339 other => panic!("unexpected result: {:?}", other),
340 };
341 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
342 Ok(None) => (),
343 other => panic!("unexpected result: {:?}", other),
344 };
345 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
346 Ok(None) => (),
347 other => panic!("unexpected result: {:?}", other),
348 };
349 match builder.feed(Event::EndElement(EventMetrics::zero())) {
350 Ok(None) => (),
351 other => panic!("unexpected result: {:?}", other),
352 };
353 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
354 Ok(None) => (),
355 other => panic!("unexpected result: {:?}", other),
356 };
357 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
358 Ok(None) => (),
359 other => panic!("unexpected result: {:?}", other),
360 };
361 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
362 Ok(None) => (),
363 other => panic!("unexpected result: {:?}", other),
364 };
365 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
366 Ok(None) => (),
367 other => panic!("unexpected result: {:?}", other),
368 };
369 match builder.feed(Event::EndElement(EventMetrics::zero())) {
370 Ok(None) => (),
371 other => panic!("unexpected result: {:?}", other),
372 };
373 match builder.feed(Event::EndElement(EventMetrics::zero())) {
374 Ok(None) => (),
375 other => panic!("unexpected result: {:?}", other),
376 };
377 match builder.feed(Event::EndElement(EventMetrics::zero())) {
378 Ok(Some(Err(Error::Other("some error")))) => (),
379 other => panic!("unexpected result: {:?}", other),
380 };
381 }
382
383 #[test]
384 fn fallible_builder_content_error_capture() {
385 let mut builder = match Result::<FailOnContent, Error>::from_events(qname(), attrs()) {
386 Ok(v) => v,
387 other => panic!("unexpected result: {:?}", other),
388 };
389 match builder.feed(Event::EndElement(EventMetrics::zero())) {
390 Ok(Some(Err(Error::Other("content error")))) => (),
391 other => panic!("unexpected result: {:?}", other),
392 };
393 }
394
395 #[test]
396 fn fallible_builder_content_error_capture_with_more_content() {
397 let mut builder = match Result::<FailOnContent, Error>::from_events(qname(), attrs()) {
398 Ok(v) => v,
399 other => panic!("unexpected result: {:?}", other),
400 };
401 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
402 Ok(None) => (),
403 other => panic!("unexpected result: {:?}", other),
404 };
405 match builder.feed(Event::EndElement(EventMetrics::zero())) {
406 Ok(Some(Err(Error::Other("content error")))) => (),
407 other => panic!("unexpected result: {:?}", other),
408 };
409 }
410
411 #[test]
412 fn fallible_builder_content_error_capture_with_nested_content() {
413 let mut builder = match Result::<FailOnContent, Error>::from_events(qname(), attrs()) {
414 Ok(v) => v,
415 other => panic!("unexpected result: {:?}", other),
416 };
417 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
418 Ok(None) => (),
419 other => panic!("unexpected result: {:?}", other),
420 };
421 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
422 Ok(None) => (),
423 other => panic!("unexpected result: {:?}", other),
424 };
425 match builder.feed(Event::EndElement(EventMetrics::zero())) {
426 Ok(None) => (),
427 other => panic!("unexpected result: {:?}", other),
428 };
429 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
430 Ok(None) => (),
431 other => panic!("unexpected result: {:?}", other),
432 };
433 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
434 Ok(None) => (),
435 other => panic!("unexpected result: {:?}", other),
436 };
437 match builder.feed(Event::StartElement(EventMetrics::zero(), qname(), attrs())) {
438 Ok(None) => (),
439 other => panic!("unexpected result: {:?}", other),
440 };
441 match builder.feed(Event::Text(EventMetrics::zero(), "hello world!".to_owned())) {
442 Ok(None) => (),
443 other => panic!("unexpected result: {:?}", other),
444 };
445 match builder.feed(Event::EndElement(EventMetrics::zero())) {
446 Ok(None) => (),
447 other => panic!("unexpected result: {:?}", other),
448 };
449 match builder.feed(Event::EndElement(EventMetrics::zero())) {
450 Ok(None) => (),
451 other => panic!("unexpected result: {:?}", other),
452 };
453 match builder.feed(Event::EndElement(EventMetrics::zero())) {
454 Ok(Some(Err(Error::Other("content error")))) => (),
455 other => panic!("unexpected result: {:?}", other),
456 };
457 }
458}