1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# `rxml` — Restricted, minimalistic XML 1.0 parser
This crate provides "restricted" parsing of XML 1.0 documents with
namespacing.
[](https://crates.io/crates/rxml) [](https://docs.rs/rxml/)
## 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` and `&NcNameStr`,
respectively.
- `compact_str` (default): Enable the use of
[`compact_str`](https://crates.io/crates/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`.
|
