Skip to main content

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}