tl

The tl parser includes optimized utility functions that use SIMD (Single Instruction, Multiple Data) to process bytes more efficiently.

To use these, you must:

1. Enable the simd feature flag in your Cargo.toml.
2. Use a nightly Rust compiler, as the feature relies on the unstable portable_simd nightly feature.

If the simd feature is not enabled, the crate falls back to highly optimized stable alternatives using manual loop unrolling.

The tl-fuzz package contains fuzz tests designed to find bugs such as crashes or infinite loops. You can execute these tests using cargo-fuzz. To run a specific test, identify the target name from the files located in the fuzz_targets folder and use the cargo fuzz run command.

cargo fuzz run <fuzz_test>

Add tl to your Cargo.toml dependencies. You can use the default configuration or enable the simd feature for accelerated parsing (note that the simd feature requires a nightly Rust compiler).

[dependencies]
tl = "0.7.8"
# or, with explicit SIMD support (requires a nightly compiler!)
tl = { version = "0.7.8", features = ["simd"] }

The HTMLTag struct provides two ways to access its children via wrapper types:

1. Children (Immutable):

   • top(): Returns the direct, topmost children (including whitespace nodes).
   • all(parser): Returns a slice containing all subnodes, including deeply nested children.
   • boundaries(parser): Returns the start and end boundaries of the children.

2. ChildrenMut (Mutable):

   • top_mut(): Returns a mutable slice of the direct, topmost children.

Important Distinction: top() only returns the immediate children of the tag. all() returns the entire subtree of nodes contained within that tag.

// Example: Accessing all subnodes
let a = dom.get_element_by_id("a").unwrap().get(parser).unwrap().as_tag().unwrap();
assert_eq!(a.children().all(parser).len(), 7);

Users should not construct the Parser struct directly. Instead, use the high-level tl::parse() function, which returns a VDom (Virtual DOM) containing the parsed tree.

Note: The Parser struct itself is an internal implementation detail used during the parsing phase.

The ParserOptions struct allows you to configure the behavior of the HTML parser. By default, ParserOptions::default() is optimized for raw parsing speed.

If your use case requires efficient lookups of elements by ID or class name, you should enable tracking. Enabling tracking causes the parser to cache HTML nodes in lookup tables on the fly as they are encountered in the source code.

// Default behavior (optimized for raw parsing)
let options = ParserOptions::default();

// Optimized for ID/Class lookups
let options = ParserOptions::new()
    .track_ids()
    .track_classes();

The VDom struct represents the parsed Document Object Model (DOM). It acts as a wrapper around the internal Parser. Most operations that require resolving NodeHandles to actual Node objects require a reference to the underlying Parser, which can be accessed via VDom::parser() or VDom::parser_mut().

let html = r#"<div><p href="/about" id="find-me">Hello world</p></div>"#;
let mut dom = tl::parse(html, Default::default()).unwrap();

// Accessing the parser to resolve handles
let parser = dom.parser();
// ... use parser with handles ...

When you need to parse an owned String rather than a borrowed &str, use VDomGuard. It uses RAII to ensure the input string is freed once the guard goes out of scope. You can access the underlying VDom via get_ref() or get_mut_ref().

// Note: VDomGuard::parse is internal/pub(crate) in this snippet,
// typically accessed via a public wrapper like tl::parse_owned()
let guard = tl::parse_owned(input_string, options).unwrap();
let dom = guard.get_ref();

You can use the query_selector method on a Dom instance to find elements matching a CSS selector. This returns an iterator over the matching nodes.

let dom = tl::parse(r#"<div><img src=\"cool-image.png\" /></div>"#, tl::ParserOptions::default()).unwrap();
let img = dom.query_selector("img[src]").unwrap().next();
    
assert!(img.is_some());

To traverse the document structure, use the nodes() method on the Dom instance to get an iterator over all nodes in the document.

let dom = tl::parse(r#"<div><img src=\"cool-image.png\" /></div>"#, tl::ParserOptions::default()).unwrap();
let img = dom.nodes()
  .iter()
  .find(|node| {
    node.as_tag().map_or(false, |tag| tag.name() == "img")
  });
    
assert!(img.is_some());

Use tl::parse() to convert an HTML source string into a DOM tree. It accepts a string slice and a tl::ParserOptions object.

Note: tl may silently ignore invalid tags (similar to browser behavior), which can result in large sections of the document being omitted from the resulting tree if the HTML is malformed.

let dom = tl::parse(r#"<p id=\"text\">Hello</p>"#, tl::ParserOptions::default()).unwrap();