Skip to main content

rdom_parser/
lib.rs

1//! # rdom-parser — HTML-ish template parser for rdom-core
2//!
3//! Turns a template string into a `Dom<Ext>` tree. The `parseFromString`
4//! equivalent for the rdom family of crates.
5//!
6//! ## Quick start
7//!
8//! ```
9//! use rdom_parser::parse;
10//! use rdom_core::Dom;
11//!
12//! let (dom, ids): (Dom<()>, _) = parse(r#"
13//!     <div class="hero" id="main">
14//!         <h1>Welcome</h1>
15//!         <p>Hello &amp; <strong>world</strong></p>
16//!     </div>
17//! "#).unwrap();
18//!
19//! let div = ids.iter().find(|&&id| dom.node(id).tag_name() == Some("div")).unwrap();
20//! assert!(dom.node(*div).has_class("hero"));
21//! ```
22//!
23//! ## Supported
24//!
25//! - Start / end / self-closing tags, case-insensitive tag names
26//! - Void elements (`<br>`, `<hr>`, `<img>`, …) auto-close
27//! - Attributes: `name="value"`, `name='value'`, `name=value`, `name`
28//!   (boolean). `class="a b c"` populates the classList.
29//! - Text with character references: the full WHATWG named table
30//!   (2 231 entries, including the legacy no-`;` names such as `&amp`
31//!   and `&copy`, with HTML's attribute-value caveat) plus `&#NNN;` /
32//!   `&#xHH;`; U+0000, surrogates and out-of-range values decode to
33//!   U+FFFD
34//! - A `<` not followed by an ASCII letter, `/`, `!`, or `?` is text
35//!   (`a < b` needs no escaping)
36//! - `<style>` / `<script>` bodies are raw text; `<textarea>` /
37//!   `<title>` bodies are RCDATA (references decode, tags are text)
38//! - Comments: `<!-- … -->` preserved as Comment nodes; `<?…>` and
39//!   `<!…>` (other than DOCTYPE) are bogus comments, also Comment nodes
40//! - `<!DOCTYPE …>` is consumed (no node)
41//! - Case-insensitive tag names (normalized to lowercase)
42//! - Attribute names preserved case
43//!
44//! ## Not supported (out of scope)
45//!
46//! - CDATA sections as CDATA (they become bogus comments), namespace
47//!   prefixes
48//! - Tree-construction recovery: a mismatched or missing end tag, or a
49//!   stray end tag at the top level, is an error, not auto-repaired
50//!
51//! ## Error reporting
52//!
53//! `ParseError` carries line/col/pos + optional hint:
54//!
55//! ```
56//! # use rdom_parser::parse;
57//! # use rdom_core::Dom;
58//! let err = parse::<()>("<div><span></p></div>").unwrap_err();
59//! assert!(err.msg.contains("mismatched"));
60//! assert!(err.hint.is_some());
61//! ```
62
63mod dom_ext;
64mod entities;
65mod error;
66mod parser;
67
68pub use dom_ext::NodeMutHtml;
69pub use error::{ParseError, Result};
70pub use parser::{parse, parse_into};