The jsonpath library for Go with low-memory footprint
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Vladimir Hodakov 289c96b1f1
Use another image for Go 1.12 in CI
3 years ago
.drone.yml Use another image for Go 1.12 in CI 3 years ago
.golangci.yaml Fix remaining linter warnings 3 years ago
LICENSE Update LICENSE 3 years ago
README.md Use Go modules, new import path 3 years ago
constants.go Fix golint errors and export all returnable types 3 years ago
eval.go Fix wsl linter warnings 3 years ago
eval_states.go Fix wsl linter warnings 3 years ago
eval_test.go Fix wsl linter warnings 3 years ago
expression.go Fix wsl linter warnings 3 years ago
expression_states.go Fix wsl linter warnings 3 years ago
expression_states_test.go Fix wsl linter warnings 3 years ago
expression_test.go Fix wsl linter warnings 3 years ago
go.mod Add basic linter config, decrease moduled Go version 3 years ago
go.sum Use Go modules, new import path 3 years ago
json_states.go Fix wsl linter warnings 3 years ago
json_states_test.go Fix wsl linter warnings 3 years ago
lexer.go Fix wsl linter warnings 3 years ago
lexer_reader.go Fix wsl linter warnings 3 years ago
lexer_slice.go Fix wsl linter warnings 3 years ago
lexer_test.go Fix wsl linter warnings 3 years ago
misc.go Fix wsl linter warnings 3 years ago
path.go Fix wsl linter warnings 3 years ago
path_states.go Fix remaining linter warnings 3 years ago
path_states_test.go Fix wsl linter warnings 3 years ago
path_test.go Remove dead or unused code 3 years ago
queue.go Fix wsl linter warnings 3 years ago
result.go Fix wsl linter warnings 3 years ago
run.go Fix wsl linter warnings 3 years ago
stack.go Fix wsl linter warnings 3 years ago
stack_test.go Initial commit 4 years ago

README.md

The jsonpath library

jsonpath is used to pull values out of a JSON document without unmarshalling the string into an object. At the loss of post-parse random access and conversion to primitive types, you gain faster return speeds and lower memory utilization. If the value you want is located near the start of the json, the evaluator will terminate after reaching and recording its destination.

The evaluator can be initialized with several paths, so you can retrieve multiple sections of the document with just one scan. Naturally, when all paths have been reached, the evaluator will early terminate.

For each value returned by a path, you'll also get the keys & indexes needed to reach that value. Use the keys flag to view this in the CLI. The Go package will return an []interface{} of length n with indexes 0 - (n-2) being the keys and the value at index n-1.

The history of a library

This fork is owned and currently maintained by WTFTeam. It's based on that one from Jumbo Interactive Limited, which sequentally based/copied from NodePrime/jsonpath Github repository, currently unavailable. The MIT license on this code is inherited from Jumbo Interactive Limited fork, so we can support and maintain this library freely. If there is by any chance someone's proprietary code, you can reach us by abuse <at> wtfteam <dot> pro with details. Unless proved against all code here is licensed under MIT.

Mirrors and development

The main development goes in fat0troll's Gitea. There is an official mirror on GitHub, but we do not guarantee that PRs, opened at GitHub, will be merged.

The canonical import path hosted by giredore, our own Go packages redirector.

Go Package

Start with

go get source.wtfteam.pro/libraries/jsonpath
paths, err := jsonpath.ParsePaths(pathStrings ...string) {
eval, err := jsonpath.EvalPathsInBytes(json []byte, paths) 
// OR
eval, err := jsonpath.EvalPathsInReader(r io.Reader, paths)

then

for {
    if result, ok := eval.Next(); ok {
        fmt.Println(result.Pretty(true)) // true -> show keys in pretty string
    } else {
        break
    }
}
if eval.Error != nil {
    return eval.Error
}

eval.Next() will traverse JSON until another value is found. This has the potential of traversing the entire JSON document in an attempt to find one. If you prefer to have more control over traversing, use the eval.Iterate() method. It will return after every scanned JSON token and return ([]*Result, bool). This array will usually be empty, but occasionally contain results.

Path Syntax

All paths start from the root node $. Similar to getting properties in a JavaScript object, a period .title or brackets ["title"] are used.

Syntax Meaning Examples
$ root of doc
. property selector $.Items
["abc"] quoted property selector $["Items"]
* wildcard property name $.*
[n] Nth index of array [0] [1]
[n:m] Nth index to m-1 index (same as Go slicing) [0:1] [2:5]
[n:] Nth index to end of array [1:] [2:]
[*] wildcard index of array [*]
+ get value at end of path $.title+
?(expression) where clause (expression can reference current json node with @) ?(@.title == "ABC")

Expressions

  • paths (that start from current node @)
  • numbers (integers, floats, scientific notation)
  • mathematical operators (+ - / * ^)
  • numerical comparisos (< <= > >=)
  • logic operators (&& || == !=)
  • parentheses (2 < (3 * 5))
  • static values like (true, false)
  • @.value > 0.5

Example:

{
    "Items":
        [
            {
                "title": "A Midsummer Night's Dream",
                "tags":[
                    "comedy",
                    "shakespeare",
                    "play"
                ]
            },{
                "title": "A Tale of Two Cities",
                "tags":[
                    "french",
                    "revolution",
                    "london"
                ]
            }
        ]
}

Example Paths:

Paths
$.Items[*].title+ ... "A Midsummer Night's Dream" ... "A Tale of Two Cities"

$.Items[*].tags+ ... ["comedy","shakespeare","play"]
... ["french","revolution","london"]

$.Items[*].tags[*]+
... "comedy"
... "shakespeare"
... "play"
... "french"
... "revolution"
... "london"

... = keys/indexes of path