quick_xml/errors.rs
1//! Error management module
2
3use crate::encoding::Decoder;
4use crate::escape::EscapeError;
5use crate::events::attributes::AttrError;
6use crate::name::QName;
7use crate::utils::write_byte_string;
8use std::fmt;
9use std::io::Error as IoError;
10use std::str::Utf8Error;
11use std::string::FromUtf8Error;
12use std::sync::Arc;
13
14/// An error returned if parsed document does not correspond to the XML grammar,
15/// for example, a tag opened by `<` not closed with `>`. This error does not
16/// represent invalid XML constructs, for example, tags `<>` and `</>` a well-formed
17/// from syntax point-of-view.
18#[derive(Copy, Clone, Debug, PartialEq, Eq)]
19pub enum SyntaxError {
20 /// The parser started to parse `<!`, but the input ended before it can recognize
21 /// anything.
22 InvalidBangMarkup,
23 /// The parser started to parse processing instruction or XML declaration (`<?`),
24 /// but the input ended before the `?>` sequence was found.
25 UnclosedPIOrXmlDecl,
26 /// The parser started to parse comment (`<!--`) content, but the input ended
27 /// before the `-->` sequence was found.
28 UnclosedComment,
29 /// The parser started to parse DTD (`<!DOCTYPE`) content, but the input ended
30 /// before the closing `>` character was found.
31 UnclosedDoctype,
32 /// The parser started to parse `<![CDATA[` content, but the input ended
33 /// before the `]]>` sequence was found.
34 UnclosedCData,
35 /// The parser started to parse tag content, but the input ended
36 /// before the closing `>` character was found.
37 UnclosedTag,
38}
39
40impl fmt::Display for SyntaxError {
41 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
42 match self {
43 Self::InvalidBangMarkup => f.write_str("unknown or missed symbol in markup"),
44 Self::UnclosedPIOrXmlDecl => {
45 f.write_str("processing instruction or xml declaration not closed: `?>` not found before end of input")
46 }
47 Self::UnclosedComment => {
48 f.write_str("comment not closed: `-->` not found before end of input")
49 }
50 Self::UnclosedDoctype => {
51 f.write_str("DOCTYPE not closed: `>` not found before end of input")
52 }
53 Self::UnclosedCData => {
54 f.write_str("CDATA not closed: `]]>` not found before end of input")
55 }
56 Self::UnclosedTag => f.write_str("tag not closed: `>` not found before end of input"),
57 }
58 }
59}
60
61impl std::error::Error for SyntaxError {}
62
63////////////////////////////////////////////////////////////////////////////////////////////////////
64
65/// An error returned if parsed document is not [well-formed], for example,
66/// an opened tag is not closed before end of input.
67///
68/// Those errors are not fatal: after encountering an error you can continue
69/// parsing the document.
70///
71/// [well-formed]: https://www.w3.org/TR/xml11/#dt-wellformed
72#[derive(Clone, Debug, PartialEq, Eq)]
73pub enum IllFormedError {
74 /// A `version` attribute was not found in an XML declaration or is not the
75 /// first attribute.
76 ///
77 /// According to the [specification], the XML declaration (`<?xml ?>`) MUST contain
78 /// a `version` attribute and it MUST be the first attribute. This error indicates,
79 /// that the declaration does not contain attributes at all (if contains `None`)
80 /// or either `version` attribute is not present or not the first attribute in
81 /// the declaration. In the last case it contains the name of the found attribute.
82 ///
83 /// [specification]: https://www.w3.org/TR/xml11/#sec-prolog-dtd
84 MissingDeclVersion(Option<String>),
85 /// A document type definition (DTD) does not contain a name of a root element.
86 ///
87 /// According to the [specification], document type definition (`<!DOCTYPE foo>`)
88 /// MUST contain a name which defines a document type (`foo`). If that name
89 /// is missed, this error is returned.
90 ///
91 /// [specification]: https://www.w3.org/TR/xml11/#NT-doctypedecl
92 MissingDoctypeName,
93 /// The end tag was not found during reading of a sub-tree of elements due to
94 /// encountering an EOF from the underlying reader. This error is returned from
95 /// [`Reader::read_to_end`].
96 ///
97 /// [`Reader::read_to_end`]: crate::reader::Reader::read_to_end
98 MissingEndTag(String),
99 /// The specified end tag was encountered without corresponding open tag at the
100 /// same level of hierarchy
101 UnmatchedEndTag(String),
102 /// The specified end tag does not match the start tag at that nesting level.
103 MismatchedEndTag {
104 /// Name of open tag, that is expected to be closed
105 expected: String,
106 /// Name of actually closed tag
107 found: String,
108 },
109 /// A comment contains forbidden double-hyphen (`--`) sequence inside.
110 ///
111 /// According to the [specification], for compatibility, comments MUST NOT contain
112 /// double-hyphen (`--`) sequence, in particular, they cannot end by `--->`.
113 ///
114 /// The quick-xml by default does not check that, because this restriction is
115 /// mostly artificial, but you can enable it in the [configuration].
116 ///
117 /// [specification]: https://www.w3.org/TR/xml11/#sec-comments
118 /// [configuration]: crate::reader::Config::check_comments
119 DoubleHyphenInComment,
120}
121
122impl fmt::Display for IllFormedError {
123 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
124 match self {
125 Self::MissingDeclVersion(None) => {
126 write!(f, "an XML declaration does not contain `version` attribute")
127 }
128 Self::MissingDeclVersion(Some(attr)) => {
129 write!(f, "an XML declaration must start with `version` attribute, but in starts with `{}`", attr)
130 }
131 Self::MissingDoctypeName => write!(
132 f,
133 "`<!DOCTYPE>` declaration does not contain a name of a document type"
134 ),
135 Self::MissingEndTag(tag) => write!(
136 f,
137 "start tag not closed: `</{}>` not found before end of input",
138 tag,
139 ),
140 Self::UnmatchedEndTag(tag) => {
141 write!(f, "close tag `</{}>` does not match any open tag", tag)
142 }
143 Self::MismatchedEndTag { expected, found } => write!(
144 f,
145 "expected `</{}>`, but `</{}>` was found",
146 expected, found,
147 ),
148 Self::DoubleHyphenInComment => {
149 write!(f, "forbidden string `--` was found in a comment")
150 }
151 }
152 }
153}
154
155impl std::error::Error for IllFormedError {}
156
157////////////////////////////////////////////////////////////////////////////////////////////////////
158
159/// The error type used by this crate.
160#[derive(Clone, Debug)]
161pub enum Error {
162 /// XML document cannot be read from or written to underlying source.
163 ///
164 /// Contains the reference-counted I/O error to make the error type `Clone`able.
165 Io(Arc<IoError>),
166 /// The document does not corresponds to the XML grammar.
167 Syntax(SyntaxError),
168 /// The document is not [well-formed](https://www.w3.org/TR/xml11/#dt-wellformed).
169 IllFormed(IllFormedError),
170 /// Input decoding error. If [`encoding`] feature is disabled, contains `None`,
171 /// otherwise contains the UTF-8 decoding error
172 ///
173 /// [`encoding`]: index.html#encoding
174 NonDecodable(Option<Utf8Error>),
175 /// Attribute parsing error
176 InvalidAttr(AttrError),
177 /// Escape error
178 EscapeError(EscapeError),
179 /// Specified namespace prefix is unknown, cannot resolve namespace for it
180 UnknownPrefix(Vec<u8>),
181 /// Error for when a reserved namespace is set incorrectly.
182 ///
183 /// This error returned in following cases:
184 /// - the XML document attempts to bind `xml` prefix to something other than
185 /// `http://www.w3.org/XML/1998/namespace`
186 /// - the XML document attempts to bind `xmlns` prefix
187 /// - the XML document attempts to bind some prefix (except `xml`) to
188 /// `http://www.w3.org/XML/1998/namespace`
189 /// - the XML document attempts to bind some prefix to
190 /// `http://www.w3.org/2000/xmlns/`
191 InvalidPrefixBind {
192 /// The prefix that is tried to be bound
193 prefix: Vec<u8>,
194 /// Namespace to which prefix tried to be bound
195 namespace: Vec<u8>,
196 },
197}
198
199impl Error {
200 pub(crate) fn missed_end(name: QName, decoder: Decoder) -> Self {
201 match decoder.decode(name.as_ref()) {
202 Ok(name) => IllFormedError::MissingEndTag(name.into()).into(),
203 Err(err) => err.into(),
204 }
205 }
206}
207
208impl From<IoError> for Error {
209 /// Creates a new `Error::Io` from the given error
210 #[inline]
211 fn from(error: IoError) -> Error {
212 Error::Io(Arc::new(error))
213 }
214}
215
216impl From<SyntaxError> for Error {
217 /// Creates a new `Error::Syntax` from the given error
218 #[inline]
219 fn from(error: SyntaxError) -> Self {
220 Self::Syntax(error)
221 }
222}
223
224impl From<IllFormedError> for Error {
225 /// Creates a new `Error::IllFormed` from the given error
226 #[inline]
227 fn from(error: IllFormedError) -> Self {
228 Self::IllFormed(error)
229 }
230}
231
232impl From<Utf8Error> for Error {
233 /// Creates a new `Error::NonDecodable` from the given error
234 #[inline]
235 fn from(error: Utf8Error) -> Error {
236 Error::NonDecodable(Some(error))
237 }
238}
239
240impl From<FromUtf8Error> for Error {
241 /// Creates a new `Error::Utf8` from the given error
242 #[inline]
243 fn from(error: FromUtf8Error) -> Error {
244 error.utf8_error().into()
245 }
246}
247
248impl From<EscapeError> for Error {
249 /// Creates a new `Error::EscapeError` from the given error
250 #[inline]
251 fn from(error: EscapeError) -> Error {
252 Error::EscapeError(error)
253 }
254}
255
256impl From<AttrError> for Error {
257 #[inline]
258 fn from(error: AttrError) -> Self {
259 Error::InvalidAttr(error)
260 }
261}
262
263/// A specialized `Result` type where the error is hard-wired to [`Error`].
264pub type Result<T> = std::result::Result<T, Error>;
265
266impl fmt::Display for Error {
267 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
268 match self {
269 Error::Io(e) => write!(f, "I/O error: {}", e),
270 Error::Syntax(e) => write!(f, "syntax error: {}", e),
271 Error::IllFormed(e) => write!(f, "ill-formed document: {}", e),
272 Error::NonDecodable(None) => write!(f, "Malformed input, decoding impossible"),
273 Error::NonDecodable(Some(e)) => write!(f, "Malformed UTF-8 input: {}", e),
274 Error::InvalidAttr(e) => write!(f, "error while parsing attribute: {}", e),
275 Error::EscapeError(e) => write!(f, "{}", e),
276 Error::UnknownPrefix(prefix) => {
277 f.write_str("Unknown namespace prefix '")?;
278 write_byte_string(f, prefix)?;
279 f.write_str("'")
280 }
281 Error::InvalidPrefixBind { prefix, namespace } => {
282 f.write_str("The namespace prefix '")?;
283 write_byte_string(f, prefix)?;
284 f.write_str("' cannot be bound to '")?;
285 write_byte_string(f, namespace)?;
286 f.write_str("'")
287 }
288 }
289 }
290}
291
292impl std::error::Error for Error {
293 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
294 match self {
295 Error::Io(e) => Some(e),
296 Error::Syntax(e) => Some(e),
297 Error::IllFormed(e) => Some(e),
298 Error::NonDecodable(Some(e)) => Some(e),
299 Error::InvalidAttr(e) => Some(e),
300 Error::EscapeError(e) => Some(e),
301 _ => None,
302 }
303 }
304}
305
306#[cfg(feature = "serialize")]
307pub mod serialize {
308 //! A module to handle serde (de)serialization errors
309
310 use super::*;
311 use std::borrow::Cow;
312 #[cfg(feature = "overlapped-lists")]
313 use std::num::NonZeroUsize;
314 use std::num::{ParseFloatError, ParseIntError};
315
316 /// (De)serialization error
317 #[derive(Clone, Debug)]
318 pub enum DeError {
319 /// Serde custom error
320 Custom(String),
321 /// Xml parsing error
322 InvalidXml(Error),
323 /// Cannot parse to integer
324 InvalidInt(ParseIntError),
325 /// Cannot parse to float
326 InvalidFloat(ParseFloatError),
327 /// Cannot parse specified value to boolean
328 InvalidBoolean(String),
329 /// This error indicates an error in the [`Deserialize`](serde::Deserialize)
330 /// implementation when read a map or a struct: `MapAccess::next_value[_seed]`
331 /// was called before `MapAccess::next_key[_seed]`.
332 ///
333 /// You should check your types, that implements corresponding trait.
334 KeyNotRead,
335 /// Deserializer encounter a start tag with a specified name when it is
336 /// not expecting. This happens when you try to deserialize a primitive
337 /// value (numbers, strings, booleans) from an XML element.
338 UnexpectedStart(Vec<u8>),
339 /// The [`Reader`] produced [`Event::Eof`] when it is not expecting,
340 /// for example, after producing [`Event::Start`] but before corresponding
341 /// [`Event::End`].
342 ///
343 /// [`Reader`]: crate::reader::Reader
344 /// [`Event::Eof`]: crate::events::Event::Eof
345 /// [`Event::Start`]: crate::events::Event::Start
346 /// [`Event::End`]: crate::events::Event::End
347 UnexpectedEof,
348 /// An attempt to deserialize to a type, that is not supported by the XML
349 /// store at current position, for example, attempt to deserialize `struct`
350 /// from attribute or attempt to deserialize binary data.
351 ///
352 /// Serialized type cannot be represented in an XML due to violation of the
353 /// XML rules in the final XML document. For example, attempt to serialize
354 /// a `HashMap<{integer}, ...>` would cause this error because [XML name]
355 /// cannot start from a digit or a hyphen (minus sign). The same result
356 /// would occur if map key is a complex type that cannot be serialized as
357 /// a primitive type (i.e. string, char, bool, unit struct or unit variant).
358 ///
359 /// [XML name]: https://www.w3.org/TR/xml11/#sec-common-syn
360 Unsupported(Cow<'static, str>),
361 /// Too many events were skipped while deserializing a sequence, event limit
362 /// exceeded. The limit was provided as an argument
363 #[cfg(feature = "overlapped-lists")]
364 TooManyEvents(NonZeroUsize),
365 }
366
367 impl fmt::Display for DeError {
368 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
369 match self {
370 DeError::Custom(s) => write!(f, "{}", s),
371 DeError::InvalidXml(e) => write!(f, "{}", e),
372 DeError::InvalidInt(e) => write!(f, "{}", e),
373 DeError::InvalidFloat(e) => write!(f, "{}", e),
374 DeError::InvalidBoolean(v) => write!(f, "Invalid boolean value '{}'", v),
375 DeError::KeyNotRead => write!(f, "Invalid `Deserialize` implementation: `MapAccess::next_value[_seed]` was called before `MapAccess::next_key[_seed]`"),
376 DeError::UnexpectedStart(e) => {
377 f.write_str("Unexpected `Event::Start(")?;
378 write_byte_string(f, e)?;
379 f.write_str(")`")
380 }
381 DeError::UnexpectedEof => write!(f, "Unexpected `Event::Eof`"),
382 DeError::Unsupported(s) => write!(f, "Unsupported operation: {}", s),
383 #[cfg(feature = "overlapped-lists")]
384 DeError::TooManyEvents(s) => write!(f, "Deserializer buffers {} events, limit exceeded", s),
385 }
386 }
387 }
388
389 impl ::std::error::Error for DeError {
390 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
391 match self {
392 DeError::InvalidXml(e) => Some(e),
393 DeError::InvalidInt(e) => Some(e),
394 DeError::InvalidFloat(e) => Some(e),
395 _ => None,
396 }
397 }
398 }
399
400 impl serde::de::Error for DeError {
401 fn custom<T: fmt::Display>(msg: T) -> Self {
402 DeError::Custom(msg.to_string())
403 }
404 }
405
406 impl serde::ser::Error for DeError {
407 fn custom<T: fmt::Display>(msg: T) -> Self {
408 DeError::Custom(msg.to_string())
409 }
410 }
411
412 impl From<Error> for DeError {
413 #[inline]
414 fn from(e: Error) -> Self {
415 Self::InvalidXml(e)
416 }
417 }
418
419 impl From<EscapeError> for DeError {
420 #[inline]
421 fn from(e: EscapeError) -> Self {
422 Self::InvalidXml(e.into())
423 }
424 }
425
426 impl From<Utf8Error> for DeError {
427 #[inline]
428 fn from(e: Utf8Error) -> Self {
429 Self::InvalidXml(e.into())
430 }
431 }
432
433 impl From<FromUtf8Error> for DeError {
434 #[inline]
435 fn from(e: FromUtf8Error) -> Self {
436 Self::InvalidXml(e.into())
437 }
438 }
439
440 impl From<AttrError> for DeError {
441 #[inline]
442 fn from(e: AttrError) -> Self {
443 Self::InvalidXml(e.into())
444 }
445 }
446
447 impl From<ParseIntError> for DeError {
448 #[inline]
449 fn from(e: ParseIntError) -> Self {
450 Self::InvalidInt(e)
451 }
452 }
453
454 impl From<ParseFloatError> for DeError {
455 #[inline]
456 fn from(e: ParseFloatError) -> Self {
457 Self::InvalidFloat(e)
458 }
459 }
460
461 impl From<fmt::Error> for DeError {
462 #[inline]
463 fn from(e: fmt::Error) -> Self {
464 Self::Custom(e.to_string())
465 }
466 }
467}