Repository navigation
XPath
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)));-
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::xmlis for an XML tree whose namespaces a host keeps, through theNamespacestrait. -
evaluate(doc, context, variables, namespaces, extensions)runs it from a context node. Variables are(name, XValue)pairs, namespaces(prefix, uri)pairs, andNoExtensionsmeans only the core function library. The result is aValue: a node set ofItems (a node, or an attribute with its owner), a string, a number or a boolean. -
Extensionsadds functions of your own. Netweir registershas-class(),re:test()andre:replace()this way; none of them are inparsec-xpath, which stays standard XPath 1.0.
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.
- 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//divor//p/following::p, is worked out once for the whole set rather than once per node. Over 8,000 nesteddivs,//div//divtakes 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 everypabout every later one. Those stop with an error once they've doneWORK_LIMITunits of work (2^30).evaluate_withintakes a limit of your own. The most any of the benchmark queries used is 1.7 million units.
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.
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)andnode.xpath(...), which answer as lxml's do. See Python. - C:
parsec_xpath_compile,parsec_xpath_evaluateand a result object. See C API. - JavaScript:
doc.xpath(expr)andnode.xpath(expr). See WASM.
- Selectors, for CSS selectors over the same tree.
-
The document tree, for
NodeIdand what a node holds.
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