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 common named ones (`&amp;
30//!   &lt; &copy; &mdash; …`, ~100) plus `&#NNN;` / `&#xHH;`; U+0000,
31//!   surrogates and out-of-range values decode to U+FFFD
32//! - A `<` not followed by an ASCII letter, `/`, `!`, or `?` is text
33//!   (`a < b` needs no escaping)
34//! - `<style>` / `<script>` bodies are raw text; `<textarea>` /
35//!   `<title>` bodies are RCDATA (references decode, tags are text)
36//! - Comments: `<!-- … -->` preserved as Comment nodes; `<?…>` and
37//!   `<!…>` (other than DOCTYPE) are bogus comments, also Comment nodes
38//! - `<!DOCTYPE …>` is consumed (no node)
39//! - Case-insensitive tag names (normalized to lowercase)
40//! - Attribute names preserved case
41//!
42//! ## Not supported (out of scope)
43//!
44//! - CDATA sections as CDATA (they become bogus comments), namespace
45//!   prefixes
46//! - Tree-construction recovery: a mismatched or missing end tag, or a
47//!   stray end tag at the top level, is an error, not auto-repaired
48//! - The full 2 231-entry named-reference table and the legacy
49//!   no-semicolon references (`&amp` without `;` stays literal)
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 error;
65mod parser;
66
67pub use dom_ext::NodeMutHtml;
68pub use error::{ParseError, Result};
69pub use parser::{parse, parse_into};