Skip to content
James Conway edited this page Nov 20, 2026 · 12 revisions

Short answers to what people ask first about Parsec, each pointing at the page with the long one.

All 24 questions

Can I use Parsec today?

Yes, from git; it isn't released. Add parsec-html = { git = "https://github.com/parsec-html/parsec" } to your dependencies and use parsec. The API can still change before 0.1.0, so pin a commit if that matters to you. Getting started has the details.

When is the first release?

When milestones M1 to M4 are done and the benchmarks show Parsec ahead of Lexbor on every page in the corpus (#32). There's no date. Roadmap has what's in each milestone.

Is it a fork of Lexbor, or html5ever?

Neither. It's its own parser, written in Rust from the HTML Standard. It's developed inside Netweir as crates/netweir-html and synced here; Contributing explains how.

Is it faster than Lexbor?

On real pages, yes. Against Lexbor 3.0.1's own C in one process, Parsec is 1.5 times as fast across 13 real pages and ahead on every one of them, with less memory. It's ahead on all eight hostile inputs as well. Benchmarks has the numbers and how to rerun them on your machine.

How correct is it?

It passes all 7,042 html5lib tokenizer runs it can be given and all 3,898 runs of the WPT tree-construction cases that don't need JavaScript. Conformance says exactly what's counted and skipped.

Does it run JavaScript?

No. The scripting flag only changes how <noscript> is parsed, as a browser with JavaScript on or off would parse it. See Parsing.

Which scripting value should I use?

false, usually. Then <noscript> fallbacks become ordinary elements your selectors can find. Use true if you want the tree a JavaScript-enabled browser builds.

Can I parse bytes, or pages in other encodings?

Yes. parsec_encoding::parse_bytes takes bytes and finds the encoding the way a browser does: byte order mark, the HTTP charset if you pass it, <meta charset>, then a fallback. Every encoding in the WHATWG Encoding Standard decodes, through encoding_rs. See Encoding.

Why did my page parse in quirks mode?

Either it has no doctype, or it has an old one, or a tag or text other than whitespace comes before it. A byte order mark at the very start doesn't count: parse drops it, as a browser does. Quirks mode has the rules.

Why doesn't .Foo match class="foo"?

Class names and ids compare exactly, as in a browser, except in quirks-mode documents. A page with no doctype is in quirks mode, so there .foo would match. See Selectors.

Why doesn't [href] find SVG's xlink:href?

Because xlink:href is in the XLink namespace and [href] means no namespace, as in a browser. Use [*|href].

Why can't my selector see what's inside a <template>?

The HTML Standard keeps template contents out of the tree, and Parsec follows it. Run the selector on doc.template_contents(id), or call doc.adopt_template_contents() once to move all contents into the tree, as lxml and Beautiful Soup show them. See The document tree.

Why is :blank (or ::before) an error?

Parsec refuses selectors it doesn't match yet, rather than parse them and silently match nothing. Each missing pseudo-class has an issue; pseudo-elements select parts of elements, not elements, so select can't return them. Selectors has the list.

How do I read one attribute?

let doc = parsec::parse("<a href=/x>x</a>", false);
let a = parsec::css::SelectorList::parse("a").unwrap().select(&doc, doc.root())[0];
let href = doc.attrs(a).find(|&(_, name, _)| name == "href").map(|(_, _, v)| v);
assert_eq!(href, Some("/x"));

There's no single-call getter yet.

How do I set innerHTML?

There's no setter. Parse the markup with parse_fragment in the element's context and copy the nodes in; Moving from Lexbor has a helper that does it.

What happens to a node I remove?

That depends on how you took it out. remove is for good: the node and everything in it stay in the document's memory until it's dropped, but their ids read as nothing (no parent, children, attributes, text or markup), and inserting one is EditError::Removed. detach is for moving: the node leaves the tree with its subtree and you can insert it again. In C they're parsec_remove and parsec_detach. See Editing.

Can I share a Document between threads?

Yes. It's Send and Sync today, so you can read it from many threads and move it between them; edits need &mut. That isn't a promise yet: #11 makes it one. See Thread safety and memory safety.

How do I protect a crawler from hostile pages?

Use parse_with with a budget, and check sizes before you parse. Limits and hostile input explains what the budget covers and where Parsec is and isn't linear.

Can I get line and column numbers?

Yes, for nodes, attributes and parse errors. Parse with Options { spans: true, .. } and Document::span, end_span, attr_span and line_col say where each was written; with errors: true, Document::errors() lists the parse errors with line and column. Parsing has both. They're in the Python, C and WASM bindings too.

Can I stream a page in as it downloads?

Yes. For text, parsec::Parser::new(options), then feed(&str) as each piece arrives and finish(). For bytes straight off the network, parsec_encoding::ByteParser does the same and finds the encoding too: it waits only until it knows it (a byte order mark, your HTTP charset, a whole <meta>, or 1,024 bytes), then decodes and parses each piece as it comes. Either way you get the tree the whole page would give, however it was cut. See Encoding.

Is there XPath?

Yes, XPath 1.0, in parsec-xpath (XPath), and from Python (page.xpath("//a/@href"), answering as lxml does), C (parsec_xpath_evaluate) and JavaScript (doc.xpath()). There's no XML parser; Ns::Xml is for trees you build yourself.

Can I use it from C, Python or JavaScript?

From C and Python, yes. C API has the header, the libraries and how to link them, and Moving from Lexbor maps Lexbor's calls to it. bindings/python is a package with selectolax's API, built from git until its wheels go to PyPI with 0.1.0; Python has it all. WebAssembly isn't there yet: #24.

Why does it need a CLA if it's Apache-2.0?

Because the parser is shared with Netweir, which is AGPL-3.0 and also sold under a commercial licence, so contributions here may go there too. You keep your copyright. Contributing has the details.

Where do I ask something that isn't here?

Discussions. Bugs go to Issues, and security problems to the private form in SECURITY.md.

See also

Clone this wiki locally