Crate rxml

Source

Expand description

§Restricted XML parsing and encoding

This crate provides “restricted” parsing and encoding of XML 1.0 documents with namespacing.

§Features (some call them restrictions)

No external resources
No custom entities
No DTD whatsoever
No processing instructions
No comments
UTF-8 only
Namespacing-well-formedness enforced
XML 1.0 only
Streamed parsing (parser emits a subset of SAX events)
Streamed encoding
Parser can be driven push- and pull-based
Tokio-based asynchronicity supported via the async feature and AsyncReader.

See crate::_spec for additional documentation on what exactly “restricted XML” means.

§Examples

§Parse data from byte slices

To parse a XML document from a byte slice (or a series of byte slices), you can use the Parser with the Parse trait directly:

use rxml::{Parser, Parse, Error, Event, XmlVersion};
use std::io;
let mut doc = &b"<?xml version='1.0'?><hello>World!</hello>"[..];
let mut fp = Parser::new();
while doc.len() > 0 {
	let ev = fp.parse(&mut doc, true);  // true = doc contains the entire document
	println!("got event: {:?}", ev);
}

§Parse data from a standard library reader

To parse a XML document from a std::io::BufRead struct, you can use the Reader.

// let file = std::fs::File::open(..).unwrap();
let reader = BufReader::new(file);
let mut reader = rxml::Reader::new(reader);
let result = rxml::as_eof_flag(reader.read_all(|ev| {
	println!("got event: {:?}", ev);
}));
assert_eq!(result.unwrap(), true);  // true indicates eof

§Parse data using `tokio`

To parse a XML document from a tokio::io::AsyncBufRead struct, you can use the AsyncReader.

This requires the tokio feature.

use rxml::{AsyncReader, Error, Event, XmlVersion};
// let sock = ..;
let reader = tokio::io::BufReader::new(sock);
// this converts the doc into an tokio::io::AsyncRead
let mut reader = AsyncReader::new(reader);
// we expect the first event to be the XML declaration
let ev = reader.read().await;
assert!(matches!(ev.unwrap().unwrap(), Event::XmlDeclaration(_, XmlVersion::V1_0)));

§Feature flags

macros: Enable macros to convert &str to &NameStr and &NcNameStr, respectively.
compact_str (default): Enable the use of compact_str for some string types to avoid allocations and conserve heap memory.
tokio (default): Enable AsyncReader and related types.
stream: Add a futures::Stream implementation to AsyncReader. Implies tokio.
shared_ns: Allow deduplication of namespace URIs within and across parsers.
std (default): Enable Reader and related types which depend on std::io.

Re-exports§

pub use strings::Namespace;
pub use bytes;

Modules§

_spec: Restricted XML 1.0-1
error: Error types
parser: Restricted XML 1.0 parsing facilities
strings: Strongly-typed strings for use with XML 1.0 documents
writer: Writer for restricted XML 1.0
xml_lang: Handling of the special xml:lang attribute
xml_map: Map structure for XML names to values

Macros§

xml_namemacros: Compile-time conversion of a string literal to NameStr
xml_ncnamemacros: Compile-time conversion of a string literal to NcNameStr

Structs§

Context: Shared context for multiple parsers
Encoder: Encodes XML into buffers.
GenericAsyncReadertokio: Generic tokio-compatible asynchronous driver for restricted XML parsers.
GenericReaderstd: Generic driver for restricted XML parsers.
Name: String which conforms to the Name production of XML 1.0.
NameStr: str which conforms to the Name production of XML 1.0.
NcName: String which conforms to the NcName production of Namespaces in XML 1.0.
NcNameStr: str which conforms to the NcName production of Namespaces in XML 1.0.
Options: Parser configuration
Parser: Non-blocking restricted XML 1.0 parser
RawParser: Low-level restricted XML 1.0 parser (without namespace support)
XmlLangTracker: Track and provide access to the currently effective xml:lang value.
XmlMap: Container struct for a set of attributes on an XML element.

Enums§

Error: Error types which may be returned from functions in this crate.
Event: High-level, logical XML document parts
Item: An encodable item.
RawEvent: Logical XML document parts
XmlVersion: XML version number

Constants§

PREFIX_XML: The static prefix used for XML built-in attributes (xml).
PREFIX_XMLNS: The static prefix used for XML namespace declarations (xmlns).
VERSION: Package version
XMLNS_XML: XML core namespace URI (for the xml: prefix)
XMLNS_XMLNS: XML namespace URI (for the xmlns: prefix)

Traits§

Parse: XML parser trait
WithOptions: Trait for things which can be constructed with Options.

Functions§

as_eof_flagstd: Convert end-of-file-ness of a result to a boolean flag.

Type Aliases§

AsyncRawReadertokio: Low-level tokio-compatible asynchronous restricted XML 1.0 parser (without namespace support)
AsyncReadertokio: Tokio-compatible asynchronous restricted XML 1.0 parser
AttrMap: Type alias for the commonly used mapping type for XML attribute values.
QName: Pair of an optional namespace name (URI) and a localpart, commonly used in element and attribute names.
RawQName: Pair of an optional namespace prefix and a localpart, commonly used in element and attribute names.
RawReaderstd: Low-level restricted XML 1.0 parser (without namespace support)
Readerstd: Restricted XML 1.0 parser
Result: The default result type for this crate.

Crate rxmlCopy item path