[#76] Support Normalized Paths

[hiltontj]

Closes #76.

This PR introduces support for Normalized Paths.

These can be accessed by a new query method JsonPath::query_located, which produces a LocatedNodeList. The LocatedNodeList is similar to NodeList, but contains the location of each node produced by the query, represented using the NormalizedPath type.

All new code has been documented with examples in this PR.

Added: NormalizedPath and PathElement types

The NormalizedPath struct represents the location of a node within a JSON object. Its representation is like so:

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 as_json_pointer method, which allows direct conversion to a JSON Pointer to be used with the serde_json::Value::pointer or serde_json::Value::pointer_mut methods.

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

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:

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.

Implementation Notes

The JsonPath::query_located method adds a completely separate function to perform queries in addition to the original JsonPath::query method. Their implementation of query execution is also completely separate, via the Queryable trait's query (existing) and query_located (new) methods, respectively. This was done, as opposed to, e.g., modifying the original query function to include locations, because I did not want to incur the overhead of producing the locations by default.

TODOs

• Changelog
• Interop/API Guidelines check
• Some remaining code docs
  • LocatedNodeList::iter

[tisonkun]

If the paths are already ordered, maybe we can call dedup directly?

[tisonkun]

I can see that you may want to mean that, although the elements can be unordered, the result of the same segment are grouped.

But how can we ensure that the unstable sort won't compare two elements of different group (in descendant query)?

[tisonkun]

For example:

fn main() {
    let value = json!({
      "o": {"k": [{"j": 1, "k": 2}]},
      "a": [5, 3, [{"j": 4}, {"k": 6}]]
    });
    let path = JsonPath::parse(r#"$["a", "o"]..[0, 1]"#).unwrap();
    let nodes = path.query_located(&value);
    let nodes = path.query_located(&value).dedup();
}

// ["$['a'][0]", "$['a'][1]", "$['a'][2][0]", "$['a'][2][1]", "$['o']['k'][0]"]

If the sorter compare "$['a'][0]" with "$['o']['k'][0]", it would cause panic.

[tisonkun]

In the other direction, we may sort PathElement with names always greater than index, to make it a total order. Is there some downside I miss?

[tisonkun]

We still have this from impl and the TODO indicates that this can be unsafe holds.

[tisonkun]

Hello @hiltontj! Thanks for providing such a useful crate.

Just for your information, I'm porting this crate to fit in the requirements of generic variant data type - /~https://github.com/cratesland/spath/

Now I'm going through this crate and do some reviews randomly. Hopefully it helps.

[hiltontj]

Hey @tisonkun - thank you!

Just for your information, I'm porting this crate to fit in the requirements of generic variant data type - /~https://github.com/cratesland/spath/

That looks really interesting, glad you could make use of serde_json_path.

Now I'm going through this crate and do some reviews randomly. Hopefully it helps.

I am grateful for the feedback 🙏