Skip to content

Commit 1910a37

Browse files
codenikocodeniko
committed
update readme
1 parent 34446a1 commit 1910a37

File tree

2 files changed

+129
-3
lines changed

2 files changed

+129
-3
lines changed

‎README.md‎

Lines changed: 128 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,131 @@
11
# JsonPathLite
22
[![Build Status](https://travis-ci.com/codeniko/JsonPathLite.svg?branch=master)](https://travis-ci.com/codeniko/JsonPathLite)
33

4-
A simplified version of [Jayway's JsonPath](https://github.com/json-path/JsonPath) with goals to be lighter in size
5-
and have better performance.
4+
**A lighter and more efficient implementation of JsonPath in Kotlin.**
5+
With functional programming aspects found in langauges like Kotlin, Scala, and streams/lambdas in Java8, this library simplifies other implementations like [Jayway's JsonPath](https://github.com/json-path/JsonPath) by removing *filter operations* and *in-path functions* to focus solely on what matters most: modern fast value extractions from JSON objects. Up to **6x more efficient** in some cases; see [Benchmarks](#benchmarks).
6+
7+
In order to make the library functional programming friendly, JsonPathLite returns *null* rather than throwing exceptions while evaluating a *path* against a JSON object. Throwing exceptions breaks flow control and should be reserved for exceptional errors only.
8+
9+
## Getting started
10+
JsonPathLite is available at the JCenter Repository.
11+
12+
**POM**
13+
```xml
14+
<dependency>
15+
<groupId>com.nfeld.jsonpathlite</groupId>
16+
<artifactId>json-path-lite</artifactId>
17+
<version>1.0.0-SNAPSHOT</version>
18+
</dependency>
19+
```
20+
21+
**Gradle**
22+
```gradle
23+
dependencies {
24+
implementation 'com.nfeld.jsonpathlite:json-path-lite:1.0.0-SNAPSHOT'
25+
}
26+
```
27+
28+
## Accessor operators
29+
30+
| Operator | Description |
31+
| :------------------------ | :----------------------------------------------------------------- |
32+
| `$` | The root element to query. This begins all path expressions. |
33+
| `..` | Deep scan for values behind followed key value accessor |
34+
| `.<name>` | Dot-notated key value accessor for JSON objects |
35+
| `['<name>' (, '<name>')]` | Bracket-notated key value accessor for JSON objects, comma-delimited|
36+
| `[<number> (, <number>)]` | JSON array accessor for index or comma-delimited indices |
37+
| `[start:end]` | JSON array range accessor from start (inclusive) to end (exclusive)|
38+
39+
## Path expression examples
40+
JsonPathLite expressions can use any combination of dot–notation and bracket–notation operators to access JSON values. For examples, these all evaluate to the same result:
41+
```text
42+
$.family.children[0].name
43+
$['family']['children'][0]['name']
44+
$['family'].children[0].name
45+
```
46+
47+
Given the json:
48+
```json
49+
{
50+
"family": {
51+
"children": [{
52+
"name": "Thomas",
53+
"age": 13
54+
},
55+
{
56+
"name": "Mila",
57+
"age": 18
58+
},
59+
{
60+
"name": "Konstantin",
61+
"age": 29
62+
},
63+
{
64+
"name": "Tracy",
65+
"age": 4
66+
}
67+
]
68+
}
69+
}
70+
```
71+
72+
| JsonPath | Result |
73+
| :------- | :----- |
74+
| $.family | The family object |
75+
| $.family.children | The children array |
76+
| $.family['children'] | The children array |
77+
| $.family.children[2] | The second child object |
78+
| $.family.children[-1] | The last child object |
79+
| $.family.children[-3] | The 3rd to last child object |
80+
| $.family.children[1:3] | The 2nd and 3rd children objects |
81+
| $.family.children[:3] | The first three children |
82+
| $.family.children[:-1] | The first three children |
83+
| $.family.children[2:] | The last two children |
84+
| $.family.children[-2:] | The last two children |
85+
| $..name | All names |
86+
| $.family..name | All names nested within family object |
87+
| $.family.children[:3]..age | The ages of first three children |
88+
89+
## Code examples
90+
When parsing a JSON, you have the flexibility to either return null or to throw org.json.JSONException on parsing failure.
91+
```kotlin
92+
val json = "{\"hello\": \"world\"}"
93+
val jsonResult = JsonPath.parseOrNull(json)
94+
jsonResult?.read<String>("$.hello") // returns "world"
95+
jsonResult?.read<Double>("$.otherkey") // returns null
96+
97+
val json2 = "{\"list\": [1,2,3,4]}"
98+
JsonPath.parseOrNull(json2)?.read<List<Int>>("$.list[1:3]") // returns listOf(2, 3)
99+
100+
val json3 = "[{\"outer\": {\"inner\": 1}}]"
101+
JsonPath.parseOrNull(json3)?.read<org.json.JSONObject>("$[0].outer") // returns JSONObject
102+
JsonPath.parseOrNull(json3)?.read<org.json.JSONArray>("$") // returns JSONArray
103+
```
104+
105+
## Benchmarks
106+
These are benchmark tests of JsonPathLite against Jayway's JsonPath implementation. Results for each test is the average of 30 runs with 80,000 reads per run. You can run these test locally with `./runBenchmarks.sh`
107+
108+
**Evaluating/reading path against large JSON**
109+
110+
| Path Tested | JsonPathLite (ms) | JsonPath (ms) |
111+
| :---------- | :------ | :----- |
112+
| $[0]['tags'][3:] | 84 ms | 137 ms |
113+
| $[0]['tags'][0,3, 5] | 62 ms | 141 ms |
114+
| $[2]._id | 22 ms | 61 ms |
115+
| $[0]['tags'][3:5] | 60 ms | 114 ms |
116+
| $[0]['tags'][-3] | 51 ms | 99 ms |
117+
| $[0].friends[1].other.a.b['c'] | 63 ms | 165 ms |
118+
| $..tags | 91 ms | 624 ms |
119+
| $..name | 91 ms | 540 ms |
120+
| $[0]['latitude','longitude', 'isActive'] | 71 ms | 146 ms |
121+
| $[0]['tags'][:3] | 65 ms | 129 ms |
122+
123+
**Compiling JsonPath string to internal tokens**
124+
125+
| Path size | JsonPathLite | JsonPath |
126+
| :-------- | :----------- | :------- |
127+
| short path compile time | 25 ms | 26 ms |
128+
| medium path compile time | 53 ms | 72 ms |
129+
| long path compile time | 119 ms | 175 ms |
130+
131+
[![Analytics](https://ga-beacon.appspot.com/UA-116910991-3/jsonpathlite/index)](https://github.com/igrigorik/ga-beacon)

‎publish.gradle‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ publishing {
2525

2626
pom {
2727
name = 'JsonPathLite'
28-
description = '2019 refresh of Jayway\'s JsonPath with goals to be lighter in size and have better performance.'
28+
description = 'A lighter and more efficient implementation of JsonPath in Kotlin'
2929
url = 'https://github.com/codeniko/JsonPathLite'
3030
licenses {
3131
license {

0 commit comments

Comments
 (0)