summaryrefslogtreecommitdiff
path: root/errors.go
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2023-01-25 21:05:17 -0700
committerLuke Shumaker <lukeshu@lukeshu.com>2023-01-26 00:45:27 -0700
commitffee5c8516f3f55f82ed5bb8f0a4f340d485fa92 (patch)
tree0c10526b1ea57b043230402e9378b341c6966965 /errors.go
parent4148776399cb7ea5e10c74dc465e4e1e682cb399 (diff)
Write documentationv0.2.0
Diffstat (limited to 'errors.go')
-rw-r--r--errors.go68
1 files changed, 38 insertions, 30 deletions
diff --git a/errors.go b/errors.go
index 67fe6c9..5669d36 100644
--- a/errors.go
+++ b/errors.go
@@ -1,4 +1,4 @@
-// Copyright (C) 2022 Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023 Luke Shumaker <lukeshu@lukeshu.com>
//
// SPDX-License-Identifier: GPL-2.0-or-later
@@ -14,21 +14,23 @@ import (
"git.lukeshu.com/go/lowmemjson/internal"
)
-var (
- ErrInvalidUnreadRune = errors.New("lowmemjson: invalid use of UnreadRune")
-)
+// ErrInvalidUnreadRune is returned to Decodable.DecodeJSON(scanner)
+// implementations from scanner.UnreadRune() if the last operation was
+// not a successful .ReadRune() call.
+var ErrInvalidUnreadRune = errors.New("lowmemjson: invalid use of UnreadRune")
// parser errors ///////////////////////////////////////////////////////////////////////////////////
-var (
- ErrParserExceededMaxDepth = internal.ErrParserExceededMaxDepth
-)
+// ErrParserExceededMaxDepth is the base error that a
+// *DecodeSyntaxError wraps when the depth of the JSON document
+// exceeds 10000.
+var ErrParserExceededMaxDepth = internal.ErrParserExceededMaxDepth
// low-level decode errors /////////////////////////////////////////////////////////////////////////
// These will be wrapped in a *DecodeError.
-// A *DecodeReadError is returned from Decode if there is an I/O error
-// reading the input.
+// A *DecodeReadError is returned from Decode (wrapped in a
+// *DecodeError) if there is an I/O error reading the input.
type DecodeReadError struct {
Err error
Offset int64
@@ -39,8 +41,8 @@ func (e *DecodeReadError) Error() string {
}
func (e *DecodeReadError) Unwrap() error { return e.Err }
-// A *DecodeSyntaxError is returned from Decode if there is a syntax
-// error in the input.
+// A *DecodeSyntaxError is returned from Decode (wrapped in a
+// *DecodeError) if there is a syntax error in the input.
type DecodeSyntaxError struct {
Err error
Offset int64
@@ -51,8 +53,9 @@ func (e *DecodeSyntaxError) Error() string {
}
func (e *DecodeSyntaxError) Unwrap() error { return e.Err }
-// A *DecodeTypeError is returned from Decode if the JSON input is not
-// appropriate for the given Go type.
+// A *DecodeTypeError is returned from Decode (wrapped in a
+// *DecodeError) if the JSON input is not appropriate for the given Go
+// type.
//
// If a .DecodeJSON, .UnmarshalJSON, or .UnmashaleText method returns
// an error, it is wrapped in a *DecodeTypeError.
@@ -69,7 +72,7 @@ func (e *DecodeTypeError) Error() string {
if e.JSONType != "" {
fmt.Fprintf(&buf, "JSON %s ", e.JSONType)
}
- fmt.Fprintf(&buf, "at input byte %v in to Go %v", e.Offset, e.GoType)
+ fmt.Fprintf(&buf, "at input byte %v into Go %v", e.Offset, e.GoType)
if e.Err != nil {
fmt.Fprintf(&buf, ": %v", strings.TrimPrefix(e.Err.Error(), "json: "))
}
@@ -78,9 +81,10 @@ func (e *DecodeTypeError) Error() string {
func (e *DecodeTypeError) Unwrap() error { return e.Err }
-var (
- ErrDecodeNonEmptyInterface = errors.New("cannot decode in to non-empty interface")
-)
+// ErrDecodeNonEmptyInterface is the base error that a
+// *DecodeTypeError wraps when Decode is asked to unmarshal into an
+// `interface` type that has one or more methods.
+var ErrDecodeNonEmptyInterface = errors.New("cannot decode into non-empty interface")
// high-level decode errors ////////////////////////////////////////////////////////////////////////
@@ -88,21 +92,26 @@ var (
// not a non-nil pointer or is not settable.
//
// Alternatively, a *DecodeArgument error may be found inside of a
-// *DecodeTypeError if the type being decoded in to is not a type that
-// can be decoded in to (such as map with non-stringable type as
-// keys).
+// *DecodeTypeError if the type being decoded into is not a type that
+// can be decoded into (such as map with non-stringable type as keys).
//
// type DecodeArgumentError struct {
// Type reflect.Type
// }
type DecodeArgumentError = json.InvalidUnmarshalError
+// A *DecodeError is returned from Decode for all errors except for
+// *DecodeArgumentError.
+//
+// A *DecodeError wraps *DecodeSyntaxError for malformed or illegal
+// input, *DecodeTypeError for Go type issues, or *DecodeReadError for
+// I/O errors.
type DecodeError struct {
- Field string
- Err error
+ Field string // Where in the JSON the error was, in the form "v[idx][idx][idx]".
+ Err error // What the error was.
- FieldParent string // for compat
- FieldName string // for compat
+ FieldParent string // for compat; the same as encoding/json.UnmarshalTypeError.Struct
+ FieldName string // for compat; the same as encoding/json.UnmarshalTypeError.Field
}
func (e *DecodeError) Error() string {
@@ -129,19 +138,18 @@ type EncodeTypeError = json.UnsupportedTypeError
// }
type EncodeValueError = json.UnsupportedValueError
-// An *EncodeTypeError is returned by Encode when attempting to encode
-// an unsupported value type.
+// An *EncodeMethodError wraps an error that is returned from an
+// object's method when encoding that object to JSON.
type EncodeMethodError struct {
- Type reflect.Type
- Err error
- SourceFunc string
+ Type reflect.Type // The Go type that the method is on
+ SourceFunc string // The method: "EncodeJSON", "MarshalJSON", or "MarshalText"
+ Err error // The error that the method returned
}
func (e *EncodeMethodError) Error() string {
return fmt.Sprintf("json: error calling %v for type %v: %v",
e.SourceFunc, e.Type, strings.TrimPrefix(e.Err.Error(), "json: "))
}
-
func (e *EncodeMethodError) Unwrap() error { return e.Err }
// reencode errors /////////////////////////////////////////////////////////////////////////////////