Documentation
¶
Overview ¶
Package errors provides functions and types to define and manipulate errors. It should generally be used instead of the standard library's errors package, as it is a strict superset.
Index ¶
- Constants
- Variables
- func As(err error, target any) bool
- func AsType[E error](err error) (E, bool)
- func Code(e error) int
- func Errorf(f string, args ...any) error
- func HasKey(e error, key string) bool
- func Is(err, target error) bool
- func IsTag(e error, tag ErrorTag) bool
- func Join(errs ...error) error
- func KeyValue(e error, key string) string
- func New(s string) error
- func Tag(e error, tag ErrorTag, kvpairs ...string) error
- func TagNew(msg string, tag ErrorTag, kvpairs ...string) error
- func TagOnce(e error, tag ErrorTag, kvpairs ...string) error
- func Unwrap(err error) error
- func UnwrapAll(err error) error
- func UserMessage(e error, defaultMsg string) string
- func WithKeyValue(e error, key, value string) error
- type ConstError
- type ErrorTag
Constants ¶
const ( // CodeKey is the key used to store an error code in the error metadata. If // the associated value is a valid integer, it can be extracted via Code. CodeKey = "code" // UserMessageKey is the key used to store a user-friendly or user-safe // message with the error. This is usually a less technical version (or a // safer version because it does not leak internal information) of the error // message that makes sense to display to the end-user. It can be extracted // via the standard KeyValue function, but also with UserMessage where a // default message can be used if no such key exists. UserMessageKey = "usermsg" )
const RootErrAsUserMsg = "/"
RootErrAsUserMsg is a special value that can be used as default message in the call to UserMessage to retrieve the message of the root error if no specific user message exist.
Variables ¶
var ErrUnsupported = errors.ErrUnsupported
ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported. See the stdlib's errors.ErrUnsupported documentation for more details.
Functions ¶
func As ¶
As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.
See the stdlib's errors.As documentation for more details.
func AsType ¶
AsType finds the first error in err's tree that matches the type E, and if one is found, returns that error value and true. Otherwise, it returns the zero value of E and false.
See the stdlib's errors.As documentation for more details.
func Code ¶
Code returns the integer value of the first "code" key found in the error metadata, if it is present and its value is a valid integer. Otherwise it returns 0.
func Errorf ¶
Errorf formats according to a format specifier and returns the string as a value that satisfies error.
If the format specifier includes a %w verb with an error operand, the returned error will implement an Unwrap method returning the operand. It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v.
See the stdlib's fmt.Errorf documentation for more details.
func HasKey ¶
HasKey returns true if e or any error in its chain has been tagged with the specified key, regardless of its value.
func Is ¶
Is reports whether any error in err's chain matches target. See the stdlib's errors.Is documentation for more details.
func Join ¶
Join returns an error that wraps the given errors. See the stdlib's errors.Join documentation for more details.
func KeyValue ¶
KeyValue returns the value associated with the specified key if any error in the chain has been tagged with it. If no such error exists, it returns an empty string.
func New ¶
New returns an error with s as error message. See the stdlib's errors.New documentation for more details.
func Tag ¶
Tag returns an error that wraps e and tags it with the provided error tag. Errors can be queried for tags with IsTag. An arbitrary set of key-value pairs can also be provided and will be stored in the error and printed in the error message. It is possible to query an error for presence of a key using HasKey and to retrieve a specific key-value pair with KeyValue. If the number of key-value arguments is not even, the final key is associated with an empty string value.
The special key "code" should be set to an integer value (as a string) when provided, and if so it can be extracted as integer with Code.
Example uses of key-value metadata could be to identify the argument that failed validation, or the (stringified) status code of an HTTP request.
If e is nil, it returns nil.
func TagOnce ¶
TagOnce is like Tag except that it returns e unchanged if it has already been tagged. That is, if any error in e's chain is a tagged error, it doesn't tag e again, so its associated ErrorTag and key-value pairs, if any, remain unchanged and possibly different than those provided in this call.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
See the stdlib's errors.Unwrap documentation for more details.
func UnwrapAll ¶
UnwrapAll unwraps err until it gets to the root, initial error and it returns that error. If err is nil or is not wrapped, err is returned.
func UserMessage ¶
UserMessage returns the UserMessageKey value from e or defaultMsg if none is found. If defaultMsg is RootErrAsUserMsg, the error message of the root error (obtained with UnwrapAll) is used, if that error is non-nil.
func WithKeyValue ¶
WithKeyValue adds (or sets) the specified key-value pair to the first tagged error found in e's chain. If e is not and does not wrap any tagged error, and it is not nil, it is wrapped with one with an empty tag and the key-value pair is set on it. It returns e or the new tagged error that wraps e.
Types ¶
type ConstError ¶
type ConstError string
ConstError is an error string that can be defined as constant.
func (ConstError) Error ¶
func (e ConstError) Error() string
Error returns the error message of the ConstError, which is the constant string value itself.
type ErrorTag ¶
type ErrorTag string
ErrorTag is the type of a tag that can be applied to an error using errors.Tag. It is expected that the main program defines its own predefined and shared list of tags to be used throughout the code.
It is conceptually similar to the error flags mentioned in this blog post: https://npf.io/2021/04/errorflags/, except that ErrorTag is a string that is also used as prefix to the error message.
Source Files