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

Fix JSON acronym 

An acronym is written in capital.
This commit is contained in:
ccoVeille 2024-04-23 13:43:14 +02:00
parent 0b9aa79774
commit 49fb81dad1
No known key found for this signature in database
4 changed files with 64 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -9,12 +9,12 @@
</p> </p>
<p align="center">get json values quickly</a></p> <p align="center">get JSON values quickly</a></p>
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).
@ -34,7 +34,7 @@ $ go get -u github.com/tidwall/gjson
This will retrieve the library. This will retrieve the library.
## Get a value ## Get a value
Get searches json for the specified path. A path is in dot syntax, such as "name.last" or "age". When the value is found it's returned immediately. Get searches JSON for the specified path. A path is in dot syntax, such as "name.last" or "age". When the value is found it's returned immediately.
```go ```go
package main package main
@ -114,8 +114,8 @@ changed in v1.3.0 as to avoid confusion with the new
## Result Type ## Result Type
GJSON supports the json types `string`, `number`, `bool`, and `null`. GJSON supports the JSON types `string`, `number`, `bool`, and `null`.
Arrays and Objects are returned as their raw json types. Arrays and Objects are returned as their raw JSON types.
The `Result` type holds one of these: The `Result` type holds one of these:
@ -184,12 +184,12 @@ result.Uint() uint64 // 0 to 18446744073709551615
New in version 1.2 is support for modifier functions and path chaining. New in version 1.2 is support for modifier functions and path chaining.
A modifier is a path component that performs custom processing on the A modifier is a path component that performs custom processing on the
json. JSON.
Multiple paths can be "chained" together using the pipe character. Multiple paths can be "chained" together using the pipe character.
This is useful for getting results from a modified query. This is useful for getting results from a modified query.
For example, using the built-in `@reverse` modifier on the above json document, For example, using the built-in `@reverse` modifier on the above JSON document,
we'll get `children` array and reverse the order: we'll get `children` array and reverse the order:
``` ```
@ -197,19 +197,19 @@ we'll get `children` array and reverse the order:
"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 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.
- `@join`: Joins multiple objects into a single object. - `@join`: Joins multiple objects into a single object.
- `@keys`: Returns an array of keys for an object. - `@keys`: Returns an array of keys for an object.
- `@values`: Returns an array of values for an object. - `@values`: Returns an array of values for an object.
- `@tostr`: Converts json to a string. Wraps a json string. - `@tostr`: Converts JSON to a string. Wraps a JSON string.
- `@fromstr`: Converts a string from json. Unwraps a json string. - `@fromstr`: Converts a string from JSON. Unwraps a JSON string.
- `@group`: Groups arrays of objects. See [e4fc67c](https://github.com/tidwall/gjson/commit/e4fc67c92aeebf2089fabc7872f010e340d105db). - `@group`: Groups arrays of objects. See [e4fc67c](https://github.com/tidwall/gjson/commit/e4fc67c92aeebf2089fabc7872f010e340d105db).
- `@dig`: Search for a value without providing its entire path. See [e8e87f2](https://github.com/tidwall/gjson/commit/e8e87f2a00dc41f3aba5631094e21f59a8cf8cbf). - `@dig`: Search for a value without providing its entire path. See [e8e87f2](https://github.com/tidwall/gjson/commit/e8e87f2a00dc41f3aba5631094e21f59a8cf8cbf).
@ -218,13 +218,13 @@ There are currently the following built-in modifiers:
A modifier may accept an optional argument. The argument can be a valid JSON A modifier may accept an optional argument. The argument can be a valid JSON
document or just characters. document or just characters.
For example, the `@pretty` modifier takes a json object as its argument. 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 of its keys.
```json ```json
{ {
@ -247,7 +247,7 @@ Please see [Pretty Options](https://github.com/tidwall/pretty#customized-output)
You can also add custom modifiers. You can also add custom modifiers.
For example, here we create a modifier that makes the entire json document upper For example, here we create a modifier that makes the entire JSON document upper
or lower case. or lower case.
```go ```go
@ -299,7 +299,7 @@ gjson.ForEachLine(json, func(line gjson.Result) bool{
## Get nested array values ## Get nested array values
Suppose you want all the last names from the following json: Suppose you want all the last names from the following JSON:
```json ```json
{ {
@ -381,7 +381,7 @@ 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 back 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 prior to using GJSON.
@ -425,7 +425,7 @@ if result.Index > 0 {
} }
``` ```
This is a best-effort no allocation sub slice of the original json. This method utilizes the `result.Index` field, which is the position of the raw data in the original json. It's possible that the value of `result.Index` equals zero, in which case the `result.Raw` is converted to a `[]byte`. This is a best-effort no allocation sub slice of the original JSON. This method utilizes the `result.Index` field, which is the position of the raw data in the original JSON. It's possible that the value of `result.Index` equals zero, in which case the `result.Raw` is converted to a `[]byte`.
## Performance ## Performance

14
SYNTAX.md
View File

@ -250,13 +250,13 @@ There are currently the following built-in modifiers:
- `@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.
- `@join`: Joins multiple objects into a single object. - `@join`: Joins multiple objects into a single object.
- `@keys`: Returns an array of keys for an object. - `@keys`: Returns an array of keys for an object.
- `@values`: Returns an array of values for an object. - `@values`: Returns an array of values for an object.
- `@tostr`: Converts json to a string. Wraps a json string. - `@tostr`: Converts JSON to a string. Wraps a JSON string.
- `@fromstr`: Converts a string from json. Unwraps a json string. - `@fromstr`: Converts a string from JSON. Unwraps a JSON string.
- `@group`: Groups arrays of objects. See [e4fc67c](https://github.com/tidwall/gjson/commit/e4fc67c92aeebf2089fabc7872f010e340d105db). - `@group`: Groups arrays of objects. See [e4fc67c](https://github.com/tidwall/gjson/commit/e4fc67c92aeebf2089fabc7872f010e340d105db).
- `@dig`: Search for a value without providing its entire path. See [e8e87f2](https://github.com/tidwall/gjson/commit/e8e87f2a00dc41f3aba5631094e21f59a8cf8cbf). - `@dig`: Search for a value without providing its entire path. See [e8e87f2](https://github.com/tidwall/gjson/commit/e8e87f2a00dc41f3aba5631094e21f59a8cf8cbf).
@ -264,13 +264,13 @@ There are currently the following built-in modifiers:
A modifier may accept an optional argument. The argument can be a valid JSON payload or just characters. A modifier may accept an optional argument. The argument can be a valid JSON payload or just characters.
For example, the `@pretty` modifier takes a json object as its argument. 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 of its keys.
```json ```json
{ {
@ -339,9 +339,9 @@ 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 is can be particularly useful when constructing a new JSON document using [multipaths](#multipaths).
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 multipath:

70
gjson.go
View File

@ -1,4 +1,4 @@
// Package gjson provides searching for json strings. // Package gjson provides searching for JSON strings.
package gjson package gjson
import ( import (
@ -17,15 +17,15 @@ import (
type Type int type Type int
const ( const (
// Null is a null json value // Null is a null JSON value
Null Type = iota Null Type = iota
// False is a json false boolean // False is a JSON false boolean
False False
// Number is json number // Number is JSON number
Number Number
// String is a json string // String is a JSON string
String String
// True is a json true boolean // True is a JSON true boolean
True True
// JSON is a raw block of JSON // JSON is a raw block of JSON
JSON JSON
@ -51,17 +51,17 @@ func (t Type) String() string {
} }
} }
// Result represents a json value that is returned from Get(). // Result represents a JSON value that is returned from Get().
type Result struct { type Result struct {
// Type is the json type // Type is the JSON type
Type Type Type Type
// Raw is the raw json // Raw is the raw JSON
Raw string Raw string
// Str is the json string // Str is the JSON string
Str string Str string
// Num is the json number // Num is the JSON number
Num float64 Num float64
// Index of raw value in original json, zero means index unknown // Index of raw value in original JSON, zero means index unknown
Index int Index int
// Indexes of all the elements that match on a path containing the '#' // Indexes of all the elements that match on a path containing the '#'
// query character. // query character.
@ -455,10 +455,10 @@ end:
return return
} }
// 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 back 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 {
@ -508,7 +508,7 @@ func Parse(json string) Result {
return value return value
} }
// ParseBytes parses the json and returns a result. // ParseBytes parses the JSON and returns a result.
// If working with bytes, this method preferred over Parse(string(data)) // If working with bytes, this method preferred over Parse(string(data))
func ParseBytes(json []byte) Result { func ParseBytes(json []byte) Result {
return Parse(string(json)) return Parse(string(json))
@ -1978,7 +1978,7 @@ type parseContext struct {
lines bool lines bool
} }
// Get searches json for the specified path. // Get searches JSON for the specified path.
// A path is in dot syntax, such as "name.last" or "age". // A path is in dot syntax, such as "name.last" or "age".
// When the value is found it's returned immediately. // When the value is found it's returned immediately.
// //
@ -2007,8 +2007,8 @@ type parseContext struct {
// "c?ildren.0" >> "Sara" // "c?ildren.0" >> "Sara"
// "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 back 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 {
@ -2122,7 +2122,7 @@ func Get(json, path string) Result {
return c.value return c.value
} }
// GetBytes searches json for the specified path. // GetBytes searches JSON for the specified path.
// If working with bytes, this method preferred over Get(string(data), path) // If working with bytes, this method preferred over Get(string(data), path)
func GetBytes(json []byte, path string) Result { func GetBytes(json []byte, path string) Result {
return getBytes(json, path) return getBytes(json, path)
@ -2254,7 +2254,7 @@ func stringLessInsensitive(a, b string) bool {
return len(a) < len(b) return len(a) < len(b)
} }
// 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 param 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) {
@ -2332,7 +2332,7 @@ func parseAny(json string, i int, hit bool) (int, Result, bool) {
return i, res, false return i, res, false
} }
// GetMany searches json for the multiple paths. // GetMany searches JSON for the multiple paths.
// The return value is a Result array where the number of items // The return value is a Result array where the number of items
// will be equal to the number of input paths. // will be equal to the number of input paths.
func GetMany(json string, path ...string) []Result { func GetMany(json string, path ...string) []Result {
@ -2343,7 +2343,7 @@ func GetMany(json string, path ...string) []Result {
return res return res
} }
// GetManyBytes searches json for the multiple paths. // GetManyBytes searches JSON for the multiple paths.
// The return value is a Result array where the number of items // The return value is a Result array where the number of items
// will be equal to the number of input paths. // will be equal to the number of input paths.
func GetManyBytes(json []byte, path ...string) []Result { func GetManyBytes(json []byte, path ...string) []Result {
@ -2633,7 +2633,7 @@ func validnull(data []byte, i int) (outi int, ok bool) {
return i, false return i, false
} }
// Valid returns true if the input is valid json. // Valid returns true if the input is valid JSON.
// //
// if !gjson.Valid(json) { // if !gjson.Valid(json) {
// return errors.New("invalid json") // return errors.New("invalid json")
@ -2644,7 +2644,7 @@ func Valid(json string) bool {
return ok return ok
} }
// ValidBytes returns true if the input is valid json. // ValidBytes returns true if the input is valid JSON.
// //
// if !gjson.Valid(json) { // if !gjson.Valid(json) {
// return errors.New("invalid json") // return errors.New("invalid json")
@ -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 arg
res := Parse(pathOut) res := Parse(pathOut)
if res.Exists() { if res.Exists() {
args = squash(pathOut) args = squash(pathOut)
@ -2797,7 +2797,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) {
return pathOut, res, false return pathOut, res, false
} }
// unwrap removes the '[]' or '{}' characters around json // unwrap removes the '[]' or '{}' characters around JSON
func unwrap(json string) string { func unwrap(json string) string {
json = trim(json) json = trim(json)
if len(json) >= 2 && (json[0] == '[' || json[0] == '{') { if len(json) >= 2 && (json[0] == '[' || json[0] == '{') {
@ -2862,7 +2862,7 @@ func cleanWS(s string) string {
return s return s
} }
// @pretty modifier makes the json look nice. // @pretty modifier makes the JSON look nice.
func modPretty(json, arg string) string { func modPretty(json, arg string) string {
if len(arg) > 0 { if len(arg) > 0 {
opts := *pretty.DefaultOptions opts := *pretty.DefaultOptions
@ -2944,7 +2944,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 original json is returned when the json is not an array. // The original JSON is returned when the JSON is not an array.
func modFlatten(json, arg string) string { func modFlatten(json, arg string) string {
res := Parse(json) res := Parse(json)
if !res.IsArray() { if !res.IsArray() {
@ -3053,7 +3053,7 @@ func modValues(json, arg string) string {
// //
// [{"first":"Tom","age":37},{"age":41}] -> {"first","Tom","age":41} // [{"first":"Tom","age":37},{"age":41}] -> {"first","Tom","age":41}
// //
// The original json is returned when the json is not an object. // The original JSON is returned when the JSON is not an object.
func modJoin(json, arg string) string { func modJoin(json, arg string) string {
res := Parse(json) res := Parse(json)
if !res.IsArray() { if !res.IsArray() {
@ -3115,9 +3115,9 @@ func modJoin(json, arg string) string {
return bytesString(out) return bytesString(out)
} }
// @valid ensures that the json is valid before moving on. An empty string is // @valid ensures that the JSON is valid before moving on. An empty string is
// returned when the json is not valid, otherwise it returns the original json. // returned when the JSON is not valid, otherwise it returns the original JSON.
func modValid(json, arg string) string { func modValid(json, _ string) string {
if !Valid(json) { if !Valid(json) {
return "" return ""
} }
@ -3189,9 +3189,9 @@ type sliceHeader struct {
cap int cap int
} }
// getBytes casts the input json bytes to a string and safely returns the // getBytes casts the input JSON bytes to a string and safely returns the
// results as uniquely allocated data. This operation is intended to minimize // results as uniquely allocated data. This operation is intended to minimize
// copies and allocations for the large json string->[]byte. // copies and allocations for the large JSON string->[]byte.
func getBytes(json []byte, path string) Result { func getBytes(json []byte, path string) Result {
var result Result var result Result
if json != nil { if json != nil {

2
gjson_test.go
View File

@ -107,7 +107,7 @@ func TestEscapePath(t *testing.T) {
testEscapePath(t, json, "test.keyk\\*.key\\?", "val7") testEscapePath(t, json, "test.keyk\\*.key\\?", "val7")
} }
// this json block is poorly formed on purpose. // this JSON block is poorly formed on purpose.
var basicJSON = ` {"age":100, "name":{"here":"B\\\"R"}, var basicJSON = ` {"age":100, "name":{"here":"B\\\"R"},
"noop":{"what is a wren?":"a bird"}, "noop":{"what is a wren?":"a bird"},
"happy":true,"immortal":false, "happy":true,"immortal":false,