xee_xpath/
lib.rs

1#![warn(missing_docs)]
2
3//! This module provides a high level API to use XPath from Rust.
4//!
5//! You can compile XPath expressions into queries using the [`Queries`] store.
6//! For each query you supply a conversion function that turns the result XPath
7//! sequence into a Rust value.
8//!
9//! You can create a [`Documents`] store and load XML documents into it.
10//!
11//! You can also add queries to a [`Queries`] object. You can
12//! then execute queries against the documents store.
13//!
14//! ```rust
15//! use xee_xpath::{Documents, Queries, Query};
16//!
17//! // create a new documents object
18//! let mut documents = Documents::new();
19//! // load a document from a string
20//! let doc = documents.add_string("http://example.com".try_into().unwrap(), "<root>foo</root>").unwrap();
21//!
22//! // create a new queries object
23//! let queries = Queries::default();
24//!
25//! // create a query expecting a single value in the result sequence
26//! // try to convert this value into a Rust `String`
27//! let q = queries.one("/root/string()", |_, item| {
28//!   Ok(item.try_into_value::<String>()?)
29//! })?;
30//!
31//! // when we execute the query, we need to pass a mutable reference to the documents,
32//! // and the item against which we want to query. We can also pass in a document handle,
33//! // as we do here
34//! let r = q.execute(&mut documents, doc)?;
35//! assert_eq!(r, "foo");
36//!
37//! # Ok::<(), xee_xpath::error::Error>(())
38//! ```
39//!
40//! Note that to represent URLs, we use the
41//! [`iri-string`](https://docs.rs/iri-string/latest/iri_string/) crate.
42//! To make an `IriString` from a string, you can use the `try_into` method:
43//!
44//! ```rust
45//! use iri_string::types::IriString;
46//!
47//! let uri: IriString = "http://example.com".try_into().unwrap();
48//! # Ok::<(), xee_xpath::error::Error>(())
49//! ```
50//!
51//! To make an `IriStr` reference, just use `&` on an `IriString`; this is
52//! like the relationship between `String` and `&str`. You can also use the
53//! `try_into` method on a `&str` directly:
54//!
55//! ```rust
56//! use iri_string::types::IriStr;
57//!
58//! let uri: &IriStr = "http://example.com".try_into().unwrap();
59//! # Ok::<(), xee_xpath::error::Error>(())
60//! ```
61
62pub mod atomic;
63pub mod context;
64mod documents;
65pub mod error;
66pub mod function;
67mod itemable;
68pub mod iter;
69mod queries;
70pub mod query;
71
72pub use documents::Documents;
73pub use itemable::Itemable;
74pub use queries::Queries;
75pub use query::{Query, Recurse};
76pub use xee_interpreter::atomic::Atomic;
77pub use xee_interpreter::sequence::{Item, Sequence, SerializationParameters};
78pub use xee_interpreter::xml::DocumentHandle;
xee_xpath/lib.rs

xee_xpath/
lib.rs
