README
¶
errors - Error handling primitives
This package extends pkg/errors and xerror packages with additional functionality.
Documentation
¶
Overview ¶
Package errors provides error handling primitives.
Index ¶
- func As(err error, target any) bool
- func Cause(err error) error
- func Errorf(format string, args ...any) error
- func FormatError(err error, s fmt.State, verb rune)
- func Into[T error](err error) (target T, ok bool)
- func Is(err, target error) bool
- func Join(errs ...error) error
- func Kind(err error) error
- func New(msg string) error
- func Opaque(err error) error
- func Pack(kind error, args ...any) error
- func SetTrace(enable bool)
- func Trace() bool
- func Unpack(err error) error
- func Unwrap(err error) error
- func UnwrapAll(err error) error
- func UnwrapMulti(err error) []error
- func WithStack(err error) error
- func Wrap(err error, msg string) error
- func Wrapf(err error, format string, args ...any) error
- type Formatter
- type MultiFormatter
- type MultiWrapper
- type Packer
- type Printer
- type StackFrame
- type StackTrace
- type StackTracer
- type Wrapper
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatError ¶ added in v0.6.0
FormatError calls the FormatError method of f with a Printer configured according to s and verb, and writes the result to s.
func Into ¶
Into finds the first error in err's tree that matches target type T, and if one is found, returns it and true. Otherwise, it returns T's zero value and false.
Into is a type-safe alternative to As.
func Join ¶
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 Kind ¶
Kind finds the first error in err's tree that implements Packer, and if one is found, returns the result of calling its Kind method. Otherwise, Kind returns nil.
func Opaque ¶ added in v0.6.0
Opaque returns an error with the same error formatting as err but that does not match err and cannot be unwrapped. If err is nil, Opaque returns nil.
func Pack ¶
Pack creates a new error with a given kind. List of valid function signatures:
Pack(kind error) Pack(kind error, err error) Pack(kind error, err error, s string) Pack(kind error, err error, format string, args ...any) Pack(kind error, s string) Pack(kind error, format string, args ...any)
If kind is nil, Pack acts as Wrap, Wrapf, New or Errorf depending on the function signature.
If kind is nil and args are empty, Pack returns nil.
func Unpack ¶ added in v0.5.0
Unpack finds the first error in err's tree that implements Packer, and if one is found, returns the result of calling its Unpack method. Otherwise, Unpack returns nil.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap/Cause method on err, if err's type contains an Unwrap/Cause method returning error. Otherwise, Unwrap returns nil.
Unwrap only calls methods of form "Unwrap() error" or "Cause() error", so it doesn't unwrap multi-errors. In particular Unwrap does not unwrap errors returned by Join.
func UnwrapAll ¶ added in v0.6.0
UnwrapAll recursively unwraps an error until it reaches the underlying cause and returns it.
UnwrapAll only calls methods of form "Unwrap() error" or "Cause() error", so it doesn't unwrap multi-errors. In particular UnwrapAll does not unwrap errors returned by Join.
func UnwrapMulti ¶ added in v0.6.0
UnwrapMulti returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning slice of errors. Otherwise, Unwrap returns nil.
UnwrapMulti only calls a method of the form "Unwrap() []error".
Types ¶
type Formatter ¶ added in v0.6.0
type Formatter interface {
error
// FormatError prints the receiver's first error and returns the next error in
// the error chain, if any.
FormatError(p Printer) (next error)
}
A Formatter formats error messages.
type MultiFormatter ¶ added in v0.6.0
type MultiFormatter interface {
error
// FormatError prints the receiver's error and returns a slice of next errors
// in the error chain, if any.
FormatError(p Printer) (next []error)
}
A MultiFormatter formats multi-error messages.
type MultiWrapper ¶ added in v0.6.0
type MultiWrapper interface {
// Unwrap returns underlying errors.
Unwrap() []error
}
MultiWrapper provides an additional context around multiple errors.
type Packer ¶ added in v0.5.0
type Packer interface {
// Kind returns the categorical error type.
Kind() error
// Unpack returns an error without the categorical error type.
// If there is nothing except the categorical error type, Unpack returns nil.
Unpack() error
}
Packer represents an error that can be categorized by kind.
type Printer ¶ added in v0.6.0
type Printer interface {
// Print appends args to the message output.
Print(args ...any)
// Printf writes a formatted string.
Printf(format string, args ...any)
// Detail reports whether error detail is requested.
// After the first call to Detail, all text written to the Printer
// is formatted as additional detail, or ignored when
// detail has not been requested.
// If Detail returns false, the caller can avoid printing the detail at all.
Detail() bool
}
A Printer formats error messages.
The most common implementation of Printer is the one provided by package fmt during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message typically provide their own implementations.
type StackFrame ¶ added in v0.6.0
StackFrame is runtime.Frame that implements fmt.Formatter.
func (StackFrame) Format ¶ added in v0.6.0
func (sf StackFrame) Format(s fmt.State, verb rune)
Format formats the frame according to the fmt.Formatter interface.
%f source file %d source line %n function name %s equivalent to %n %f:%d %v equivalent to %s
Format accepts flags that alter the printing of some verbs, as follows:
%+v equivalent to %n\n %f:%d
func (StackFrame) MarshalText ¶ added in v0.6.0
func (sf StackFrame) MarshalText() ([]byte, error)
MarshalText formats a stack frame as a text string. The output is the same as that of fmt.Sprintf("%n %f:%d", f).
func (StackFrame) String ¶ added in v0.6.0
func (sf StackFrame) String() string
String formats a stack frame as a text string. The output is the same as that of fmt.Sprintf("%n %f:%d", f).
type StackTrace ¶
type StackTrace []uintptr
StackTrace contains PC values returned by runtime.Callers.
func GetStackTrace ¶ added in v0.6.0
func GetStackTrace(err error) StackTrace
GetStackTrace finds the first error in err's tree that implements StackTracer, and if one is found, returns the result of calling its StackTrace method. Otherwise, GetStackTrace returns nil.
func (StackTrace) Format ¶
func (st StackTrace) Format(s fmt.State, verb rune)
Format formats the stack trace according to the fmt.Formatter interface.
%s prints each frame as "func file:line" %v equivalent to %s
Format accepts flags that alter the printing of some verbs, as follows:
%+v prints each frame as "func\n file:line"
func (StackTrace) Frames ¶ added in v0.3.0
func (st StackTrace) Frames() []StackFrame
Frames returns a slice of caller frames from st. Wraps runtime.CallersFrames.
func (StackTrace) FramesSeq ¶ added in v0.3.0
func (st StackTrace) FramesSeq() iter.Seq[StackFrame]
FramesSeq returns go1.23 iterator that wraps runtime.CallersFrames.
type StackTracer ¶ added in v0.6.0
type StackTracer interface {
// StackTrace returns the stack trace associated with the error.
StackTrace() StackTrace
}
StackTracer represents an error with an associated stack trace.
Source Files