From c12548f2007147f26a07fb1065e3f7f818a814cb Mon Sep 17 00:00:00 2001 From: ccoVeille <3875889+ccoVeille@users.noreply.github.com> Date: Tue, 23 Apr 2024 13:59:52 +0200 Subject: [PATCH] Fix typos and style --- README.md | 22 +++++++++++----------- SYNTAX.md | 36 ++++++++++++++++++------------------ gjson.go | 38 +++++++++++++++++++------------------- gjson_test.go | 10 +++++----- 4 files changed, 53 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 40cb763..73a60e6 100644 --- a/README.md +++ b/README.md @@ -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. 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). @@ -58,7 +58,7 @@ Prichard ## 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). 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"] ``` -*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](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.* ## 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. ``` -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 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. - `@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. - `@valid`: Ensure the JSON document is valid. - `@flatten`: Flattens an array. @@ -269,7 +269,7 @@ gjson.AddModifier("case", func(json, arg string) string { ## 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: @@ -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. -For example, all of these will return the same result: +For example, these will return the same result: ```go gjson.Parse(json).Get("name").Get("last") @@ -381,9 +381,9 @@ 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 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 if !gjson.Valid(json) { @@ -412,7 +412,7 @@ var json []byte = ... 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 var json []byte = ... diff --git a/SYNTAX.md b/SYNTAX.md index 0460770..b4cd1b2 100644 --- a/SYNTAX.md +++ b/SYNTAX.md @@ -10,9 +10,9 @@ This document is designed to explain the structure of a GJSON Path through examp - [Escape Character](#escape-character) - [Arrays](#arrays) - [Queries](#queries) -- [Dot vs Pipe](#dot-vs-pipe) +- [Dot vs. Pipe](#dot-vs-pipe) - [Modifiers](#modifiers) -- [Multipaths](#multipaths) +- [Multi-paths](#multi-paths) - [Literals](#literals) 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 -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 name.last "Anderson" @@ -77,7 +77,7 @@ Special purpose characters, such as `.`, `*`, and `?` can be escaped with `\`. 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 @@ -105,7 +105,7 @@ friends.#.age [44,68,47] ### Queries -You can also query an array for the first match by using `#(...)`, or find all matches with `#(...)#`. +You can also query an array for the first match by using `#(...)`, or find all matches with `#(...)#`. Queries support the `==`, `!=`, `<`, `<=`, `>`, `>=` comparison operators, and the simple pattern matching `%` (like) and `!%` (not like) operators. @@ -130,8 +130,8 @@ Nested queries are allowed. friends.#(nets.#(=="fb"))#.first >> ["Dale","Roger"] ``` -*Please note that prior to v1.3.0, queries used the `#[...]` brackets. This was -changed in v1.3.0 as to avoid confusion with the new [multipath](#multipaths) +*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 [multi-paths](#multi-paths) syntax. For backwards compatibility, `#[...]` will continue to work until the next major release.* @@ -183,10 +183,10 @@ vals.#(b==~*)#.a >> [1,2,3,4,5,6,7,8,9,10] vals.#(b!=~*)#.a >> [11] ``` -### Dot vs Pipe +### Dot vs. Pipe 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). 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}] ``` -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 ["Dale","Jane"] ``` 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. Yet, `|0` suffix returns @@ -244,11 +244,11 @@ children.@reverse ["Jack","Alex","Sara"] 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 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. - `@valid`: Ensure the JSON document is valid. - `@flatten`: Flattens an array. @@ -270,7 +270,7 @@ 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 its keys. ```json { @@ -311,13 +311,13 @@ gjson.AddModifier("case", func(json, arg string) string { *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 to form new documents. Wrapping comma-separated paths between `[...]` or `{...}` 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} @@ -339,11 +339,11 @@ 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 can be particularly useful when constructing a new JSON document using [multi-paths](#multi-paths). 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} diff --git a/gjson.go b/gjson.go index 4c50909..f9711fa 100644 --- a/gjson.go +++ b/gjson.go @@ -99,7 +99,7 @@ func (t Result) String() string { } } -// Bool returns an boolean representation. +// Bool returns a boolean representation. func (t Result) Bool() bool { switch t.Type { 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 { switch t.Type { default: @@ -458,7 +458,7 @@ end: // 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. +// 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 // use the Valid function first. func Parse(json string) Result { @@ -480,7 +480,7 @@ func Parse(json string) Result { value.Raw, value.Num = tonum(json[i:]) case 'n': if i+1 < len(json) && json[i+1] != 'u' { - // nan + // NaN value.Type = Number value.Raw, value.Num = tonum(json[i:]) } else { @@ -1813,10 +1813,10 @@ type subSelector struct { 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 // 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) { modifier := 0 depth := 1 @@ -2008,7 +2008,7 @@ type parseContext struct { // "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. +// 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 // use the Valid function first. func Get(json, path string) Result { @@ -2035,7 +2035,7 @@ func Get(json, path string) Result { } } if path[0] == '[' || path[0] == '{' { - // using a subselector path + // using a sub-selector path kind := path[0] var ok bool var subs []subSelector @@ -2128,7 +2128,7 @@ func GetBytes(json []byte, path string) Result { return getBytes(json, path) } -// runeit returns the rune from the the \uXXXX +// runeit returns the rune from the \uXXXX func runeit(json string) rune { n, _ := strconv.ParseUint(json[:4], 16, 64) return rune(n) @@ -2255,7 +2255,7 @@ func stringLessInsensitive(a, b string) bool { } // 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) func parseAny(json string, i int, hit bool) (int, Result, bool) { var res Result @@ -2767,7 +2767,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) { var parsedArgs bool switch pathOut[0] { case '{', '[', '"': - // JSON arg + // JSON argument res := Parse(pathOut) if res.Exists() { args = squash(pathOut) @@ -2776,7 +2776,7 @@ func execModifier(json, path string) (pathOut, res string, ok bool) { } } if !parsedArgs { - // simple arg + // simple argument i := 0 for ; i < len(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]] // -// 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] // @@ -3221,11 +3221,11 @@ func getBytes(json []byte, path string) Result { } else if uintptr(strh.data) >= uintptr(rawh.data) && uintptr(strh.data)+uintptr(strh.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) // safely copy the raw slice header result.Raw = string(*(*[]byte)(unsafe.Pointer(&rawh))) - // substring the raw + // sub-string the raw result.Str = result.Raw[start : start+uintptr(strh.len)] } else { // 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"] // -// 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 -// 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. func (t Result) Paths(json string) []string { if t.Indexes == nil { @@ -3348,10 +3348,10 @@ func (t Result) Paths(json string) []string { // // "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 -// 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. func (t Result) Path(json string) string { var path []byte diff --git a/gjson_test.go b/gjson_test.go index 33f15d6..8e68755 100644 --- a/gjson_test.go +++ b/gjson_test.go @@ -353,7 +353,7 @@ func TestPlus53BitInts(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\udf93asdf"]`, "0") Get(`["S3O PEDRO DO BUTI\udf93\u"]`, "0") @@ -2227,7 +2227,7 @@ func TestTildeQueries(t *testing.T) { } func TestModifierDoubleQuotes(t *testing.T) { - josn := `{ + json := `{ "data": [ { "name": "Product P4", @@ -2246,11 +2246,11 @@ func TestModifierDoubleQuotes(t *testing.T) { } ] }` - AddModifier("string", func(josn, arg string) string { - return strconv.Quote(josn) + AddModifier("string", func(json, arg string) string { + 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 == `[`+ `{"name":"Product P4","value":"{\"productId\":\"1bb3\",\"vendorId\":\"10de\"}"},`+