#xml-parser #xml-data #xml #xml-document #namespaces #minimalist #events

rxml

Minimalistic, restricted XML 1.0 parser which does not include dangerous XML features

17 releases (11 breaking)

0.12.0 Aug 12, 2024
0.11.1 Jun 23, 2024
0.10.1 Jun 8, 2024
0.10.0 Mar 16, 2024
0.3.0 Jun 26, 2021

#586 in Parser implementations

Download history 13718/week @ 2024-07-15 13870/week @ 2024-07-22 18519/week @ 2024-07-29 20044/week @ 2024-08-05 15028/week @ 2024-08-12 14060/week @ 2024-08-19 14861/week @ 2024-08-26 16327/week @ 2024-09-02 15767/week @ 2024-09-09 15261/week @ 2024-09-16 16177/week @ 2024-09-23 13824/week @ 2024-09-30 14985/week @ 2024-10-07 17793/week @ 2024-10-14 19315/week @ 2024-10-21 18794/week @ 2024-10-28

71,568 downloads per month
Used in 33 crates (3 directly)

MIT license

435KB
12K SLoC

rxml — Restricted, minimalistic XML 1.0 parser

This crate provides "restricted" parsing of XML 1.0 documents with namespacing.

crate badge docs badge

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, 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.

# use std::io::BufReader;
# let file = &mut &b"<?xml version='1.0'?><hello>World!</hello>"[..];
// 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 tokio::io::AsyncRead;
use rxml::{AsyncReader, Error, Event, XmlVersion};
# tokio_test::block_on(async {
# let sock = &mut &b"<?xml version='1.0'?><hello>World!</hello>"[..];
// 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, &NcNameStr and &CDataStr 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.

Dependencies

~2.1–8MB
~54K SLoC