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.

§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, ResolvedEvent, 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 async feature.

use rxml::{AsyncReader, Error, ResolvedEvent, 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(), ResolvedEvent::XmlDeclaration(_, XmlVersion::V1_0)));

§Feature flags

  • macros: Enable macros to convert &str to &NameStr, &NcNameStr and &CDataStr respectively.
  • smartstring (default): Enable the use of smartstring for some string types to avoid allocations and conserve heap memory.
  • tokio (default): Enable AsyncReader and related types. Implies sync.
  • sync (default): Use Arc instead of Rc for deduplicated namespace URIs.
  • stream: Add a futures::Stream implementation to AsyncReader. Implies tokio.
  • shared_ns: Allow deduplication of namespace URIs within and across parsers.

Re-exports§

Modules§

  • 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

Macros§

Structs§

  • AsyncReadertokio
    Tokio-compatible asynchronous restricted XML 1.0 parser
  • Context
    Shared context for multiple parsers
  • Encoder
    Encodes XML into buffers.
  • Options
    Parser configuration
  • Parser
    Non-blocking restricted XML 1.0 parser
  • RawParser
    Low-level restricted XML 1.0 parser
  • Reader
    Restricted XML 1.0 parser

Enums§

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§

Functions§

  • as_eof_flag
    Convert end-of-file-ness of a result to a boolean flag.

Type Aliases§