Repository navigation
Home
Parsec is an HTML parser written in Rust. It reads a page the way a browser does, following the WHATWG HTML Standard, gives you a tree you can walk and change, finds what you're after with CSS selectors from Selectors Level 4, and writes the tree back out as HTML.
It's being built for the people who use Lexbor today, directly or through selectolax, PHP's Dom\HTMLDocument, nokolexbor or lazy_html. Lexbor is fast and follows the spec. What Parsec adds, or plans to, is the list Lexbor's users keep asking for: positions on nodes, a worst case that doesn't blow up, documents you can share across threads, XPath, selectors that match everything a static page can decide, and memory safety.
This wiki is Parsec's only documentation. There's no website and no rustdoc site yet, so the reference pages here list every public item, taken from the source on main.
Note
Parsec isn't released. There's nothing on crates.io yet, and the API can still change before 0.1.0.
You depend on it from git:
[dependencies]
parsec-html = { git = "https://github.com/parsec-html/parsec" }The package is parsec-html; the crate you use is parsec. You need Rust 1.88 or newer.
use parsec::css::SelectorList;
let doc = parsec::parse("<ul><li class=hit>one<li>two</ul>", false);
let hits = SelectorList::parse("li.hit").unwrap().select(&doc, doc.root());
assert_eq!(doc.text(hits[0]), "one");Everything marked ✅ ships on main, and cargo test checks it. The rest has an issue and a milestone, and Roadmap has the order.
| Area | Where it stands | |
|---|---|---|
| ✅ | Whole documents | The HTML Standard's tokenizer and tree builder, scripting on or off. Passes the html5lib tokenizer suite and every web-platform-tests tree-construction case that doesn't need JavaScript; Conformance has the counts. |
| ✅ | Fragments | Parsed in the context of any element as innerHTML does, SVG and MathML included. See Parsing. |
| ✅ | A tree you can walk | Nodes in one arena, addressed by NodeId, with parent, child and sibling links. See The document tree. |
| ✅ | Editing | Create, insert, move and remove nodes; set, add, rename and remove attributes; rename elements. See Editing. |
| ✅ | Serialization |
innerHTML, outerHTML, a start tag alone, or text. See Serialization. |
| ✅ | CSS selectors from Level 4 |
:has(), :is(), :where(), :not() with lists, :nth-child(An+B of S), :scope, :lang(), :dir(), attribute case flags, the form states and validity (:valid, :in-range, :default and the rest); :target and :local-link given the page's URL; queries that stop at the first match, and specificity. See Selectors. |
| ✅ | The tokenizer on its own | Feeding a Sink you write. See Tokenizer. |
| ✅ | Bytes in, encoding sniffed |
parse_bytes finds the encoding from the BOM, the HTTP charset, the <meta> prescan or a fallback, and reparses once if a later <meta> disagrees with a guess. Passes the html5lib encoding/ cases. See Encoding. |
| ✅ | Every encoding the web uses | Decoding and encoding through encoding_rs, Firefox's implementation, passing the web-platform-tests encoding data. See Encoding. |
| ✅ | WHATWG URL |
parsec-url: every getter and setter of URL, URLSearchParams, IDNA, Punycode and Unicode normalization, in a parser of its own that passes all 4,565 web-platform-tests URL cases and beats Ada on real links. See URL. |
| ✅ | A C API | Shared and static libraries, parsec.h, pkg-config and CMake files, with prebuilt packages for Linux, macOS and Windows, x86-64 and ARM, built for each release. Opaque handles, node numbers that can't dangle, and error codes. See C API. |
| ✅ | Limits you choose | A time budget per parse, a maximum tree depth, and a fixed cap on input size. See Limits and hostile input. |
| ✅ | Declarative shadow DOM |
<template shadowrootmode> attaches a shadow root as browsers do, with slots, the flat tree, :host and ::slotted(); all 7,590 WPT declarative shadow DOM cases pass. See Shadow DOM. |
| ✅ | Chunked input |
Parser::feed and finish build exactly the tree the whole page would, tested at every cut of every test input. See Parsing. |
| ✅ | Parse errors | With the HTML Standard's names, byte offset, line and column. See Parsing. |
| ✅ | Source positions | A byte range for every node and attribute, with line and column. See Parsing. |
| ✅ | A Python package | selectolax's API, documents shared across threads, free-threaded Python with the GIL off, plus XPath that answers as lxml's does, positions and parse errors; pytest checks it in CI. See Python. Wheels go to PyPI with 0.1.0. |
| ✅ | WebAssembly | The npm package parsec-html, with TypeScript types, XPath, spans and parse errors; tested in Node and Firefox. See WASM. It goes to npm with 0.1.0. |
| ✅ | XPath | XPath 1.0 in parsec-xpath, shared with Netweir, passing libxml2's expression tests; a work limit stops queries that stay quadratic. See XPath. |
| ✅ | CSS Syntax |
parsec-html-css: the tokenizer, every parser entry point of the current draft with nesting, An+B, <urange> and serialization, with a byte span on every rule, declaration and token. Passes css-parsing-tests but for 12 cases that predate the draft, and every CSS tokenizer test. See CSS. |
| ✅ | Typed CSS values | Every property in the specs (822, generated from w3c/webref), each value parsed against its grammar; units, math functions, CSS Color 4 and most of 5; shorthands into longhands; custom properties and var(). Each value written in the shortest form CSSOM gives it. 14,758 of WPT's 14,893 static CSS parsing cases pass. See CSS values. |
| ✅ | The cascade, media queries, computed values | Origins, layers, specificity, !important and style="" on a Parsec document; @media and @supports against an environment you give; @scope, @container against sizes you give, with style() ranges and container query units, @import through your fetch, @property; @keyframes and @counter-style parsed; computed values as getComputedStyle() writes them, for pseudo-elements too (::before, ::after, ::marker, ::first-line and the rest). All 1,370 of WPT's media query cases pass, and 11,356 of its 12,111 computed-value cases. See Cascade. |
The marks mean the same on every page of this wiki:
- ✅ shipped, and
cargo testchecks it; - 🚧 in progress;
- 📋 planned, with an issue.
Parsec has one dependency (memchr) and one unsafe block. That's a fact about the code rather than something a test checks, so it gets no mark; Thread safety and memory safety explains both. Comparison with Lexbor lays the whole picture out module by module.
Start here
- Getting started: add Parsec, parse, select, read, edit, write out.
- FAQ
- Glossary: the HTML Standard's terms, and Parsec's own, in a sentence or two each.
Reference
-
Parsing:
parse,parse_with,Options,ParseError,MAX_INPUT,parse_fragment, quirks, scripting, input. -
The document tree:
Document,NodeId,Kind,Ns,AttrNs,Quirks, navigation, attributes, templates, the name helpers. -
Editing: every edit function,
EditError, and the rules edits keep. -
Serialization:
inner_html,outer_html,html_alone,text. - Selectors: what parses, what matches, what's refused, and where Lexbor differs.
-
Tokenizer:
Tokenizer,Sink,TextMode,Tag,Attrs,Doctype,preprocess. -
CSS:
parsec-html-css, CSS Syntax Level 3: every entry point, the tree, spans and lines, An+B, serialization, its suite counts and every case it fails. -
Cascade:
parsec_css::cascade,::mediaand::supports: styling a document, media queries,@supports, computed values, the WPT counts and what fails. -
CSS values:
parsec_css::values: the property table, typed values, colors, math functions, shorthands, custom properties andvar(), with WPT's counts and what fails. -
URL:
parsec-url'sUrl,SearchParams, IDNA, Punycode and normalization, how it's built, its WPT counts and its speed. -
Python:
parsec_html, the selectolax-style package:HTMLParser,Node,Attributes, threads, and what differs from selectolax. -
C API:
parsec.h, linking with CMake or pkg-config, ownership and strings, every function and status code.
How it works
- Architecture: the arena, spans into the source, the tokenizer and tree builder, the adoption agency, foreign content.
- Limits and hostile input: the budget, the size cap, and which inputs stay linear.
- Thread safety and memory safety
- Conformance: the suites, the counts, what's skipped and why.
- Benchmarks: Parsec against Lexbor's C and html5ever, page by page, against Lexbor and Ada on URLs, and against Lexbor and cssparser on stylesheets, with the method.
Coming from Lexbor
- Comparison with Lexbor
- Moving from Lexbor: Lexbor's C calls next to Parsec's, in C and in Rust.
The project
- Contributing: the Netweir sync, building, testing, fuzzing, the CLA.
- Roadmap
- Changelog: what's on main, and every release once there is one.
- Getting started, to go from an empty project to a parsed page.
- Glossary, for the HTML Standard's vocabulary.
- Changelog, for what has landed so far.
Parsec is Apache-2.0 and not yet released; these pages describe main. Found something wrong here? Open an issue or ask in Discussions.
Repository · Issues · Discussions · Roadmap · Security policy · Licence