Skip to content
James Conway edited this page Nov 19, 2026 · 2 revisions

parsec-xpath is XPath 1.0 over Parsec's document tree. Lexbor has no XPath at all, which is why nokolexbor ported libxml2's to get one (lexbor#23). The engine is shared with Netweir, the way the parser core is: its source is Netweir's crates/netweir-xpath, and scripts/sync-from-netweir.sh copies it here (Contributing).

use parsec_xpath::{Doc, Index, NoExtensions, Value, XPath};

let doc = parsec::parse("<ul><li>a<li class=x>b<li>c</ul>", false);
let index = Index::build(&doc, &[doc.root()]);
let query = XPath::new("count(//li[@class='x']/following-sibling::li)").unwrap();
let n = query.evaluate(Doc::html(&doc, &index), doc.root(), &[], &[], &NoExtensions).unwrap();
assert!(matches!(n, Value::Num(1.0)));

The pieces

  • XPath::new(source) compiles an expression once. Keep it and run it as often as you like; source() gives the text back.
  • Index::build(&doc, roots) puts the tree in document order, once. Pass the document's root, and any subtrees you've detached and still want to query. Build it again after you edit the tree, since a query reads positions from it.
  • Doc::html(&doc, &index) is what a query runs over. Doc::xml is for an XML tree whose namespaces a host keeps, through the Namespaces trait.
  • evaluate(doc, context, variables, namespaces, extensions) runs it from a context node. Variables are (name, XValue) pairs, namespaces (prefix, uri) pairs, and NoExtensions means only the core function library. The result is a Value: a node set of Items (a node, or an attribute with its owner), a string, a number or a boolean.
  • Extensions adds functions of your own. Netweir registers has-class(), re:test() and re:replace() this way; none of them are in parsec-xpath, which stays standard XPath 1.0.

How HTML reads

Names are matched as lxml matches them on HTML: the parser lowercases HTML element and attribute names, and a name test compares exactly, in no namespace. So //div finds the page's <DIV>s and <div>s alike, //DIV finds nothing, and a prefixed name matches nothing. That's not the HTML Standard's reading, which puts HTML elements in the XHTML namespace for XPath; a mode for that could come later, but changing it now would change every Netweir result.

A <template>'s contents are a separate fragment in Parsec's tree, so a query doesn't see inside one. Call doc.adopt_template_contents() before building the index to make them its children, as lxml has them.

Limits

  • Expressions nest at most 256 levels, and walking the tree never recurses, so neither a deep expression nor a deep page can run a thread out of stack.
  • A step from many context nodes, like the second step of //div//div or //p/following::p, is worked out once for the whole set rather than once per node. Over 8,000 nested divs, //div//div takes 0.2 ms; the engine before it took 1.7 s.
  • Some queries stay quadratic however they're run, like //p[following::p], which asks a question of every p about every later one. Those stop with an error once they've done WORK_LIMIT units of work (2^30). evaluate_within takes a limit of your own. The most any of the benchmark queries used is 1.7 million units.

Conformance

libxml2's test/XPath/expr suite runs in cargo test: 231 passed, 0 failed, 12 skipped. The skipped ones test libxml2's own extensions, number literals with an exponent, which XPath 1.0 doesn't have. The suite is vendored in crates/parsec-xpath/tests/libxml2 with its MIT licence and the commit it came from. libxml2's node-set tests (test/XPath/tests) need XML documents and libxml2's dump format, so they aren't run yet.

From Python, C and JavaScript

Each binding keeps the index for you: it's built by the first query after a change and reused until the next. Every node without a parent is a root of it, so a query can start in a removed subtree too.

  • Python: page.xpath(query, **variables) and node.xpath(...), which answer as lxml's do. See Python.
  • C: parsec_xpath_compile, parsec_xpath_evaluate and a result object. See C API.
  • JavaScript: doc.xpath(expr) and node.xpath(expr). See WASM.

See also

Clone this wiki locally