xmloxide 0.4.2

A pure Rust reimplementation of libxml2 — memory-safe XML/HTML parsing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

//! `XPath` 1.0 query language implementation.
//!
//! This module provides an implementation of the `XPath` 1.0 specification
//! (<https://www.w3.org/TR/xpath-10/>), including expression parsing and
//! evaluation against an XML document tree.
//!
//! # Quick Start
//!
//! ```
//! use xmloxide::Document;
//! use xmloxide::xpath::{evaluate, XPathValue};
//!
//! let doc = Document::parse_str("<root><a>1</a><b>2</b></root>").unwrap();
//! let root = doc.root_element().unwrap();
//! let result = evaluate(&doc, root, "count(*)").unwrap();
//! assert_eq!(result.to_number(), 2.0);
//! ```
//!
//! # Known Limitations
//!
//! - The `namespace::` axis returns the element's `NodeId` when in-scope
//!   namespaces match (following the same pattern as the attribute axis).
//!   Namespace nodes are not materialized as separate tree nodes.
//!
//! # Submodules
//!
//! - [`ast`]: Abstract syntax tree types for parsed `XPath` expressions.
//! - [`lexer`]: Tokenizer for `XPath` expression strings.
//! - [`types`]: `XPath` value types and comparison helpers.
//! - [`parser`]: Recursive descent parser for `XPath` expressions.
//! - [`eval`]: Expression evaluator against a document tree.

pub mod ast;
pub mod eval;
pub mod lexer;
pub mod parser;
pub(crate) mod regex;
pub mod types;

pub use eval::XPathContext;
pub use types::{XPathError, XPathValue};

use crate::tree::{Document, NodeId};

/// Evaluates an `XPath` 1.0 expression against a document node.
///
/// This is a convenience function that parses the expression and evaluates it
/// in a single call. For evaluating the same expression against multiple
/// context nodes, use [`parser::parse`] and [`XPathContext::evaluate`]
/// separately to avoid re-parsing.
///
/// # Examples
///
/// ```
/// use xmloxide::Document;
/// use xmloxide::xpath::{evaluate, XPathValue};
///
/// let doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
/// let root = doc.root_element().unwrap();
///
/// // Count child elements
/// let result = evaluate(&doc, root, "count(*)").unwrap();
/// assert_eq!(result.to_number(), 1.0);
///
/// // Get text content
/// let result = evaluate(&doc, root, "string(child)").unwrap();
/// assert_eq!(result.to_xpath_string(), "Hello");
/// ```
///
/// # Errors
///
/// Returns [`XPathError`] if the expression is malformed or evaluation fails.
pub fn evaluate(
    doc: &Document,
    context_node: NodeId,
    expression: &str,
) -> Result<XPathValue, XPathError> {
    let expr = parser::parse(expression)?;
    let ctx = XPathContext::new(doc, context_node);
    ctx.evaluate(&expr)
}