encoding/json/jsontext: add symbolic Kind constants

Add constants for each possible Kind value (KindNull, KindTrue, etc.).
Leave the values unchanged ('n', 't', etc.).
Update documentation to reference the symbols.

Fixes #71756

Change-Id: Ib33b2ad9ee55f6f547d9e6a1c5a7f00c8400d3d3
Reviewed-on: https://go-review.googlesource.com/c/go/+/728420
Auto-Submit: Damien Neil <dneil@google.com>
Reviewed-by: Joseph Tsai <joetsai@digital-static.net>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/encoding/json/jsontext/decode.go b/src/encoding/json/jsontext/decode.go
index 511832f2ae087970600a4d30d1e5d3e408ad50aa..48d66fb1d4875b378ef0ba07ecbf41a3225e89c1 100644 (file)
--- a/src/encoding/json/jsontext/decode.go
+++ b/src/encoding/json/jsontext/decode.go
@@ -306,7 +306,7 @@ func (d *decodeBuffer) PreviousTokenOrValue() []byte {
 
 // PeekKind retrieves the next token kind, but does not advance the read offset.
 //
-// It returns 0 if an error occurs. Any such error is cached until
+// It returns [KindInvalid] if an error occurs. Any such error is cached until
 // the next read call and it is the caller's responsibility to eventually
 // follow up a PeekKind call with a read call.
 func (d *Decoder) PeekKind() Kind {
@@ -1154,9 +1154,9 @@ func (d *Decoder) StackDepth() int {
 // It must be a number between 0 and [Decoder.StackDepth], inclusive.
 // For each level, it reports the kind:
 //
-//   - 0 for a level of zero,
-//   - '{' for a level representing a JSON object, and
-//   - '[' for a level representing a JSON array.
+//   - [KindInvalid] for a level of zero,
+//   - [KindBeginObject] for a level representing a JSON object, and
+//   - [KindBeginArray] for a level representing a JSON array.
 //
 // It also reports the length of that JSON object or array.
 // Each name and value in a JSON object is counted separately,

diff --git a/src/encoding/json/jsontext/encode.go b/src/encoding/json/jsontext/encode.go
index e3b9c04ca615a0803156c691ca4a2dbb1bb90043..20f020700b810c9715db46147bdc67e8f1208b9b 100644 (file)
--- a/src/encoding/json/jsontext/encode.go
+++ b/src/encoding/json/jsontext/encode.go
@@ -946,9 +946,9 @@ func (e *Encoder) StackDepth() int {
 // It must be a number between 0 and [Encoder.StackDepth], inclusive.
 // For each level, it reports the kind:
 //
-//   - 0 for a level of zero,
-//   - '{' for a level representing a JSON object, and
-//   - '[' for a level representing a JSON array.
+//   - [KindInvalid] for a level of zero,
+//   - [KindBeginObject] for a level representing a JSON object, and
+//   - [KindBeginArray] for a level representing a JSON array.
 //
 // It also reports the length of that JSON object or array.
 // Each name and value in a JSON object is counted separately,

diff --git a/src/encoding/json/jsontext/token.go b/src/encoding/json/jsontext/token.go
index caf01749237413035db7968edf160f5c6a970286..6d9ad4b499888d96eddc1af2706f115d6c48df96 100644 (file)
--- a/src/encoding/json/jsontext/token.go
+++ b/src/encoding/json/jsontext/token.go
@@ -472,29 +472,33 @@ func (t Token) Kind() Kind {
        }
 }
 
+// A Kind represents the kind of a JSON token.
+//
 // Kind represents each possible JSON token kind with a single byte,
 // which is conveniently the first byte of that kind's grammar
-// with the restriction that numbers always be represented with '0':
-//
-//   - 'n': null
-//   - 'f': false
-//   - 't': true
-//   - '"': string
-//   - '0': number
-//   - '{': object begin
-//   - '}': object end
-//   - '[': array begin
-//   - ']': array end
-//
-// An invalid kind is usually represented using 0,
-// but may be non-zero due to invalid JSON data.
+// with the restriction that numbers always be represented with '0'.
 type Kind byte
 
+const (
+       KindInvalid     Kind = 0   // invalid kind
+       KindNull        Kind = 'n' // null
+       KindFalse       Kind = 'f' // false
+       KindTrue        Kind = 't' // true
+       KindString      Kind = '"' // string
+       KindNumber      Kind = '0' // number
+       KindBeginObject Kind = '{' // begin object
+       KindEndObject   Kind = '}' // end object
+       KindBeginArray  Kind = '[' // begin array
+       KindEndArray    Kind = ']' // end array
+)
+
 const invalidKind Kind = 0
 
 // String prints the kind in a humanly readable fashion.
 func (k Kind) String() string {
        switch k {
+       case 0:
+               return "invalid"
        case 'n':
                return "null"
        case 'f':

diff --git a/src/encoding/json/jsontext/value.go b/src/encoding/json/jsontext/value.go
index a4b06b2a947de74ceae27752b2a5603c271154bc..84c919b9dc591e160382457ff3f42f517c35adbd 100644 (file)
--- a/src/encoding/json/jsontext/value.go
+++ b/src/encoding/json/jsontext/value.go
@@ -236,7 +236,7 @@ func (v *Value) UnmarshalJSON(b []byte) error {
 }
 
 // Kind returns the starting token kind.
-// For a valid value, this will never include '}' or ']'.
+// For a valid value, this will never include [KindEndObject] or [KindEndArray].
 func (v Value) Kind() Kind {
        if v := v[jsonwire.ConsumeWhitespace(v):]; len(v) > 0 {
                return Kind(v[0]).normalize()