jsonpath_lib/lib.rs
1//! JsonPath implementation written in Rust.
2//!
3//! # Example
4//! ```
5//! extern crate jsonpath_lib as jsonpath;
6//! #[macro_use] extern crate serde_json;
7//! let json_obj = json!({
8//! "store": {
9//! "book": [
10//! {
11//! "category": "reference",
12//! "author": "Nigel Rees",
13//! "title": "Sayings of the Century",
14//! "price": 8.95
15//! },
16//! {
17//! "category": "fiction",
18//! "author": "Evelyn Waugh",
19//! "title": "Sword of Honour",
20//! "price": 12.99
21//! },
22//! {
23//! "category": "fiction",
24//! "author": "Herman Melville",
25//! "title": "Moby Dick",
26//! "isbn": "0-553-21311-3",
27//! "price": 8.99
28//! },
29//! {
30//! "category": "fiction",
31//! "author": "J. R. R. Tolkien",
32//! "title": "The Lord of the Rings",
33//! "isbn": "0-395-19395-8",
34//! "price": 22.99
35//! }
36//! ],
37//! "bicycle": {
38//! "color": "red",
39//! "price": 19.95
40//! }
41//! },
42//! "expensive": 10
43//! });
44//!
45//! let mut selector = jsonpath::selector(&json_obj);
46//!
47//! assert_eq!(selector("$.store.book[*].author").unwrap(),
48//! vec![
49//! "Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"
50//! ]);
51//!
52//! assert_eq!(selector("$..author").unwrap(),
53//! vec![
54//! "Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"
55//! ]);
56//!
57//! assert_eq!(selector("$.store.*").unwrap(),
58//! vec![
59//! &json!([
60//! { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 },
61//! { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 },
62//! { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 },
63//! { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 }
64//! ]),
65//! &json!({ "color": "red", "price": 19.95 })
66//! ]);
67//!
68//! assert_eq!(selector("$.store..price").unwrap(),
69//! vec![
70//! 8.95, 12.99, 8.99, 22.99, 19.95
71//! ]);
72//!
73//! assert_eq!(selector("$..book[2]").unwrap(),
74//! vec![
75//! &json!({
76//! "category" : "fiction",
77//! "author" : "Herman Melville",
78//! "title" : "Moby Dick",
79//! "isbn" : "0-553-21311-3",
80//! "price" : 8.99
81//! })
82//! ]);
83//!
84//! assert_eq!(selector("$..book[-2]").unwrap(),
85//! vec![
86//! &json!({
87//! "category" : "fiction",
88//! "author" : "Herman Melville",
89//! "title" : "Moby Dick",
90//! "isbn" : "0-553-21311-3",
91//! "price" : 8.99
92//! })
93//! ]);
94//!
95//! assert_eq!(selector("$..book[0,1]").unwrap(),
96//! vec![
97//! &json!({"category" : "reference","author" : "Nigel Rees","title" : "Sayings of the Century","price" : 8.95}),
98//! &json!({"category" : "fiction","author" : "Evelyn Waugh","title" : "Sword of Honour","price" : 12.99})
99//! ]);
100//!
101//! assert_eq!(selector("$..book[:2]").unwrap(),
102//! vec![
103//! &json!({"category" : "reference","author" : "Nigel Rees","title" : "Sayings of the Century","price" : 8.95}),
104//! &json!({"category" : "fiction","author" : "Evelyn Waugh","title" : "Sword of Honour","price" : 12.99})
105//! ]);
106//!
107//! assert_eq!(selector("$..book[:2]").unwrap(),
108//! vec![
109//! &json!({"category" : "reference","author" : "Nigel Rees","title" : "Sayings of the Century","price" : 8.95}),
110//! &json!({"category" : "fiction","author" : "Evelyn Waugh","title" : "Sword of Honour","price" : 12.99})
111//! ]);
112//!
113//! assert_eq!(selector("$..book[?(@.isbn)]").unwrap(),
114//! vec![
115//! &json!({"category" : "fiction","author" : "Herman Melville","title" : "Moby Dick","isbn" : "0-553-21311-3","price" : 8.99}),
116//! &json!({"category" : "fiction","author" : "J. R. R. Tolkien","title" : "The Lord of the Rings","isbn" : "0-395-19395-8","price" : 22.99})
117//! ]);
118//!
119//! assert_eq!(selector("$.store.book[?(@.price < 10)]").unwrap(),
120//! vec![
121//! &json!({"category" : "reference","author" : "Nigel Rees","title" : "Sayings of the Century","price" : 8.95}),
122//! &json!({"category" : "fiction","author" : "Herman Melville","title" : "Moby Dick","isbn" : "0-553-21311-3","price" : 8.99})
123//! ]);
124//! ```
125extern crate array_tool;
126extern crate core;
127extern crate env_logger;
128#[macro_use]
129extern crate log;
130extern crate serde;
131extern crate serde_json;
132
133use serde_json::Value;
134
135pub use parser::Parser; // TODO private
136pub use select::JsonPathError;
137pub use select::{Selector, SelectorMut};
138
139#[doc(hidden)]
140mod ffi;
141#[doc(hidden)]
142mod parser;
143#[doc(hidden)]
144mod select;
145
146/// It is a high-order function. it compile a jsonpath and then returns a closure that has JSON as argument. if you need to reuse a jsonpath, it is good for performance.
147///
148/// ```rust
149/// extern crate jsonpath_lib as jsonpath;
150/// #[macro_use] extern crate serde_json;
151///
152/// let mut first_firend = jsonpath::compile("$..friends[0]");
153///
154/// let json_obj = json!({
155/// "school": {
156/// "friends": [
157/// {"name": "친구1", "age": 20},
158/// {"name": "친구2", "age": 20}
159/// ]
160/// },
161/// "friends": [
162/// {"name": "친구3", "age": 30},
163/// {"name": "친구4"}
164/// ]});
165///
166/// let json = first_firend(&json_obj).unwrap();
167///
168/// assert_eq!(json, vec![
169/// &json!({"name": "친구3", "age": 30}),
170/// &json!({"name": "친구1", "age": 20})
171/// ]);
172/// ```
173pub fn compile(path: &str) -> impl FnMut(&Value) -> Result<Vec<&Value>, JsonPathError> {
174 let node = parser::Parser::compile(path);
175 move |json| match &node {
176 Ok(node) => {
177 let mut selector = Selector::default();
178 selector.compiled_path(node).value(json).select()
179 }
180 Err(e) => Err(JsonPathError::Path(e.to_string())),
181 }
182}
183
184/// It is a high-order function. it returns a closure that has a jsonpath string as argument. you can use diffenent jsonpath for one JSON object.
185///
186/// ```rust
187/// extern crate jsonpath_lib as jsonpath;
188/// #[macro_use] extern crate serde_json;
189///
190/// let json_obj = json!({
191/// "school": {
192/// "friends": [
193/// {"name": "친구1", "age": 20},
194/// {"name": "친구2", "age": 20}
195/// ]
196/// },
197/// "friends": [
198/// {"name": "친구3", "age": 30},
199/// {"name": "친구4"}
200/// ]});
201///
202/// let mut selector = jsonpath::selector(&json_obj);
203///
204/// let json = selector("$..friends[0]").unwrap();
205///
206/// assert_eq!(json, vec![
207/// &json!({"name": "친구3", "age": 30}),
208/// &json!({"name": "친구1", "age": 20})
209/// ]);
210///
211/// let json = selector("$..friends[1]").unwrap();
212///
213/// assert_eq!(json, vec![
214/// &json!({"name": "친구4"}),
215/// &json!({"name": "친구2", "age": 20})
216/// ]);
217/// ```
218#[allow(clippy::needless_lifetimes)]
219pub fn selector<'a>(json: &'a Value) -> impl FnMut(&str) -> Result<Vec<&'a Value>, JsonPathError> {
220 let mut selector = Selector::default();
221 let _ = selector.value(json);
222 move |path: &str| selector.str_path(path)?.reset_value().select()
223}
224
225/// It is the same to `selector` function. but it deserialize the result as given type `T`.
226///
227/// ```rust
228/// extern crate jsonpath_lib as jsonpath;
229/// extern crate serde;
230/// #[macro_use] extern crate serde_json;
231///
232/// use serde::{Deserialize, Serialize};
233///
234/// let json_obj = json!({
235/// "school": {
236/// "friends": [
237/// {"name": "친구1", "age": 20},
238/// {"name": "친구2", "age": 20}
239/// ]
240/// },
241/// "friends": [
242/// {"name": "친구3", "age": 30},
243/// {"name": "친구4"}
244/// ]});
245///
246/// #[derive(Deserialize, PartialEq, Debug)]
247/// struct Friend {
248/// name: String,
249/// age: Option<u8>,
250/// }
251///
252/// let mut selector = jsonpath::selector_as::<Friend>(&json_obj);
253///
254/// let json = selector("$..friends[0]").unwrap();
255///
256/// let ret = vec!(
257/// Friend { name: "친구3".to_string(), age: Some(30) },
258/// Friend { name: "친구1".to_string(), age: Some(20) }
259/// );
260/// assert_eq!(json, ret);
261///
262/// let json = selector("$..friends[1]").unwrap();
263///
264/// let ret = vec!(
265/// Friend { name: "친구4".to_string(), age: None },
266/// Friend { name: "친구2".to_string(), age: Some(20) }
267/// );
268///
269/// assert_eq!(json, ret);
270/// ```
271pub fn selector_as<T: serde::de::DeserializeOwned>(
272 json: &Value,
273) -> impl FnMut(&str) -> Result<Vec<T>, JsonPathError> + '_ {
274 let mut selector = Selector::default();
275 let _ = selector.value(json);
276 move |path: &str| selector.str_path(path)?.reset_value().select_as()
277}
278
279/// It is a simple select function. but it compile the jsonpath argument every time.
280///
281/// ```rust
282/// extern crate jsonpath_lib as jsonpath;
283/// #[macro_use] extern crate serde_json;
284///
285/// let json_obj = json!({
286/// "school": {
287/// "friends": [
288/// {"name": "친구1", "age": 20},
289/// {"name": "친구2", "age": 20}
290/// ]
291/// },
292/// "friends": [
293/// {"name": "친구3", "age": 30},
294/// {"name": "친구4"}
295/// ]});
296///
297/// let json = jsonpath::select(&json_obj, "$..friends[0]").unwrap();
298///
299/// assert_eq!(json, vec![
300/// &json!({"name": "친구3", "age": 30}),
301/// &json!({"name": "친구1", "age": 20})
302/// ]);
303/// ```
304pub fn select<'a>(json: &'a Value, path: &str) -> Result<Vec<&'a Value>, JsonPathError> {
305 Selector::default().str_path(path)?.value(json).select()
306}
307
308pub fn select_with_iter<'a>(
309 json: impl ExactSizeIterator<Item = &'a Value> + 'a,
310 path: &str,
311) -> Result<(Vec<&'a Value>, Vec<usize>), JsonPathError> {
312 let mut selector = Selector::default();
313 let json = selector.str_path(path)?.values_iter(json).select()?;
314
315 let chose_indices = selector.chose_indices();
316
317 Ok((json, chose_indices))
318}
319
320/// It is the same to `select` function but it return the result as string.
321///
322/// ```rust
323/// extern crate jsonpath_lib as jsonpath;
324/// #[macro_use] extern crate serde_json;
325///
326/// let ret = jsonpath::select_as_str(r#"
327/// {
328/// "school": {
329/// "friends": [
330/// {"name": "친구1", "age": 20},
331/// {"name": "친구2", "age": 20}
332/// ]
333/// },
334/// "friends": [
335/// {"name": "친구3", "age": 30},
336/// {"name": "친구4"}
337/// ]
338/// }
339/// "#, "$..friends[0]").unwrap();
340///
341/// assert_eq!(ret, r#"[{"name":"친구3","age":30},{"name":"친구1","age":20}]"#);
342/// ```
343pub fn select_as_str(json_str: &str, path: &str) -> Result<String, JsonPathError> {
344 let json = serde_json::from_str(json_str).map_err(|e| JsonPathError::Serde(e.to_string()))?;
345 let ret = Selector::default().str_path(path)?.value(&json).select()?;
346 serde_json::to_string(&ret).map_err(|e| JsonPathError::Serde(e.to_string()))
347}
348
349/// It is the same to `select` function but it deserialize the the result as given type `T`.
350///
351/// ```rust
352/// extern crate jsonpath_lib as jsonpath;
353/// extern crate serde;
354/// #[macro_use] extern crate serde_json;
355///
356/// use serde::{Deserialize, Serialize};
357///
358/// #[derive(Deserialize, PartialEq, Debug)]
359/// struct Person {
360/// name: String,
361/// age: u8,
362/// phones: Vec<String>,
363/// }
364///
365/// let ret: Vec<Person> = jsonpath::select_as(r#"
366/// {
367/// "person":
368/// {
369/// "name": "Doe John",
370/// "age": 44,
371/// "phones": [
372/// "+44 1234567",
373/// "+44 2345678"
374/// ]
375/// }
376/// }
377/// "#, "$.person").unwrap();
378///
379/// let person = Person {
380/// name: "Doe John".to_string(),
381/// age: 44,
382/// phones: vec!["+44 1234567".to_string(), "+44 2345678".to_string()],
383/// };
384///
385/// assert_eq!(ret[0], person);
386/// ```
387pub fn select_as<T: serde::de::DeserializeOwned>(
388 json_str: &str,
389 path: &str,
390) -> Result<Vec<T>, JsonPathError> {
391 let json = serde_json::from_str(json_str).map_err(|e| JsonPathError::Serde(e.to_string()))?;
392 let t = Selector::default().str_path(path)?.value(&json).select_as();
393
394 t
395}
396
397/// Delete(= replace with null) the JSON property using the jsonpath.
398///
399/// ```rust
400/// extern crate jsonpath_lib as jsonpath;
401/// #[macro_use] extern crate serde_json;
402///
403/// let json_obj = json!({
404/// "school": {
405/// "friends": [
406/// {"name": "친구1", "age": 20},
407/// {"name": "친구2", "age": 20}
408/// ]
409/// },
410/// "friends": [
411/// {"name": "친구3", "age": 30},
412/// {"name": "친구4"}
413/// ]});
414///
415/// let ret = jsonpath::delete(json_obj, "$..[?(20 == @.age)]").unwrap();
416///
417/// assert_eq!(ret, json!({
418/// "school": {
419/// "friends": [
420/// null,
421/// null
422/// ]
423/// },
424/// "friends": [
425/// {"name": "친구3", "age": 30},
426/// {"name": "친구4"}
427/// ]}));
428/// ```
429pub fn delete(value: Value, path: &str) -> Result<Value, JsonPathError> {
430 let mut selector = SelectorMut::default();
431 let value = selector.str_path(path)?.value(value).delete()?;
432 Ok(value.take().unwrap_or(Value::Null))
433}
434
435/// Select JSON properties using a jsonpath and transform the result and then replace it. via closure that implements `FnMut` you can transform the selected results.
436///
437/// ```rust
438/// extern crate jsonpath_lib as jsonpath;
439/// #[macro_use] extern crate serde_json;
440///
441/// use serde_json::Value;
442///
443/// let json_obj = json!({
444/// "school": {
445/// "friends": [
446/// {"name": "친구1", "age": 20},
447/// {"name": "친구2", "age": 20}
448/// ]
449/// },
450/// "friends": [
451/// {"name": "친구3", "age": 30},
452/// {"name": "친구4"}
453/// ]});
454///
455/// let ret = jsonpath::replace_with(json_obj, "$..[?(@.age == 20)].age", &mut |v| {
456/// let age = if let Value::Number(n) = v {
457/// n.as_u64().unwrap() * 2
458/// } else {
459/// 0
460/// };
461///
462/// Some(json!(age))
463/// }).unwrap();
464///
465/// assert_eq!(ret, json!({
466/// "school": {
467/// "friends": [
468/// {"name": "친구1", "age": 40},
469/// {"name": "친구2", "age": 40}
470/// ]
471/// },
472/// "friends": [
473/// {"name": "친구3", "age": 30},
474/// {"name": "친구4"}
475/// ]}));
476/// ```
477pub fn replace_with<F>(value: Value, path: &str, fun: &mut F) -> Result<Value, JsonPathError>
478where
479 F: FnMut(Value) -> Option<Value>,
480{
481 let mut selector = SelectorMut::default();
482 let value = selector.str_path(path)?.value(value).replace_with(fun)?;
483 Ok(value.take().unwrap_or(Value::Null))
484}