README
¶
go-errors
powerful errors library with a simple API that allows:
- accessing all the standard library errors functions
- wrapping of errors
- adding values to errors, in a similar manner to contexts
- including calling function prefix when tag=errcaller is set
- including stacktrace with error when tag=errtrace is set
Documentation
¶
Index ¶
- Constants
- func As(err error, target any) bool
- func AsV2[Type any](err error) Type
- func Is(err error, target error) bool
- func IsV2(err error, targets ...error) bool
- func Join(errs ...error) error
- func New(msg string) error
- func NewAt(skip int, msg string) error
- func Newf(msgf string, args ...interface{}) error
- func Unwrap(err error) error
- func UnwrapV2(err error) []error
- func Value(err error, key any) any
- func WithValue(err error, key any, value any) error
- func Wrap(err error, msg string) error
- func WrapAt(skip int, err error, msg string) error
- func Wrapf(err error, msgf string, args ...interface{}) error
- type Callers
- type OnceError
Constants ¶
const IncludesCaller = false
IncludesCaller is a compile-time flag used to indicate whether to include calling function prefix on error wrap / creation.
const IncludesStacktrace = false
IncludesStacktrace is a compile-time flag used to indicate whether to include stacktraces on error wrap / creation.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true. Otherwise, it returns false.
The tree consists of err itself, followed by the errors obtained by repeatedly calling Unwrap. When err wraps multiple errors, As examines err followed by a depth-first traversal of its children.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
An error type might provide an As method so it can be treated as if it were a different error type.
As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.
func AsV2 ¶ added in v2.3.1
AsV2 is functionally similar to As(), instead leveraging generics to handle allocation and returning of a concrete generic parameter type.
func Is ¶
Is reports whether any error in err's tree matches target.
The tree consists of err itself, followed by the errors obtained by repeatedly calling Unwrap. When err wraps multiple errors, Is examines err followed by a depth-first traversal of its children.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines
func (m MyError) Is(target error) bool { return target == fs.ErrExist }
then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library. An Is method should only shallowly compare err and the target and not call Unwrap on either.
func Join ¶ added in v2.3.0
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.
A non-nil error returned by Join implements the Unwrap() []error method.
func New ¶
New returns a new error created from message.
Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.
func NewAt ¶ added in v2.3.0
NewAt returns a new error created, skipping 'skip' frames for trace / caller information, from message.
Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.
func Newf ¶
Newf returns a new error created from message format and args.
Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.
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.
Unwrap only calls a method of the form "Unwrap() error". In particular Unwrap does not unwrap errors returned by Join.
func UnwrapV2 ¶ added in v2.3.1
UnwrapV2 is functionally similar to Unwrap(), except that it also handles the case of interface{ Unwrap() []error }.
func WithValue ¶ added in v2.1.0
WithValue wraps err to store given key-value pair, accessible via Value() function.
func Wrap ¶
Wrap will wrap supplied error within a new error created from message.
Note this function cannot be inlined, to ensure expected and consistent behaviour in setting trace / caller info.
Types ¶
type Callers ¶
Callers ...
func Stacktrace ¶
Stacktrace fetches first stored stacktrace of callers from error chain.
func (Callers) MarshalJSON ¶
MarshalJSON implements json.Marshaler to provide an easy, simple default.
type OnceError ¶
type OnceError struct {
// contains filtered or unexported fields
}
OnceError is an error structure that supports safe multi threaded usage and setting only once (until reset).
Source Files