| 1 | //! High performance XML reader/writer.
|
| 2 | //!
|
|---|
| 3 | //! # Description
|
|---|
| 4 | //!
|
|---|
| 5 | //! quick-xml contains two modes of operation:
|
|---|
| 6 | //!
|
|---|
| 7 | //! A streaming API based on the [StAX] model. This is suited for larger XML documents which
|
|---|
| 8 | //! cannot completely read into memory at once.
|
|---|
| 9 | //!
|
|---|
| 10 | //! The user has to explicitly _ask_ for the next XML event, similar to a database cursor.
|
|---|
| 11 | //! This is achieved by the following two structs:
|
|---|
| 12 | //!
|
|---|
| 13 | //! - [`Reader`]: A low level XML pull-reader where buffer allocation/clearing is left to user.
|
|---|
| 14 | //! - [`Writer`]: A XML writer. Can be nested with readers if you want to transform XMLs.
|
|---|
| 15 | //!
|
|---|
| 16 | //! Especially for nested XML elements, the user must keep track _where_ (how deep)
|
|---|
| 17 | //! in the XML document the current event is located.
|
|---|
| 18 | //!
|
|---|
| 19 | //! quick-xml contains optional support of asynchronous reading and writing using [tokio].
|
|---|
| 20 | //! To get it enable the [`async-tokio`](#async-tokio) feature.
|
|---|
| 21 | //!
|
|---|
| 22 | //! Furthermore, quick-xml also contains optional [Serde] support to directly
|
|---|
| 23 | //! serialize and deserialize from structs, without having to deal with the XML events.
|
|---|
| 24 | //! To get it enable the [`serialize`](#serialize) feature. Read more about mapping Rust types
|
|---|
| 25 | //! to XML in the documentation of [`de`] module. Also check [`serde_helpers`]
|
|---|
| 26 | //! module.
|
|---|
| 27 | //!
|
|---|
| 28 | //! # Examples
|
|---|
| 29 | //!
|
|---|
| 30 | //! - For a reading example see [`Reader`]
|
|---|
| 31 | //! - For a writing example see [`Writer`]
|
|---|
| 32 | //!
|
|---|
| 33 | //! # Features
|
|---|
| 34 | //!
|
|---|
| 35 | //! `quick-xml` supports the following features:
|
|---|
| 36 | //!
|
|---|
| 37 | //! [StAX]: https://en.wikipedia.org/wiki/StAX
|
|---|
| 38 | //! [tokio]: https://tokio.rs/
|
|---|
| 39 | //! [Serde]: https://serde.rs/
|
|---|
| 40 | //! [`de`]: ./de/index.html
|
|---|
| 41 | #![cfg_attr (
|
|---|
| 42 | feature = "document-features" ,
|
|---|
| 43 | cfg_attr(doc, doc = ::document_features::document_features!(
|
|---|
| 44 | feature_label = "<a id= \"{feature} \" href= \"#{feature} \"><strong><code>{feature}</code></strong></a>"
|
|---|
| 45 | ))
|
|---|
| 46 | )]
|
|---|
| 47 | #![forbid (unsafe_code)]
|
|---|
| 48 | #![deny (missing_docs)]
|
|---|
| 49 | #![recursion_limit = "1024" ]
|
|---|
| 50 | // Enable feature requirements in the docs from 1.57
|
|---|
| 51 | // See https://stackoverflow.com/questions/61417452
|
|---|
| 52 | #![cfg_attr (docs_rs, feature(doc_auto_cfg))]
|
|---|
| 53 |
|
|---|
| 54 | #[cfg (feature = "serialize" )]
|
|---|
| 55 | pub mod de;
|
|---|
| 56 | pub mod encoding;
|
|---|
| 57 | mod errors;
|
|---|
| 58 | mod escapei;
|
|---|
| 59 | pub mod escape {
|
|---|
| 60 | //! Manage xml character escapes
|
|---|
| 61 | pub use crate::escapei::{escape, partial_escape, unescape, unescape_with, EscapeError};
|
|---|
| 62 | }
|
|---|
| 63 | pub mod events;
|
|---|
| 64 | pub mod name;
|
|---|
| 65 | pub mod reader;
|
|---|
| 66 | #[cfg (feature = "serialize" )]
|
|---|
| 67 | pub mod se;
|
|---|
| 68 | #[cfg (feature = "serde-types" )]
|
|---|
| 69 | pub mod serde_helpers;
|
|---|
| 70 | /// Not an official API, public for integration tests
|
|---|
| 71 | #[doc (hidden)]
|
|---|
| 72 | pub mod utils;
|
|---|
| 73 | pub mod writer;
|
|---|
| 74 |
|
|---|
| 75 | // reexports
|
|---|
| 76 | pub use crate::encoding::Decoder;
|
|---|
| 77 | #[cfg (feature = "serialize" )]
|
|---|
| 78 | pub use crate::errors::serialize::DeError;
|
|---|
| 79 | pub use crate::errors::{Error, Result};
|
|---|
| 80 | pub use crate::reader::{NsReader, Reader};
|
|---|
| 81 | pub use crate::writer::{ElementWriter, Writer};
|
|---|
| 82 | |
|---|
