README.md
1# xml5ever
2
3 
4[](https://docs.rs/xml5ever)
5[](https://crates.io/crates/xml5ever)
6
7[API documentation](https://Ygg01.github.io/docs/xml5ever/xml5ever/index.html)
8
9**Warning:** This library is alpha quality, so no guarantees are given.
10
11This crate provides a push based XML parser library that trades well-formedness for error recovery.
12
13xml5ever is based largely on [html5ever](https://github.com/servo/html5ever) parser, so if you have experience with html5ever you will be familiar with xml5ever.
14
15The library is dual licensed under MIT and Apache license.
16
17# Why you should use xml5ever
18
19Main use case for this library is when XML is badly formatted, usually from bad XML
20templates. XML5 tries to handle most common errors, in a manner similar to HTML5.
21
22## When you should use it?
23
24 - You aren't interested in well-formed documents.
25 - You need to get some info from your data even if it has errors (although not all possible errors are handled).
26 - You want to features like character references or xml namespaces.
27
28## When you shouldn't use it
29
30 - You need to have your document validated.
31 - You require DTD support.
32 - You require an easy to use parser, with lots of extensions (e.g. XPath, XQuery).
33 - You require a battle tested, industry proven solution.
34
35# Installation
36
37Add xml5ever as a dependency in your project manifest.
38
39```toml
40 [dependencies]
41 xml5ever = "0.1.3"
42```
43
44And add crate declaration in your lib.rs
45
46```rust
47 extern crate xml5ever
48```
49
50# Getting started
51
52Here is a very simple RcDom backed parser:
53
54```rust
55
56 let input = "<xml></xml>".to_tendril();
57
58 // To parse XML into a tree form, we need a TreeSink
59 // luckily xml5ever comes with a static RC backed tree represetation.
60 let dom: RcDom = parse(std::iter::once(input), Default::default());
61
62 // Do something with dom
63
64```
65The thing that does actual parsing is the `parse` function. It expects an iterator that can be converted into `StrTendril`, so you can use `std::iter::once(input)` or `Some(input).into_iter()` (where `input` is `StrTendril` like structure).
66
67# Working on xml5ever
68
69To build examples and tests you need to do something along the lines of:
70
71```rust
72 git submodule update --init # to fetch xml5lib-tests
73 cargo build
74 cargo test
75```
76
77This will fetch tests from outside repository and it will invoke cargo to
78build and test the crate. If you need docs checkout either [API docs](https://ygg01.github.io/docs/xml5ever/xml5ever/index.html) or run `cargo docs`
79to generate documentation.
80
81## Easy first tasks
82
83What I generally recommend is to look at Clippy Linting badge results and create
84a PR for fixing the said lints. Other than that try to look for any tasks labeled
85easy or just update docs/examples.
86
){kind=link}
){kind=link}
){kind=link}