get json values quickly
+get JSON values quickly
-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). +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). -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). @@ -34,7 +34,7 @@ $ go get -u github.com/tidwall/gjson This will retrieve the library. ## 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 package main @@ -114,8 +114,8 @@ changed in v1.3.0 as to avoid confusion with the new ## Result Type -GJSON supports the json types `string`, `number`, `bool`, and `null`. -Arrays and Objects are returned as their raw json types. +GJSON supports the JSON types `string`, `number`, `bool`, and `null`. +Arrays and Objects are returned as their raw JSON types. 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. A modifier is a path component that performs custom processing on the -json. +JSON. Multiple paths can be "chained" together using the pipe character. 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: ``` @@ -197,19 +197,19 @@ we'll get `children` array and reverse the order: "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. -- `@ugly`: Remove all whitespace from a json document. -- `@pretty`: Make the json document more human readable. +- `@ugly`: Remove all whitespace from a JSON document. +- `@pretty`: Make the JSON document more human readable. - `@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. - `@join`: Joins multiple objects into a single object. - `@keys`: Returns an array of keys for an object. - `@values`: Returns an array of values for an object. -- `@tostr`: Converts json to a string. Wraps a json string. -- `@fromstr`: Converts a string from json. Unwraps a json string. +- `@tostr`: Converts JSON to a string. Wraps 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). - `@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 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} ``` -Which makes the json pretty and orders all of its keys. +Which makes the JSON pretty and orders all of its keys. ```json { @@ -247,7 +247,7 @@ Please see [Pretty Options](https://github.com/tidwall/pretty#customized-output) 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. ```go @@ -299,7 +299,7 @@ gjson.ForEachLine(json, func(line gjson.Result) bool{ ## 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 { @@ -381,7 +381,7 @@ if gjson.Get(json, "name.last").Exists() { ## 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. @@ -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 diff --git a/SYNTAX.md b/SYNTAX.md index 14c1df9..0460770 100644 --- a/SYNTAX.md +++ b/SYNTAX.md @@ -250,13 +250,13 @@ There are currently the following built-in modifiers: - `@ugly`: Remove all whitespace from JSON. - `@pretty`: Make the JSON more human readable. - `@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. - `@join`: Joins multiple objects into a single object. - `@keys`: Returns an array of keys for an object. - `@values`: Returns an array of values for an object. -- `@tostr`: Converts json to a string. Wraps a json string. -- `@fromstr`: Converts a string from json. Unwraps a json string. +- `@tostr`: Converts JSON to a string. Wraps 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). - `@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. -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} ``` -Which makes the json pretty and orders all of its keys. +Which makes the JSON pretty and orders all of its keys. ```json { @@ -339,9 +339,9 @@ This results in ### 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: diff --git a/gjson.go b/gjson.go index d6d341b..4c50909 100644 --- a/gjson.go +++ b/gjson.go @@ -1,4 +1,4 @@ -// Package gjson provides searching for json strings. +// Package gjson provides searching for JSON strings. package gjson import ( @@ -17,15 +17,15 @@ import ( type Type int const ( - // Null is a null json value + // Null is a null JSON value Null Type = iota - // False is a json false boolean + // False is a JSON false boolean False - // Number is json number + // Number is JSON number Number - // String is a json string + // String is a JSON string String - // True is a json true boolean + // True is a JSON true boolean True // JSON is a raw block of 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 is the json type + // Type is the JSON type Type Type - // Raw is the raw json + // Raw is the raw JSON Raw string - // Str is the json string + // Str is the JSON string Str string - // Num is the json number + // Num is the JSON number 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 // Indexes of all the elements that match on a path containing the '#' // query character. @@ -455,10 +455,10 @@ end: 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. -// Invalid json will not panic, but it may return back unexpected results. +// 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. // If you are consuming JSON from an unpredictable source then you may want to // use the Valid function first. func Parse(json string) Result { @@ -508,7 +508,7 @@ func Parse(json string) Result { 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)) func ParseBytes(json []byte) Result { return Parse(string(json)) @@ -1978,7 +1978,7 @@ type parseContext struct { 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". // When the value is found it's returned immediately. // @@ -2007,8 +2007,8 @@ type parseContext struct { // "c?ildren.0" >> "Sara" // "friends.#.first" >> ["James","Roger"] // -// 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. +// 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. // If you are consuming JSON from an unpredictable source then you may want to // use the Valid function first. func Get(json, path string) Result { @@ -2122,7 +2122,7 @@ func Get(json, path string) Result { 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) func GetBytes(json []byte, path string) Result { return getBytes(json, path) @@ -2254,7 +2254,7 @@ func stringLessInsensitive(a, b string) bool { 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. // The return values are (i int, res Result, ok 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 } -// 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 // will be equal to the number of input paths. func GetMany(json string, path ...string) []Result { @@ -2343,7 +2343,7 @@ func GetMany(json string, path ...string) []Result { 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 // will be equal to the number of input paths. func GetManyBytes(json []byte, path ...string) []Result { @@ -2633,7 +2633,7 @@ func validnull(data []byte, i int) (outi int, ok bool) { 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) { // return errors.New("invalid json") @@ -2644,7 +2644,7 @@ func Valid(json string) bool { return ok } -// ValidBytes returns true if the input is valid json. +// ValidBytes returns true if the input is valid JSON. // // if !gjson.Valid(json) { // return errors.New("invalid json") @@ -2767,7 +2767,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) { var parsedArgs bool switch pathOut[0] { case '{', '[', '"': - // json arg + // JSON arg res := Parse(pathOut) if res.Exists() { args = squash(pathOut) @@ -2797,7 +2797,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) { return pathOut, res, false } -// unwrap removes the '[]' or '{}' characters around json +// unwrap removes the '[]' or '{}' characters around JSON func unwrap(json string) string { json = trim(json) if len(json) >= 2 && (json[0] == '[' || json[0] == '{') { @@ -2862,7 +2862,7 @@ func cleanWS(s string) string { return s } -// @pretty modifier makes the json look nice. +// @pretty modifier makes the JSON look nice. func modPretty(json, arg string) string { if len(arg) > 0 { 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] // -// 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 { res := Parse(json) if !res.IsArray() { @@ -3053,7 +3053,7 @@ func modValues(json, arg string) string { // // [{"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 { res := Parse(json) if !res.IsArray() { @@ -3115,9 +3115,9 @@ func modJoin(json, arg string) string { return bytesString(out) } -// @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. -func modValid(json, arg string) string { +// @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. +func modValid(json, _ string) string { if !Valid(json) { return "" } @@ -3189,9 +3189,9 @@ type sliceHeader struct { 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 -// 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 { var result Result if json != nil { diff --git a/gjson_test.go b/gjson_test.go index c803f44..33f15d6 100644 --- a/gjson_test.go +++ b/gjson_test.go @@ -107,7 +107,7 @@ func TestEscapePath(t *testing.T) { 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"}, "noop":{"what is a wren?":"a bird"}, "happy":true,"immortal":false,