jsonpath_rust/
lib.rs

Help
1//! # Json path
2//! The library provides the basic functionality
3//! to find the slice of data according to the query.
4//! The idea comes from xpath for xml structures.
5//! The details can be found over [`there`]
6//! Therefore JSONPath is a query language for JSON,
7//! similar to XPath for XML. The jsonpath query is a set of assertions to specify the JSON fields that need to be verified.
8//!
9//! # Simple example
10//! Let's suppose we have a following json:
11//! ```json
12//!  {
13//!   "shop": {
14//!    "orders": [
15//!       {"id": 1, "active": true},
16//!       {"id": 2 },
17//!       {"id": 3 },
18//!       {"id": 4, "active": true}
19//!     ]
20//!   }
21//! }
22//! ```
23//! And we pursue to find all orders id having the field 'active'
24//! we can construct the jsonpath instance like that
25//! ```$.shop.orders[?(@.active)].id``` and get the result ``` [1,4] ```
26//!
27//! # Another examples
28//! ```json
29//! { "store": {
30//!     "book": [
31//!       { "category": "reference",
32//!         "author": "Nigel Rees",
33//!         "title": "Sayings of the Century",
34//!         "price": 8.95
35//!       },
36//!       { "category": "fiction",
37//!         "author": "Evelyn Waugh",
38//!         "title": "Sword of Honour",
39//!         "price": 12.99
40//!       },
41//!       { "category": "fiction",
42//!         "author": "Herman Melville",
43//!         "title": "Moby Dick",
44//!         "isbn": "0-553-21311-3",
45//!         "price": 8.99
46//!       },
47//!       { "category": "fiction",
48//!         "author": "J. R. R. Tolkien",
49//!         "title": "The Lord of the Rings",
50//!         "isbn": "0-395-19395-8",
51//!         "price": 22.99
52//!       }
53//!     ],
54//!     "bicycle": {
55//!       "color": "red",
56//!       "price": 19.95
57//!     }
58//!   }
59//! }
60//! ```
61//! and examples
62//! - ``` $.store.book[*].author ``` : the authors of all books in the store
63//! - ``` $..book[?(@.isbn)]``` : filter all books with isbn number
64//! - ``` $..book[?(@.price<10)]``` : filter all books cheapier than 10
65//! - ``` $..*``` : all Elements in XML document. All members of JSON structure
66//! - ``` $..book[0,1]``` : The first two books
67//! - ``` $..book[:2]``` : The first two books
68//!
69//! # Operators
70//!
71//! - `$` : Pointer to the root of the json. It is gently advising to start every jsonpath from the root. Also, inside the filters to point out that the path is starting from the root.
72//! - `@`Pointer to the current element inside the filter operations.It is used inside the filter operations to iterate the collection.
73//! - `*` or `[*]`Wildcard. It brings to the list all objects and elements regardless their names.It is analogue a flatmap operation.
74//! - `<..>`| Descent operation. It brings to the list all objects, children of that objects and etc It is analogue a flatmap operation.
75//! - `.<name>` or `.['<name>']`the key pointing to the field of the objectIt is used to obtain the specific field.
76//! - `['<name>' (, '<name>')]`the list of keysthe same usage as for a single key but for list
77//! - `[<number>]`the filter getting the element by its index.
78//! - `[<number> (, <number>)]`the list if elements of array according to their indexes representing these numbers. |
79//! - `[<start>:<end>:<step>]`slice operator to get a list of element operating with their indexes. By default step = 1, start = 0, end = array len. The elements can be omitted ```[:]```
80//! - `[?(<expression>)]`the logical expression to filter elements in the list.It is used with arrays preliminary.
81//!
82//! # Examples
83//!```rust
84//! use std::str::FromStr;
85//! use serde_json::{json, Value};
86//! use jsonpath_rust::{jp_v, JsonPathValue, JsonPath};
87//!
88//! fn test() -> Result<(), Box<dyn std::error::Error>> {
89//!     let json = serde_json::from_str(r#"{"first":{"second":[{"active":1},{"passive":1}]}}"#)?;
90//!     let path = JsonPath::try_from("$.first.second[?(@.active)]")?;
91//!     let slice_of_data:Vec<JsonPathValue<Value>> = path.find_slice(&json);
92//!     let js = json!({"active":1});
93//!     assert_eq!(slice_of_data, jp_v![&js;"$.first.second[0]",]);
94//!     # Ok(())
95//! }
96//! ```
97//!
98//!
99//! [`there`]: https://goessner.net/articles/JsonPath/
100
101pub use parser::model::JsonPath;
102pub use parser::JsonPathParserError;
103use serde_json::Value;
104use std::fmt::Debug;
105use std::ops::Deref;
106use JsonPathValue::{NewValue, NoValue, Slice};
107
108mod jsonpath;
109pub mod parser;
110pub mod path;
111
112#[macro_use]
113extern crate pest_derive;
114extern crate core;
115extern crate pest;
116
117/// the trait allows to query a path on any value by just passing the &str of as JsonPath.
118///
119/// It is equal to
120/// ```rust
121/// # use serde_json::json;
122/// # use std::str::FromStr;
123/// use jsonpath_rust::JsonPath;
124///
125/// let query = "$.hello";
126/// let json_path = JsonPath::from_str(query).unwrap();
127/// json_path.find(&json!({"hello": "world"}));
128/// ```
129///
130/// It is default implemented for [Value].
131///
132/// #Note:
133/// the result is going to be cloned and therefore it can be significant for the huge queries.
134/// if the same &str is used multiple times, it's more efficient to reuse a single JsonPath.
135///
136/// # Examples:
137/// ```
138/// use std::str::FromStr;
139/// use serde_json::{json, Value};
140/// use jsonpath_rust::jp_v;
141/// use jsonpath_rust::{JsonPathQuery, JsonPath, JsonPathValue};
142///
143/// fn test() -> Result<(), Box<dyn std::error::Error>> {
144///     let json: Value = serde_json::from_str("{}")?;
145///     let v = json.path("$..book[?(@.author size 10)].title")?;
146///     assert_eq!(v, json!([]));
147///
148///     let json: Value = serde_json::from_str("{}")?;
149///     let path = json.path("$..book[?(@.author size 10)].title")?;
150///
151///     assert_eq!(path, json!(["Sayings of the Century"]));
152///
153///     let json: Value = serde_json::from_str("{}")?;
154///     let path = JsonPath::try_from("$..book[?(@.author size 10)].title")?;
155///
156///     let v = path.find_slice(&json);
157///     let js = json!("Sayings of the Century");
158///     assert_eq!(v, jp_v![&js;"",]);
159///     # Ok(())
160/// }
161///
162/// ```
163pub trait JsonPathQuery {
164    fn path(self, query: &str) -> Result<Value, JsonPathParserError>;
165}
166
167/// Json paths may return either pointers to the original json or new data. This custom pointer type allows us to handle both cases.
168/// Unlike JsonPathValue, this type does not represent NoValue to allow the implementation of Deref.
169#[derive(Debug, PartialEq, Clone)]
170pub enum JsonPtr<'a, Data> {
171    /// The slice of the initial json data
172    Slice(&'a Data),
173    /// The new data that was generated from the input data (like length operator)
174    NewValue(Data),
175}
176
177/// Allow deref from json pointer to value.
178impl Deref for JsonPtr<'_, Value> {
179    type Target = Value;
180
181    fn deref(&self) -> &Self::Target {
182        match self {
183            JsonPtr::Slice(v) => v,
184            JsonPtr::NewValue(v) => v,
185        }
186    }
187}
188
189impl JsonPathQuery for Value {
190    fn path(self, query: &str) -> Result<Value, JsonPathParserError> {
191        let p = JsonPath::try_from(query)?;
192        Ok(p.find(&self))
193    }
194}
195
196/*
197impl<T> JsonPathQuery for T
198    where T: Deref<Target=Value> {
199    fn path(self, query: &str) -> Result<Value, String> {
200        let p = JsonPath::from_str(query)?;
201        Ok(p.find(self.deref()))
202    }
203}
204 */
205
206/// just to create a json path value of data
207/// Example:
208///  - `jp_v(&json) = JsonPathValue::Slice(&json)`
209///  - `jp_v(&json;"foo") = JsonPathValue::Slice(&json, "foo".to_string())`
210///  - `jp_v(&json,) = vec![JsonPathValue::Slice(&json)]`
211///  - `jp_v[&json1,&json1] = vec![JsonPathValue::Slice(&json1),JsonPathValue::Slice(&json2)]`
212///  - `jp_v(json) = JsonPathValue::NewValue(json)`
213/// ```
214/// use std::str::FromStr;
215/// use serde_json::{json, Value};
216/// use jsonpath_rust::{jp_v, JsonPathQuery, JsonPath, JsonPathValue};
217///
218/// fn test() -> Result<(), Box<dyn std::error::Error>> {
219///     let json: Value = serde_json::from_str("{}")?;
220///     let path = JsonPath::try_from("$..book[?(@.author size 10)].title")?;
221///     let v = path.find_slice(&json);
222///
223///     let js = json!("Sayings of the Century");
224///     assert_eq!(v, jp_v![&js;"",]);
225///     # Ok(())
226/// }
227/// ```
228#[macro_export]
229macro_rules! jp_v {
230    (&$v:expr) =>{
231        JsonPathValue::Slice(&$v, String::new())
232    };
233
234    (&$v:expr ; $s:expr) =>{
235        JsonPathValue::Slice(&$v, $s.to_string())
236    };
237
238    ($(&$v:expr;$s:expr),+ $(,)?) =>{
239        {
240            vec![
241                $(
242                    jp_v!(&$v ; $s),
243                )+
244            ]
245        }
246    };
247
248    ($(&$v:expr),+ $(,)?) => {
249        {
250            vec![
251                $(
252                    jp_v!(&$v),
253                )+
254            ]
255        }
256    };
257
258    ($v:expr) =>{
259        JsonPathValue::NewValue($v)
260    };
261
262}
263
264/// Represents the path of the found json data
265pub type JsonPathStr = String;
266
267pub fn jsp_idx(prefix: &str, idx: usize) -> String {
268    format!("{}[{}]", prefix, idx)
269}
270pub fn jsp_obj(prefix: &str, key: &str) -> String {
271    format!("{}.['{}']", prefix, key)
272}
273
274/// A result of json path
275/// Can be either a slice of initial data or a new generated value(like length of array)
276#[derive(Debug, PartialEq, Clone)]
277pub enum JsonPathValue<'a, Data> {
278    /// The slice of the initial json data
279    Slice(&'a Data, JsonPathStr),
280    /// The new data that was generated from the input data (like length operator)
281    NewValue(Data),
282    /// The absent value that indicates the input data is not matched to the given json path (like the absent fields)
283    NoValue,
284}
285
286impl<'a, Data: Clone + Debug + Default> JsonPathValue<'a, Data> {
287    /// Transforms given value into data either by moving value out or by cloning
288    pub fn to_data(self) -> Data {
289        match self {
290            Slice(r, _) => r.clone(),
291            NewValue(val) => val,
292            NoValue => Data::default(),
293        }
294    }
295
296    /// Transforms given value into path
297    pub fn to_path(self) -> Option<JsonPathStr> {
298        match self {
299            Slice(_, path) => Some(path),
300            _ => None,
301        }
302    }
303
304    pub fn from_root(data: &'a Data) -> Self {
305        Slice(data, String::from("$"))
306    }
307    pub fn new_slice(data: &'a Data, path: String) -> Self {
308        Slice(data, path.to_string())
309    }
310}
311
312impl<'a, Data> JsonPathValue<'a, Data> {
313    pub fn only_no_value(input: &[JsonPathValue<'a, Data>]) -> bool {
314        !input.is_empty() && input.iter().filter(|v| v.has_value()).count() == 0
315    }
316
317    pub fn map_vec(data: Vec<(&'a Data, JsonPathStr)>) -> Vec<JsonPathValue<'a, Data>> {
318        data.into_iter()
319            .map(|(data, pref)| Slice(data, pref))
320            .collect()
321    }
322
323    pub fn map_slice<F>(self, mapper: F) -> Vec<JsonPathValue<'a, Data>>
324    where
325        F: FnOnce(&'a Data, JsonPathStr) -> Vec<(&'a Data, JsonPathStr)>,
326    {
327        match self {
328            Slice(r, pref) => mapper(r, pref)
329                .into_iter()
330                .map(|(d, s)| Slice(d, s))
331                .collect(),
332
333            NewValue(_) => vec![],
334            no_v => vec![no_v],
335        }
336    }
337
338    pub fn flat_map_slice<F>(self, mapper: F) -> Vec<JsonPathValue<'a, Data>>
339    where
340        F: FnOnce(&'a Data, JsonPathStr) -> Vec<JsonPathValue<'a, Data>>,
341    {
342        match self {
343            Slice(r, pref) => mapper(r, pref),
344            _ => vec![NoValue],
345        }
346    }
347
348    pub fn has_value(&self) -> bool {
349        !matches!(self, NoValue)
350    }
351
352    pub fn vec_as_data(input: Vec<JsonPathValue<'a, Data>>) -> Vec<&'a Data> {
353        input
354            .into_iter()
355            .filter_map(|v| match v {
356                Slice(el, _) => Some(el),
357                _ => None,
358            })
359            .collect()
360    }
361    pub fn vec_as_pair(input: Vec<JsonPathValue<'a, Data>>) -> Vec<(&'a Data, JsonPathStr)> {
362        input
363            .into_iter()
364            .filter_map(|v| match v {
365                Slice(el, v) => Some((el, v)),
366                _ => None,
367            })
368            .collect()
369    }
370
371    /// moves a pointer (from slice) out or provides a default value when the value was generated
372    pub fn slice_or(self, default: &'a Data) -> &'a Data {
373        match self {
374            Slice(r, _) => r,
375            NewValue(_) | NoValue => default,
376        }
377    }
378}
379
380#[cfg(test)]
381mod tests {
382    use serde_json::Value;
383
384    use crate::JsonPath;
385    use std::str::FromStr;
386
387    #[test]
388    fn to_string_test() {
389        let path: Box<JsonPath<Value>> = Box::from(
390            JsonPath::from_str(
391                "$.['a'].a..book[1:3][*][1]['a','b'][?(@)][?(@.verb == 'TEST')].a.length()",
392            )
393            .unwrap(),
394        );
395
396        assert_eq!(
397            path.to_string(),
398            "$.'a'.'a'..book[1:3:1][*][1]['a','b'][?(@ exists )][?(@.'verb' == \"TEST\")].'a'.length()"
399        );
400    }
401}
jsonpath_rust/lib.rs

jsonpath_rust/
lib.rs
