Merge pull request #78 from hiltontj/76-norm-paths

[#76] Support Normalized Paths

serde_json_path/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
+## Added: `NormalizedPath` and `PathElement` types ([#78])
+
+The `NormalizedPath` struct represents the location of a node within a JSON object. Its representation is like so:
+
+```rust
+pub struct NormalizedPath<'a>(Vec<PathElement<'a>);
+
+pub enum PathElement<'a> {
+ Name(&'a str),
+ Index(usize),
+}
+```
+
+Several methods were included to interact with a `NormalizedPath`, e.g., `first`, `last`, `get`, `iter`, etc., but notably there is a `to_json_pointer` method, which allows direct conversion to a JSON Pointer to be used with the [`serde_json::Value::pointer`][pointer] or [`serde_json::Value::pointer_mut`][pointer-mut] methods.
+
+[pointer]: https://docs.rs/serde_json/latest/serde_json/enum.Value.html#method.pointer
+[pointer-mut]: https://docs.rs/serde_json/latest/serde_json/enum.Value.html#method.pointer_mut
+
+The new `PathElement` type also comes equipped with several methods, and both it and `NormalizedPath` have eagerly implemented traits from the standard library / `serde` to help improve interoperability.
+
+## Added: `LocatedNodeList` and `LocatedNode` types ([#78])
+
+The `LocatedNodeList` struct was built to have a similar API surface to the `NodeList` struct, but includes additional methods that give access to the location of each node produced by the original query. For example, it has the `locations` and `nodes` methods to provide dedicated iterators over locations or nodes, respectively, but also provides the `iter` method to iterate over the location/node pairs. Here is an example:
+
+```rust
+use serde_json::{json, Value};
+use serde_json_path::JsonPath;
+let value = json!({"foo": {"bar": 1, "baz": 2}});
+let path = JsonPath::parse("$.foo.*")?;
+let query = path.query_located(&value);
+let nodes: Vec<&Value> = query.nodes().collect();
+assert_eq!(nodes, vec![1, 2]);
+let locs: Vec<String> = query
+ .locations()
+ .map(|loc| loc.to_string())
+ .collect();
+assert_eq!(locs, ["$['foo']['bar']", "$['foo']['baz']"]);
+```
+
+The location/node pairs are represented by the `LocatedNode` type.
+
+The `LocatedNodeList` provides one unique bit of functionality over `NodeList`: deduplication of the query results, via the `LocatedNodeList::dedup` and `LocatedNodeList::dedup_in_place` methods.
+
+[#78]: https://github.com/hiltontj/serde_json_path/pull/78
+
+## Other Changes
+
 - **internal**: address new clippy lints in Rust 1.75 ([#75])
 - **internal**: address new clippy lints in Rust 1.74 ([#70])
 - **internal**: code clean-up ([#72])

serde_json_path/src/lib.rs

@@ -10,16 +10,19 @@
 //!
 //! # Features
 //!
-//! This crate provides two key abstractions:
+//! This crate provides three key abstractions:
 //!
 //! * The [`JsonPath`] struct, which represents a parsed JSONPath query.
 //! * The [`NodeList`] struct, which represents the result of a JSONPath query performed on a
-//! [`serde_json::Value`].
+//! [`serde_json::Value`] using the [`JsonPath::query`] method.
+//! * The [`LocatedNodeList`] struct, which is similar to [`NodeList`], but includes the location
+//! of each node in the query string as a [`NormalizedPath`], and is produced by the
+//! [`JsonPath::query_located`] method.
 //!
 //! In addition, the [`JsonPathExt`] trait is provided, which extends the [`serde_json::Value`]
 //! type with the [`json_path`][JsonPathExt::json_path] method for performing JSONPath queries.
 //!
-//! Finally, the [`#[function]`][function] attribute macro allows you to extend your JSONPath
+//! Finally, the [`#[function]`][function] attribute macro can be used to extend JSONPath
 //! queries to use custom functions.
 //!
 //! # Usage
@@ -37,9 +40,11 @@
 //! # }
 //! ```
 //!
-//! You can then use the parsed JSONPath to query a [`serde_json::Value`]. Every JSONPath query
-//! produces a [`NodeList`], which provides several accessor methods that you can use depending on
-//! the nature of your query and its expected output.
+//! You then have two options to query a [`serde_json::Value`] using the parsed JSONPath:
+//! [`JsonPath::query`] or [`JsonPath::query_located`]. The former will produce a [`NodeList`],
+//! while the latter will produce a [`LocatedNodeList`]. The two options provide similar
+//! functionality, but it is recommended to use the former unless you have need of node locations
+//! in the query results.
 //!
 //! ## Querying for single nodes
 //!
@@ -269,14 +274,46 @@
 //! "baz": 1
 //! },
 //! "baz": 2
-//! }
+//! },
+//! "baz": 3,
 //! });
 //! let path = JsonPath::parse("$.foo..baz")?;
 //! let nodes = path.query(&value).all();
 //! assert_eq!(nodes, vec![2, 1]);
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! ## Node locations and `NormalizedPath`
+//!
+//! Should you need to know the locations of the nodes produced by your queries, you can make use
+//! of the [`JsonPath::query_located`] method to perform the query. The resulting
+//! [`LocatedNodeList`] contains both the nodes produced by the query, as well as their locations
+//! represented by their [`NormalizedPath`].
+//!
+//! ```rust
+//! # use serde_json::json;
+//! # use serde_json_path::JsonPath;
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! let value = json!({
+//! "foo": {
+//! "bar": {
+//! "baz": 1
+//! },
+//! "baz": 2
+//! },
+//! "baz": 3,
+//! });
+//! let path = JsonPath::parse("$..[? @.baz == 1]")?;
+//! let location = path
+//! .query_located(&value)
+//! .exactly_one()?
+//! .location()
+//! .to_string();
+//! assert_eq!(location, "$['foo']['bar']");
+//! # Ok(())
+//! # }
+//! ```
 
 #![warn(
  clippy::all,
@@ -328,8 +365,30 @@ pub use error::ParseError;
 pub use ext::JsonPathExt;
 #[doc(inline)]
 pub use path::JsonPath;
+/// A list of nodes resulting from a JSONPath query, along with their locations
+///
+/// This is produced by the [`JsonPath::query_located`] method.
+///
+/// As with [`NodeList`], each node is a borrowed reference to the node in the original
+/// [`serde_json::Value`] that was queried; however, each node in the list is paired with its
+/// location, which is represented by a [`NormalizedPath`].
+///
+/// In addition to the locations, [`LocatedNodeList`] provides useful functionality over [`NodeList`]
+/// such as de-duplication of query results (see [`dedup`][LocatedNodeList::dedup]).
+pub use serde_json_path_core::node::LocatedNodeList;
+#[doc(inline)]
+pub use serde_json_path_core::node::{
+ AtMostOneError, ExactlyOneError, LocatedNode, Locations, NodeList, Nodes,
+};
+/// Represents a [Normalized Path][norm-path] from the JSONPath specification
+///
+/// A [`NormalizedPath`] is used to represent the location of a node within a query result
+/// produced by the [`JsonPath::query_located`] method.
+///
+/// [norm-path]: https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#name-normalized-paths
+pub use serde_json_path_core::path::NormalizedPath;
 #[doc(inline)]
-pub use serde_json_path_core::node::{AtMostOneError, ExactlyOneError, NodeList};
+pub use serde_json_path_core::path::PathElement;
 
 pub use serde_json_path_core::spec::functions;
 

serde_json_path/src/path.rs

@@ -3,7 +3,7 @@ use std::str::FromStr;
 use serde::{de::Visitor, Deserialize, Serialize};
 use serde_json::Value;
 use serde_json_path_core::{
- node::NodeList,
+ node::{LocatedNodeList, NodeList},
  spec::query::{Query, Queryable},
 };
 
@@ -65,8 +65,8 @@ impl JsonPath {
  /// # use serde_json::json;
  /// # use serde_json_path::JsonPath;
  /// # fn main() -> Result<(), serde_json_path::ParseError> {
- /// let path = JsonPath::parse("$.foo[::2]")?;
  /// let value = json!({"foo": [1, 2, 3, 4]});
+ /// let path = JsonPath::parse("$.foo[::2]")?;
  /// let nodes = path.query(&value);
  /// assert_eq!(nodes.all(), vec![1, 3]);
  /// # Ok(())
@@ -75,6 +75,32 @@ impl JsonPath {
  pub fn query<'b>(&self, value: &'b Value) -> NodeList<'b> {
  self.0.query(value, value).into()
  }
+
+ /// Query a [`serde_json::Value`] using this [`JsonPath`] to produce a [`LocatedNodeList`]
+ ///
+ /// # Example
+ /// ```rust
+ /// # use serde_json::{json, Value};
+ /// # use serde_json_path::{JsonPath,NormalizedPath};
+ /// # fn main() -> Result<(), serde_json_path::ParseError> {
+ /// let value = json!({"foo": {"bar": 1, "baz": 2}});
+ /// let path = JsonPath::parse("$.foo.*")?;
+ /// let query = path.query_located(&value);
+ /// let nodes: Vec<&Value> = query.nodes().collect();
+ /// assert_eq!(nodes, vec![1, 2]);
+ /// let locs: Vec<String> = query
+ /// .locations()
+ /// .map(|loc| loc.to_string())
+ /// .collect();
+ /// assert_eq!(locs, ["$['foo']['bar']", "$['foo']['baz']"]);
+ /// # Ok(())
+ /// # }
+ /// ```
+ pub fn query_located<'b>(&self, value: &'b Value) -> LocatedNodeList<'b> {
+ self.0
+ .query_located(value, value, Default::default())
+ .into()
+ }
 }
 
 impl FromStr for JsonPath {

serde_json_path/tests/compliance.rs

@@ -24,7 +24,7 @@ struct TestCase {
 }
 
 #[test]
-fn compliace_test_suite() {
+fn compliance_test_suite() {
  let cts_json_str = fs::read_to_string("../jsonpath-compliance-test-suite/cts.json")
  .expect("read cts.json file");
 
@@ -50,12 +50,25 @@ fn compliace_test_suite() {
  "{name}: parsing {selector:?} should have failed",
  );
  } else {
- let actual = path.expect("valid JSON Path string").query(document).all();
+ let path = path.expect("valid JSON Path string");
  let expected = result.iter().collect::<Vec<&Value>>();
- assert_eq!(
- expected, actual,
- "{name}: incorrect result, expected {expected:?}, got {actual:?}"
- );
+ {
+ // Query using JsonPath::query
+ let actual = path.query(document).all();
+ assert_eq!(
+ expected, actual,
+ "{name}: incorrect result, expected {expected:?}, got {actual:?}"
+ );
+ }
+ {
+ // Query using JsonPath::query_located
+ let q = path.query_located(document);
+ let actual = q.nodes().collect::<Vec<&Value>>();
+ assert_eq!(
+ expected, actual,
+ "(located) {name}: incorrect result, expected {expected:?}, got {actual:?}"
+ );
+ }
  }
  }
 }

serde_json_path_core/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Unreleased
 
+## Added: `NormalizedPath` and `PathElement` types ([#78])
+
+The `NormalizedPath` struct represents the location of a node within a JSON object. Its representation is like so:
+
+```rust
+pub struct NormalizedPath<'a>(Vec<PathElement<'a>);
+
+pub enum PathElement<'a> {
+ Name(&'a str),
+ Index(usize),
+}
+```
+
+Several methods were included to interact with a `NormalizedPath`, e.g., `first`, `last`, `get`, `iter`, etc., but notably there is a `to_json_pointer` method, which allows direct conversion to a JSON Pointer to be used with the [`serde_json::Value::pointer`][pointer] or [`serde_json::Value::pointer_mut`][pointer-mut] methods.
+
+[pointer]: https://docs.rs/serde_json/latest/serde_json/enum.Value.html#method.pointer
+[pointer-mut]: https://docs.rs/serde_json/latest/serde_json/enum.Value.html#method.pointer_mut
+
+The new `PathElement` type also comes equipped with several methods, and both it and `NormalizedPath` have eagerly implemented traits from the standard library / `serde` to help improve interoperability.
+
+## Added: `LocatedNodeList` and `LocatedNode` types ([#78])
+
+The `LocatedNodeList` struct was built to have a similar API surface to the `NodeList` struct, but includes additional methods that give access to the location of each node produced by the original query. For example, it has the `locations` and `nodes` methods to provide dedicated iterators over locations or nodes, respectively, but also provides the `iter` method to iterate over the location/node pairs. Here is an example:
+
+```rust
+use serde_json::{json, Value};
+use serde_json_path::JsonPath;
+let value = json!({"foo": {"bar": 1, "baz": 2}});
+let path = JsonPath::parse("$.foo.*")?;
+let query = path.query_located(&value);
+let nodes: Vec<&Value> = query.nodes().collect();
+assert_eq!(nodes, vec![1, 2]);
+let locs: Vec<String> = query
+ .locations()
+ .map(|loc| loc.to_string())
+ .collect();
+assert_eq!(locs, ["$['foo']['bar']", "$['foo']['baz']"]);
+```
+
+The location/node pairs are represented by the `LocatedNode` type.
+
+The `LocatedNodeList` provides one unique bit of functionality over `NodeList`: deduplication of the query results, via the `LocatedNodeList::dedup` and `LocatedNodeList::dedup_in_place` methods.
+
+[#78]: https://github.com/hiltontj/serde_json_path/pull/78
+
+## Other Changes
+
 - **internal**: address new clippy lints in Rust 1.75 ([#75])
 - **internal**: address new clippy lints in Rust 1.74 and update some tracing instrumentation ([#70])
 - **internal**: code clean-up ([#72])

serde_json_path_core/src/lib.rs

@@ -41,4 +41,5 @@
 #![forbid(unsafe_code)]
 
 pub mod node;
+pub mod path;
 pub mod spec;