mirror
/
gjson
mirror of https://github.com/tidwall/gjson.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

Fix typos and style

This commit is contained in:
ccoVeille 2024-04-23 13:59:52 +02:00
parent 49fb81dad1
commit c12548f200
No known key found for this signature in database
4 changed files with 53 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -14,7 +14,7 @@
GJSON is a Go package that provides a [fast](#performance) and [simple](#get-a-value) way to get values from a JSON document. GJSON is a Go package that provides a [fast](#performance) and [simple](#get-a-value) way to get values from a JSON document.
It has features such as [one line retrieval](#get-a-value), [dot notation paths](#path-syntax), [iteration](#iterate-through-an-object-or-array), and [parsing JSON lines](#json-lines). It has features such as [one line retrieval](#get-a-value), [dot notation paths](#path-syntax), [iteration](#iterate-through-an-object-or-array), and [parsing JSON lines](#json-lines).
Also check out [SJSON](https://github.com/tidwall/sjson) for modifying JSON, and the [JJ](https://github.com/tidwall/jj) command line tool. Also check out [SJSON](https://github.com/tidwall/sjson) for modifying JSON, and the [JJ](https://github.com/tidwall/jj) command-line tool.
This README is a quick overview of how to use GJSON, for more information check out [GJSON Syntax](SYNTAX.md). This README is a quick overview of how to use GJSON, for more information check out [GJSON Syntax](SYNTAX.md).
@ -58,7 +58,7 @@ Prichard
## Path Syntax ## Path Syntax
Below is a quick overview of the path syntax, for more complete information please Below is a quick overview of the path syntax, for further information please
check out [GJSON Syntax](SYNTAX.md). check out [GJSON Syntax](SYNTAX.md).
A path is a series of keys separated by a dot. A path is a series of keys separated by a dot.
@ -107,9 +107,9 @@ friends.#(first!%"D*").last >> "Craig"
friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"] friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"]
``` ```
*Please note that prior to v1.3.0, queries used the `#[...]` brackets. This was *Please note that before v1.3.0, queries used the `#[...]` brackets. This was
changed in v1.3.0 as to avoid confusion with the new changed in v1.3.0 as to avoid confusion with the new
[multipath](SYNTAX.md#multipaths) syntax. For backwards compatibility, [multi-paths](SYNTAX.md#multi-paths) syntax. For backwards compatibility,
`#[...]` will continue to work until the next major release.* `#[...]` will continue to work until the next major release.*
## Result Type ## Result Type
@ -137,7 +137,7 @@ result.Index // index of raw value in original json, zero means index u
result.Indexes // indexes of all the elements that match on a path containing the '#' query character. result.Indexes // indexes of all the elements that match on a path containing the '#' query character.
``` ```
There are a variety of handy functions that work on a result: These are a variety of handy functions that work on a result:
```go ```go
result.Exists() bool result.Exists() bool
@ -201,7 +201,7 @@ These are currently the following built-in modifiers:
- `@reverse`: Reverse an array or the members of an object. - `@reverse`: Reverse an array or the members of an object.
- `@ugly`: Remove all whitespace from a JSON document. - `@ugly`: Remove all whitespace from a JSON document.
- `@pretty`: Make the JSON document more human readable. - `@pretty`: Make the JSON document more human-readable.
- `@this`: Returns the current element. It can be used to retrieve the root element. - `@this`: Returns the current element. It can be used to retrieve the root element.
- `@valid`: Ensure the JSON document is valid. - `@valid`: Ensure the JSON document is valid.
- `@flatten`: Flattens an array. - `@flatten`: Flattens an array.
@ -269,7 +269,7 @@ gjson.AddModifier("case", func(json, arg string) string {
## JSON Lines ## JSON Lines
There's support for [JSON Lines](http://jsonlines.org/) using the `..` prefix, which treats a multilined document as an array. There's support for [JSON Lines](http://jsonlines.org/) using the `..` prefix, which treats a multi-lined document as an array.
For example: For example:
@ -353,7 +353,7 @@ result.ForEach(func(key, value gjson.Result) bool {
There's a `Parse(json)` function that will do a simple parse, and `result.Get(path)` that will search a result. There's a `Parse(json)` function that will do a simple parse, and `result.Get(path)` that will search a result.
For example, all of these will return the same result: For example, these will return the same result:
```go ```go
gjson.Parse(json).Get("name").Get("last") gjson.Parse(json).Get("name").Get("last")
@ -381,9 +381,9 @@ if gjson.Get(json, "name.last").Exists() {
## Validate JSON ## Validate JSON
The `Get*` and `Parse*` functions expects that the JSON is well-formed. Bad JSON will not panic, but it may return back unexpected results. The `Get*` and `Parse*` functions expects that the JSON is well-formed. Bad JSON will not panic, but it may return unexpected results.
If you are consuming JSON from an unpredictable source then you may want to validate prior to using GJSON. If you are consuming JSON from an unpredictable source then you may want to validate before using GJSON.
```go ```go
if !gjson.Valid(json) { if !gjson.Valid(json) {
@ -412,7 +412,7 @@ var json []byte = ...
result := gjson.GetBytes(json, path) result := gjson.GetBytes(json, path)
``` ```
If you are using the `gjson.GetBytes(json, path)` function and you want to avoid converting `result.Raw` to a `[]byte`, then you can use this pattern: If you are using the `gjson.GetBytes(json, path)` function, and you want to avoid converting `result.Raw` to a `[]byte`, then you can use this pattern:
```go ```go
var json []byte = ... var json []byte = ...

34
SYNTAX.md
View File

@ -10,9 +10,9 @@ This document is designed to explain the structure of a GJSON Path through examp
- [Escape Character](#escape-character) - [Escape Character](#escape-character)
- [Arrays](#arrays) - [Arrays](#arrays)
- [Queries](#queries) - [Queries](#queries)
- [Dot vs Pipe](#dot-vs-pipe) - [Dot vs. Pipe](#dot-vs-pipe)
- [Modifiers](#modifiers) - [Modifiers](#modifiers)
- [Multipaths](#multipaths) - [Multi-paths](#multi-paths)
- [Literals](#literals) - [Literals](#literals)
The definitive implementation is [github.com/tidwall/gjson](https://github.com/tidwall/gjson). The definitive implementation is [github.com/tidwall/gjson](https://github.com/tidwall/gjson).
@ -46,7 +46,7 @@ The following GJSON Paths evaluate to the accompanying values.
### Basic ### Basic
In many cases you'll just want to retrieve values by object name or array index. Often, you'll just want to retrieve values by object name or array index.
```go ```go
name.last "Anderson" name.last "Anderson"
@ -77,7 +77,7 @@ Special purpose characters, such as `.`, `*`, and `?` can be escaped with `\`.
fav\.movie "Deer Hunter" fav\.movie "Deer Hunter"
``` ```
You'll also need to make sure that the `\` character is correctly escaped when hardcoding a path in your source code. You'll also need to make sure that the `\` character is correctly escaped when hard-coding a path in your source code.
```go ```go
// Go // Go
@ -130,8 +130,8 @@ Nested queries are allowed.
friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"] friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"]
``` ```
*Please note that prior to v1.3.0, queries used the `#[...]` brackets. This was *Please note that before v1.3.0, queries used the `#[...]` brackets. This was
changed in v1.3.0 as to avoid confusion with the new [multipath](#multipaths) changed in v1.3.0 as to avoid confusion with the new [multi-paths](#multi-paths)
syntax. For backwards compatibility, `#[...]` will continue to work until the syntax. For backwards compatibility, `#[...]` will continue to work until the
next major release.* next major release.*
@ -183,10 +183,10 @@ vals.#(b==~*)#.a >> [1,2,3,4,5,6,7,8,9,10]
vals.#(b!=~*)#.a >> [11] vals.#(b!=~*)#.a >> [11]
``` ```
### Dot vs Pipe ### Dot vs. Pipe
The `.` is standard separator, but it's also possible to use a `|`. The `.` is standard separator, but it's also possible to use a `|`.
In most cases they both end up returning the same results. Usually, they both end up returning the same results.
The cases where`|` differs from `.` is when it's used after the `#` for [Arrays](#arrays) and [Queries](#queries). The cases where`|` differs from `.` is when it's used after the `#` for [Arrays](#arrays) and [Queries](#queries).
Here are some examples Here are some examples
@ -215,14 +215,14 @@ The path `friends.#(last="Murphy")#` all by itself results in
[{"first": "Dale", "last": "Murphy", "age": 44},{"first": "Jane", "last": "Murphy", "age": 47}] [{"first": "Dale", "last": "Murphy", "age": 44},{"first": "Jane", "last": "Murphy", "age": 47}]
``` ```
The `.first` suffix will process the `first` path on each array element *before* returning the results. Which becomes The `.first` suffix will process the `first` path on each array element *before* returning the results. Which becomes:
```json ```json
["Dale","Jane"] ["Dale","Jane"]
``` ```
But the `|first` suffix actually processes the `first` path *after* the previous result. But the `|first` suffix actually processes the `first` path *after* the previous result.
Since the previous result is an array, not an object, it's not possible to process Since the previous result is an array, not an object, it's impossible to process
because `first` does not exist. because `first` does not exist.
Yet, `|0` suffix returns Yet, `|0` suffix returns
@ -244,11 +244,11 @@ children.@reverse ["Jack","Alex","Sara"]
children.@reverse.0 "Jack" children.@reverse.0 "Jack"
``` ```
There are currently the following built-in modifiers: These are currently the following built-in modifiers:
- `@reverse`: Reverse an array or the members of an object. - `@reverse`: Reverse an array or the members of an object.
- `@ugly`: Remove all whitespace from JSON. - `@ugly`: Remove all whitespace from JSON.
- `@pretty`: Make the JSON more human readable. - `@pretty`: Make the JSON more human-readable.
- `@this`: Returns the current element. It can be used to retrieve the root element. - `@this`: Returns the current element. It can be used to retrieve the root element.
- `@valid`: Ensure the JSON document is valid. - `@valid`: Ensure the JSON document is valid.
- `@flatten`: Flattens an array. - `@flatten`: Flattens an array.
@ -270,7 +270,7 @@ For example, the `@pretty` modifier takes a JSON object as its argument.
@pretty:{"sortKeys":true} @pretty:{"sortKeys":true}
``` ```
Which makes the JSON pretty and orders all of its keys. Which makes the JSON pretty and orders all its keys.
```json ```json
{ {
@ -311,13 +311,13 @@ gjson.AddModifier("case", func(json, arg string) string {
*Note: Custom modifiers are not yet available in the Rust version* *Note: Custom modifiers are not yet available in the Rust version*
### Multipaths ### Multi-paths
Starting with v1.3.0, GJSON added the ability to join multiple paths together Starting with v1.3.0, GJSON added the ability to join multiple paths together
to form new documents. Wrapping comma-separated paths between `[...]` or to form new documents. Wrapping comma-separated paths between `[...]` or
`{...}` will result in a new array or object, respectively. `{...}` will result in a new array or object, respectively.
For example, using the given multipath: For example, using the given multi-path:
``` ```
{name.first,age,"the_murphys":friends.#(last="Murphy")#.first} {name.first,age,"the_murphys":friends.#(last="Murphy")#.first}
@ -339,11 +339,11 @@ This results in
### Literals ### Literals
Starting with v1.12.0, GJSON added support of JSON literals, which provides a way for constructing static blocks of JSON. This is can be particularly useful when constructing a new JSON document using [multipaths](#multipaths). Starting with v1.12.0, GJSON added support of JSON literals, which provides a way for constructing static blocks of JSON. This can be particularly useful when constructing a new JSON document using [multi-paths](#multi-paths).
A JSON literal begins with the '!' declaration character. A JSON literal begins with the '!' declaration character.
For example, using the given multipath: For example, using the given multi-path:
``` ```
{name.first,age,"company":!"Happysoft","employed":!true} {name.first,age,"company":!"Happysoft","employed":!true}

38
gjson.go
View File

@ -99,7 +99,7 @@ func (t Result) String() string {
} }
} }
// Bool returns an boolean representation. // Bool returns a boolean representation.
func (t Result) Bool() bool { func (t Result) Bool() bool {
switch t.Type { switch t.Type {
default: default:
@ -166,7 +166,7 @@ func (t Result) Uint() uint64 {
} }
} }
// Float returns an float64 representation. // Float returns a float64 representation.
func (t Result) Float() float64 { func (t Result) Float() float64 {
switch t.Type { switch t.Type {
default: default:
@ -458,7 +458,7 @@ end:
// Parse parses the JSON and returns a result. // Parse parses the JSON and returns a result.
// //
// This function expects that the JSON is well-formed, and does not validate. // This function expects that the JSON is well-formed, and does not validate.
// Invalid JSON will not panic, but it may return back unexpected results. // Invalid JSON will not panic, but it may return unexpected results.
// If you are consuming JSON from an unpredictable source then you may want to // If you are consuming JSON from an unpredictable source then you may want to
// use the Valid function first. // use the Valid function first.
func Parse(json string) Result { func Parse(json string) Result {
@ -480,7 +480,7 @@ func Parse(json string) Result {
value.Raw, value.Num = tonum(json[i:]) value.Raw, value.Num = tonum(json[i:])
case 'n': case 'n':
if i+1 < len(json) && json[i+1] != 'u' { if i+1 < len(json) && json[i+1] != 'u' {
// nan // NaN
value.Type = Number value.Type = Number
value.Raw, value.Num = tonum(json[i:]) value.Raw, value.Num = tonum(json[i:])
} else { } else {
@ -1813,10 +1813,10 @@ type subSelector struct {
path string path string
} }
// parseSubSelectors returns the subselectors belonging to a '[path1,path2]' or // parseSubSelectors returns the sub-selectors belonging to a '[path1,path2]' or
// '{"field1":path1,"field2":path2}' type subSelection. It's expected that the // '{"field1":path1,"field2":path2}' type subSelection. It's expected that the
// first character in path is either '[' or '{', and has already been checked // first character in path is either '[' or '{', and has already been checked
// prior to calling this function. // before calling this function.
func parseSubSelectors(path string) (sels []subSelector, out string, ok bool) { func parseSubSelectors(path string) (sels []subSelector, out string, ok bool) {
modifier := 0 modifier := 0
depth := 1 depth := 1
@ -2008,7 +2008,7 @@ type parseContext struct {
// "friends.#.first" >> ["James","Roger"] // "friends.#.first" >> ["James","Roger"]
// //
// This function expects that the JSON is well-formed, and does not validate. // This function expects that the JSON is well-formed, and does not validate.
// Invalid JSON will not panic, but it may return back unexpected results. // Invalid JSON will not panic, but it may return unexpected results.
// If you are consuming JSON from an unpredictable source then you may want to // If you are consuming JSON from an unpredictable source then you may want to
// use the Valid function first. // use the Valid function first.
func Get(json, path string) Result { func Get(json, path string) Result {
@ -2035,7 +2035,7 @@ func Get(json, path string) Result {
} }
} }
if path[0] == '[' || path[0] == '{' { if path[0] == '[' || path[0] == '{' {
// using a subselector path // using a sub-selector path
kind := path[0] kind := path[0]
var ok bool var ok bool
var subs []subSelector var subs []subSelector
@ -2128,7 +2128,7 @@ func GetBytes(json []byte, path string) Result {
return getBytes(json, path) return getBytes(json, path)
} }
// runeit returns the rune from the the \uXXXX // runeit returns the rune from the \uXXXX
func runeit(json string) rune { func runeit(json string) rune {
n, _ := strconv.ParseUint(json[:4], 16, 64) n, _ := strconv.ParseUint(json[:4], 16, 64)
return rune(n) return rune(n)
@ -2255,7 +2255,7 @@ func stringLessInsensitive(a, b string) bool {
} }
// parseAny parses the next value from a JSON string. // parseAny parses the next value from a JSON string.
// A Result is returned when the hit param is set. // A Result is returned when the hit parameter is set.
// The return values are (i int, res Result, ok bool) // The return values are (i int, res Result, ok bool)
func parseAny(json string, i int, hit bool) (int, Result, bool) { func parseAny(json string, i int, hit bool) (int, Result, bool) {
var res Result var res Result
@ -2767,7 +2767,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) {
var parsedArgs bool var parsedArgs bool
switch pathOut[0] { switch pathOut[0] {
case '{', '[', '"': case '{', '[', '"':
// JSON arg // JSON argument
res := Parse(pathOut) res := Parse(pathOut)
if res.Exists() { if res.Exists() {
args = squash(pathOut) args = squash(pathOut)
@ -2776,7 +2776,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) {
} }
} }
if !parsedArgs { if !parsedArgs {
// simple arg // simple argument
i := 0 i := 0
for ; i < len(pathOut); i++ { for ; i < len(pathOut); i++ {
if pathOut[i] == '|' { if pathOut[i] == '|' {
@ -2940,7 +2940,7 @@ func modReverse(json, arg string) string {
// //
// [1,[2],[3,4],[5,[6,7]]] -> [1,2,3,4,5,[6,7]] // [1,[2],[3,4],[5,[6,7]]] -> [1,2,3,4,5,[6,7]]
// //
// The {"deep":true} arg can be provide for deep flattening. // The {"deep":true} argument can be provided for deep flattening.
// //
// [1,[2],[3,4],[5,[6,7]]] -> [1,2,3,4,5,6,7] // [1,[2],[3,4],[5,[6,7]]] -> [1,2,3,4,5,6,7]
// //
@ -3221,11 +3221,11 @@ func getBytes(json []byte, path string) Result {
} else if uintptr(strh.data) >= uintptr(rawh.data) && } else if uintptr(strh.data) >= uintptr(rawh.data) &&
uintptr(strh.data)+uintptr(strh.len) <= uintptr(strh.data)+uintptr(strh.len) <=
uintptr(rawh.data)+uintptr(rawh.len) { uintptr(rawh.data)+uintptr(rawh.len) {
// Str is a substring of Raw. // Str is a sub-string of Raw.
start := uintptr(strh.data) - uintptr(rawh.data) start := uintptr(strh.data) - uintptr(rawh.data)
// safely copy the raw slice header // safely copy the raw slice header
result.Raw = string(*(*[]byte)(unsafe.Pointer(&rawh))) result.Raw = string(*(*[]byte)(unsafe.Pointer(&rawh)))
// substring the raw // sub-string the raw
result.Str = result.Raw[start : start+uintptr(strh.len)] result.Str = result.Raw[start : start+uintptr(strh.len)]
} else { } else {
// safely copy both the raw and str slice headers to strings // safely copy both the raw and str slice headers to strings
@ -3319,10 +3319,10 @@ func revSquash(json string) string {
// //
// ["friends.0.first","friends.1.first","friends.2.first"] // ["friends.0.first","friends.1.first","friends.2.first"]
// //
// The param 'json' must be the original JSON used when calling Get. // The parameter 'json' must be the original JSON used when calling Get.
// //
// Returns an empty string if the paths cannot be determined, which can happen // Returns an empty string if the paths cannot be determined, which can happen
// when the Result came from a path that contained a multipath, modifier, // when the Result came from a path that contained a multi-path, modifier,
// or a nested query. // or a nested query.
func (t Result) Paths(json string) []string { func (t Result) Paths(json string) []string {
if t.Indexes == nil { if t.Indexes == nil {
@ -3348,10 +3348,10 @@ func (t Result) Paths(json string) []string {
// //
// "friends.0" // "friends.0"
// //
// The param 'json' must be the original JSON used when calling Get. // The parameter 'json' must be the original JSON used when calling Get.
// //
// Returns an empty string if the paths cannot be determined, which can happen // Returns an empty string if the paths cannot be determined, which can happen
// when the Result came from a path that contained a multipath, modifier, // when the Result came from a path that contained a multi-path, modifier,
// or a nested query. // or a nested query.
func (t Result) Path(json string) string { func (t Result) Path(json string) string {
var path []byte var path []byte

10
gjson_test.go
View File

@ -353,7 +353,7 @@ func TestPlus53BitInts(t *testing.T) {
} }
func TestIssue38(t *testing.T) { func TestIssue38(t *testing.T) {
// These should not fail, even though the unicode is invalid. // These should not fail, even though the Unicode is invalid.
Get(`["S3O PEDRO DO BUTI\udf93"]`, "0") Get(`["S3O PEDRO DO BUTI\udf93"]`, "0")
Get(`["S3O PEDRO DO BUTI\udf93asdf"]`, "0") Get(`["S3O PEDRO DO BUTI\udf93asdf"]`, "0")
Get(`["S3O PEDRO DO BUTI\udf93\u"]`, "0") Get(`["S3O PEDRO DO BUTI\udf93\u"]`, "0")
@ -2227,7 +2227,7 @@ func TestTildeQueries(t *testing.T) {
} }
func TestModifierDoubleQuotes(t *testing.T) { func TestModifierDoubleQuotes(t *testing.T) {
josn := `{ json := `{
"data": [ "data": [
{ {
"name": "Product P4", "name": "Product P4",
@ -2246,11 +2246,11 @@ func TestModifierDoubleQuotes(t *testing.T) {
} }
] ]
}` }`
AddModifier("string", func(josn, arg string) string { AddModifier("string", func(json, arg string) string {
return strconv.Quote(josn) return strconv.Quote(json)
}) })
res := Get(josn, "data.#.{name,value:{productId,vendorId}.@string.@ugly}") res := Get(json, "data.#.{name,value:{productId,vendorId}.@string.@ugly}")
assert(t, res.Raw == `[`+ assert(t, res.Raw == `[`+
`{"name":"Product P4","value":"{\"productId\":\"1bb3\",\"vendorId\":\"10de\"}"},`+ `{"name":"Product P4","value":"{\"productId\":\"1bb3\",\"vendorId\":\"10de\"}"},`+