tl/
lib.rs

1#![doc = include_str!("../README.md")]
2#![deny(missing_docs)]
3
4mod bytes;
5/// Errors that occur throughout the crate
6pub mod errors;
7/// Inline data structures
8pub mod inline;
9mod parser;
10/// Query selector API
11pub mod queryselector;
12mod stream;
13#[cfg(test)]
14mod tests;
15mod util;
16mod vdom;
17
18#[doc(hidden)]
19#[cfg(feature = "__INTERNALS_DO_NOT_USE")]
20pub mod simd;
21#[cfg(not(feature = "__INTERNALS_DO_NOT_USE"))]
22mod simd;
23
24pub use bytes::Bytes;
25pub use errors::ParseError;
26pub use parser::*;
27use queryselector::Selector;
28pub use vdom::{VDom, VDomGuard};
29
30/// Parses the given input string
31///
32/// This is the "entry point" and function that is called to parse HTML.
33/// The input string must be kept alive, and must outlive `VDom`.
34/// If you need an "owned" version that takes an input string and can be kept around forever,
35/// consider using `parse_owned()`.
36///
37/// # Errors
38/// Throughout the parser it is assumed that spans never overflow a `u32`.
39/// To prevent this, this function will return an error if the input string length would overflow a `u32`.
40/// If the input string length fits in a `u32`, then it is safe to assume that none of the substrings can overflow a `u32`.
41///
42/// # Example
43/// ```
44/// # use tl::*;
45/// let dom = parse("<div>Hello, world!</div>", ParserOptions::default()).unwrap();
46/// assert_eq!(dom.query_selector("div").unwrap().count(), 1);
47/// ```
48pub fn parse(input: &str, options: ParserOptions) -> Result<VDom<'_>, ParseError> {
49    let mut parser = Parser::new(input, options);
50    parser.parse()?;
51    Ok(VDom::from(parser))
52}
53
54/// Parses a query selector
55///
56/// # Example
57/// ```
58/// # use tl::queryselector::selector::Selector;
59/// let selector = tl::parse_query_selector("div#test");
60///
61/// match selector {
62///     Some(Selector::And(left, right)) => {
63///         assert!(matches!(&*left, Selector::Tag(b"div")));
64///         assert!(matches!(&*right, Selector::Id(b"test")));
65///     },
66///     _ => unreachable!()
67/// }
68/// ```
69pub fn parse_query_selector(input: &str) -> Option<Selector<'_>> {
70    let selector = queryselector::Parser::new(input.as_bytes()).selector()?;
71    Some(selector)
72}
73
74/// Parses the given input string and returns an owned, RAII guarded DOM
75///
76/// # Errors
77/// See [parse]
78///
79/// # Safety
80/// This uses `unsafe` code to create a self-referential-like struct.
81/// The given input string is first leaked and turned into raw pointer, and its lifetime will be promoted to 'static.
82/// Once `VDomGuard` goes out of scope, the string will be freed.
83/// It should not be possible to cause UB in its current form and might become a safe function in the future.
84pub unsafe fn parse_owned(input: String, options: ParserOptions) -> Result<VDomGuard, ParseError> {
85    VDomGuard::parse(input, options)
86}
tl/lib.rs

tl/
lib.rs
