arb/xpath.rs
1//! Native XPath front-end for `source { … }` / `out { … }` bodies. A body
2//! command whose first token starts with `/`, `//`, or `@` is an XPath literal.
3//!
4//! **This is a real XPath 1.0 engine**, not a translation layer:
5//! [`crate::xpath_syntax`] lexes and parses the full grammar of the W3C
6//! Recommendation (<https://www.w3.org/TR/1999/REC-xpath-19991116/>) and
7//! [`crate::xpath_eval`] evaluates it over the parsed document — all 13 axes,
8//! all four node tests, predicates with correct proximity positions, and the
9//! 27-function core library.
10//!
11//! It replaces a translator that compiled XPath-shaped syntax to a CSS selector.
12//! That approach could not carry an axis or a function at all, and it did worse
13//! than refuse them: it compiled a ROOTED path `/li/text()` to the CSS
14//! descendant selector `li`, so a path XPath says selects NOTHING answered with
15//! three nodes and exit 0. `[@a='x' or @a='y']` and a chained predicate
16//! `[@a='x'][@b='y']` went the other way, answering EMPTY where XPath selects
17//! nodes. A wrong answer under a success exit is the one outcome SPEC §8 rules
18//! out, and the four are pinned in `tests/xpath.rs` against `xmllint`.
19//!
20//! ## Where the expression is evaluated
21//!
22//! arb's pipeline is a LINE stream, and an XPath step can appear either as a
23//! whole query or as one stage of a chain (`//div[@class='card']` then `@href`).
24//! So the context follows the expression's own shape, which is XPath's rule
25//! already:
26//!
27//! * An ABSOLUTE expression (`/…`, `//…`) is evaluated ONCE over the whole
28//! stream parsed as one document, because `/` means the document root.
29//! * A RELATIVE expression (`@href`, `text()`, `a/b`, `count(p)`) is evaluated
30//! PER LINE with the context node set to that line's first element, so it
31//! composes with whatever step produced those lines.
32
33use crate::query::QueryOp;
34use crate::xpath_syntax::{self, Expr, PathStart};
35
36/// Parse an XPath literal, or report why it is not one.
37///
38/// Parsing happens HERE, at spec-build time, so a malformed expression is a hard
39/// error before any input is read — never a silent empty node-set at run time.
40pub fn translate(src: &str) -> Result<Vec<QueryOp>, String> {
41 let s = src.trim();
42 if s.is_empty() {
43 return Err("xpath: empty expression".into());
44 }
45 // A jq FORMAT STRING also starts with `@`, and the body dispatcher sends
46 // every leading-`@` command here. Read as an attribute step, `@base64`
47 // would select an attribute nobody has and yield an empty result with a
48 // ZERO exit — a jq construct silently answering "nothing" instead of
49 // erroring, which is precisely what SPEC §8 rules out. The format names are
50 // a closed set, so name them and refuse. (An element really carrying an
51 // attribute with one of these names is still reachable through the native
52 // `attr` verb, which is not `@`-dispatched.)
53 if let Some(rest) = s.strip_prefix('@') {
54 if crate::jqlang::FORMAT_NAMES.contains(&rest) {
55 return Err(format!(
56 "xpath: `@{rest}` is a jq format string, which is outside the \
57 supported subset (a leading `@` here is an xpath attribute step; \
58 use `attr {rest}` for a literal attribute of that name)"
59 ));
60 }
61 }
62 // A bare NCName is a legal XPath relative location path (`bogus` is
63 // `child::bogus`), and at COMMAND position that is a trap: a typo'd arb verb
64 // would parse, select nothing, and exit 0 — the silent answer this engine
65 // exists to remove, reintroduced through the front door. So an expression
66 // reaching arb's command position must carry a character only XPath uses.
67 //
68 // Nothing becomes unreachable: the same step is spelled `//bogus`,
69 // `./bogus` or `child::bogus`, any of which is unambiguous. This is the
70 // `keys`/`names` rule again — a language does not get to claim a spelling
71 // another meaning already owns.
72 if !s.contains(['/', '@', ':', '(', '[', '|']) {
73 return Err(format!(
74 "xpath: `{src}` has no xpath-only syntax, so it is read as a verb name (spell the step `//{src}`, `./{src}` or `child::{src}` to force xpath)"
75 ));
76 }
77 let expr = xpath_syntax::parse(s).map_err(|e| format!("xpath: {e} in `{src}`"))?;
78 // Only a RELATIVE LOCATION PATH composes with a previous pipeline step, and
79 // only it is evaluated per line. Everything else — an absolute path, a
80 // function call, a comparison — is one question about the DOCUMENT and is
81 // answered once. Deciding this from the source text instead (a leading `/`)
82 // made `count(//p)` run once per input line and print eight separate counts.
83 //
84 // A UNION follows its branches rather than being document-scoped outright:
85 // `@href|@id` is two relative paths and composes exactly as `@href` does,
86 // and treating it as one document question left both branches with no
87 // context node, so it answered NOTHING while either branch alone answered.
88 let per_line = is_relative_location(&expr);
89 Ok(vec![QueryOp::XPath(Box::new(XPath {
90 src: s.to_string(),
91 expr,
92 per_line,
93 }))])
94}
95
96/// A compiled XPath expression, carried by the query op.
97#[derive(Debug, Clone)]
98pub struct XPath {
99 pub src: String,
100 pub expr: Expr,
101 /// Whether to evaluate once per input line (see the module docs).
102 pub per_line: bool,
103}
104
105impl XPath {
106 /// Evaluate over the current stream lines, returning the output lines.
107 pub fn run(&self, lines: &[String]) -> Result<Vec<String>, String> {
108 use crate::xpath_eval::{eval, render, Doc};
109 if !self.per_line {
110 let doc = Doc::parse(&lines.join("\n"));
111 let v = eval(&doc, &self.expr, doc.root())
112 .map_err(|e| format!("xpath: {e} in `{}`", self.src))?;
113 return Ok(render(&doc, &v));
114 }
115 // Relative: one evaluation per line, context = that line's first
116 // element, so a chain like `//a` then `@href` behaves as it reads.
117 let mut out = Vec::new();
118 for l in lines {
119 let doc = Doc::parse(l);
120 let ctx = first_element(&doc).unwrap_or_else(|| doc.root());
121 let v =
122 eval(&doc, &self.expr, ctx).map_err(|e| format!("xpath: {e} in `{}`", self.src))?;
123 out.extend(render(&doc, &v));
124 }
125 Ok(out)
126 }
127}
128
129/// The first element of a re-parsed fragment, skipping the `html`/`body`
130/// wrappers the parser inserts around one. That is the node a previous pipeline
131/// step actually produced.
132fn first_element(doc: &crate::xpath_eval::Doc) -> Option<crate::xpath_eval::XNode> {
133 use crate::xpath_eval::{Kind, XNode};
134 let mut best: Option<XNode> = None;
135 for n in doc.document_nodes() {
136 if doc.kind(n) == Kind::Element {
137 let name = doc.name(n).unwrap_or_default();
138 if name == "html" || name == "body" || name == "head" {
139 continue;
140 }
141 best = Some(n);
142 break;
143 }
144 }
145 best
146}
147
148/// Whether `e` is a relative location path — including a union of them.
149///
150/// A union is only document-scoped when a branch is: `//@href|//@id` asks about
151/// the document, while `@href|@id` is two relative steps and has to be evaluated
152/// against each line's context node like any other relative path. A MIXED union
153/// stays document-scoped, which is the conservative reading — there is one
154/// context and the absolute branch does not want it.
155fn is_relative_location(e: &Expr) -> bool {
156 match e {
157 Expr::Path(PathStart::Relative, _) => true,
158 Expr::Union(a, b) => is_relative_location(a) && is_relative_location(b),
159 _ => false,
160 }
161}
162
163#[cfg(test)]
164mod tests {
165 use super::*;
166 use crate::query::{eval, QueryResult};
167
168 /// Render an xpath literal over one HTML document, returning the lines.
169 fn run(src: &str, html: &str) -> Vec<String> {
170 match eval(&translate(src).unwrap(), &[html.to_string()], 0.0) {
171 QueryResult::Lines(v) => v,
172 other => panic!("expected Lines, got {other:?}"),
173 }
174 }
175
176 #[test]
177 fn descendant_and_child_paths() {
178 let doc = "<html><body><div><span>A</span></div><span>B</span></body></html>";
179 assert_eq!(run("//span/text()", doc), vec!["A", "B"]);
180 assert_eq!(run("//div/span/text()", doc), vec!["A"]);
181 assert_eq!(run("/html/body/span/text()", doc), vec!["B"]);
182 }
183
184 #[test]
185 fn attr_predicate_and_accessors() {
186 let doc = "<div><a href=\"x\">1</a><a href=\"y\">2</a></div>";
187 assert_eq!(run("//a/@href", doc), vec!["x", "y"]);
188 assert_eq!(run("//a/text()", doc), vec!["1", "2"]);
189 // A path step then a standalone attr step (two ops) is the same result.
190 let two = [translate("//a").unwrap(), translate("@href").unwrap()].concat();
191 match eval(&two, &[doc.to_string()], 0.0) {
192 QueryResult::Lines(v) => assert_eq!(v, vec!["x", "y"]),
193 other => panic!("{other:?}"),
194 }
195 }
196
197 #[test]
198 fn a_malformed_expression_is_a_parse_error_not_an_empty_answer() {
199 for bad in [
200 "//a[", // unclosed predicate
201 "//a[@href", // unclosed predicate
202 "count(", // unclosed call
203 "//a[@class=btn", // unterminated
204 "'unterminated", // unterminated literal
205 "//a!", // stray `!`
206 "//a/@href extra", // trailing junk
207 "//nosuchfn()", // not a node type
208 "//bogus-axis::a", // not an axis
209 "", // empty
210 ] {
211 assert!(translate(bad).is_err(), "expected `{bad}` to be refused");
212 }
213 }
214}