Documentation ¶
Overview ¶
Package errors provides advanced error handling features.
Index ¶
- Variables
- func Adapt(err error) error
- func Cause(err error) error
- func Causes(err error) []error
- func Err(v interface{}) error
- func Errorf(msg string, args ...interface{}) error
- func Inspect(err error) (msgs []string, types []string, tags []Tag, stacks []StackTrace, causes []error)
- func Is(typ string, err error) bool
- func Join(errs ...error) error
- func LookupTag(err error, name string) string
- func New(msg string) error
- func Recv(ch <-chan error) error
- func Register(a Adapter)
- func Types(err error) []string
- func WithMessage(err error, msg string) error
- func WithStack(err error) error
- func WithStackTrace(err error, stack StackTrace) error
- func WithTags(err error, tags ...Tag) error
- func WithTypes(err error, types ...string) error
- func Wrap(err error, msg string) error
- func Wrapf(err error, msg string, args ...interface{}) error
- type Adapter
- type AdapterFunc
- type Frame
- type StackTrace
- type Tag
- type Value
Constants ¶
This section is empty.
Variables ¶
var TODO error
TODO is a non-nil error intended to act as a placeholder during development when writing the structure of the code but the implementation is still left to be written.
Functions ¶
func Adapt ¶
Adapt adapts err using the registered adapters.
Programs usually do not need to call this function explicitly and can instead rely on the fact that functions like Wrap, WithMessage, WithStack... will automatically adapt the errors that they receive.
func Causes ¶
Causes returns the list of causes of err, which may be an empty slice if err is nil or had no causes.
func Err ¶
func Err(v interface{}) error
Err constructs an error from a value of arbitrary type, using the following rules:
- if v is nil, the function simply returns nil
- if v is a string type, the function behaves like calling New
- if v is already an error it is returned unchanged
- if v has an Err() method returning an error, the function returns the result of calling it.
- if v doesn't fall into any of those categories, the function behaves like calling Errorf("%+v", v).
A common use case for this function is to implement internal error reporting based on raising panics (within a package), here is an example:
func F() (err error) { defer func() { err = errors.Err(recover()) }() // ... }
func Errorf ¶
Errorf returns an error that formats as fmt.Sprintf(msg, args...). The returned error carries a capture of the stack trace.
err = errors.Errorf("unexpected answer: %d", 42)
func Inspect ¶
func Inspect(err error) (msgs []string, types []string, tags []Tag, stacks []StackTrace, causes []error)
Inspect extract and returns properties of err.
The function follows a straight path on the error graph, stopping when it finds an error that doesn't have a single cause (either zero or many).
func Is ¶
Is tests whether err is of type typ. Errors may implement types by defining methods that take no arguments and return a boolean value. Passing the name of those methods to Is tests for their existence and calls them to validate the type of the error.
This model has been used in the standard library where some errors implement the Temporary and Timeout methods to give the program more details about the reason the error occurred and the way it should be handled.
Here is an example of using the Is function:
if errors.Is("Timeout", err) { // ... } if errors.Is("Temporary", err) { // ... }
The function walks through the graph of causes looking for an error which may implement the given type.
func Join ¶
Join composes an error from the list of errors passed as argument.
The function strips all nil errors from the input argument list. The returned error has a Causes method which returns the list of non-nil errors that were given to the function.
err = errors.Join(err1, err2, err3)
All errors passed to the function are adapted.
func LookupTag ¶
LookupTag returns value for a given tag name. Returns empty string if tag wasn't found. If multiple tags found by that name, the most recent value is used.
func New ¶
New returns an error that formats as the given message. The returned error carries a capture of the stack trace.
err = errors.New("something went wrong")
func Recv ¶
Recv reads all errors from the given channel and returns one that combines them. All nil error are ignored.
ch := make(chan error) wg := sync.WaitGroup{} for _, t := range tasks { wg.Add(1) go func(t task) { ch <- t(); wg.Done() } } go func() { wg.Wait(); close(ch) } err := errors.Recv(errch)
All errors received on the channel are adapted.
func Types ¶
Types returns a slice containing all the types implemented by err and its causes (if it had any).
func WithMessage ¶
WithMessage returns an error that wraps err and prefix its original error error message with msg. If err is nil, WithMessage returns nil.
err = errors.WithMessage(err, "something went wrong")
func WithStack ¶
WithStack returns an error that wraps err with a capture of the stack trace at the time the function is called. If err is nil, WithStack returns nil.
err = errors.WithStack(err)
The error is adapted before the stack trace is added.
func WithStackTrace ¶
func WithStackTrace(err error, stack StackTrace) error
WithStackTrace returns an error that wraps err with the given stack trace. If err is nil, WithStackTrace returns nil.
err = errors.WithStackTrace(err, errors.CaptureStackTrace(1))
The error is adapted before the stack trace is added.
func WithTags ¶
WithTags returns an error that wraps err and tags it with the given key/value pairs. If err is nil the function returns nil.
The error is adapted before tags are added.
func WithTypes ¶
WithTypes returns an error that wraps err and implements the given types so that calling errors.Is on the returned error with one of the given types will return true.
The error is adapted before types are added.
func Wrap ¶
Wrap returns an error that wraps err with msg as prefix to its original message and a capture of the stack trace at the time the function is called. If err is nil, Wrap returns nil.
err = errors.Wrap(err, "something went wrong")
The error is adapted before being wrapped with a message and stack trace.
func Wrapf ¶
Wrapf returns an error that wraps err with fmt.Sprintf(msg, args...) as prefix to its original message and a capture of the stack trace at the time the function is called. If err is nil, Wrap returns nil.
err = errors.Wrapf(err, "unexpected answer: %d", 42)
The error is adapted before being wrapped with a message and stack trace.
Types ¶
type Adapter ¶
type Adapter interface { // Adapt is called to adapt err, it either returnes err and false if it did // not recognize the error, or returns the adapted error and true. Adapt(err error) (error, bool) }
Adapter is an interface implemented by types that support adapting errors to be introspected by functions of the erorrs package.
type AdapterFunc ¶
The AdapterFunc types is an implementation of the Adapter interface which makes it possible to use simple functions as error adapters.
type Frame ¶
type Frame uintptr
Frame represents a program counter inside a stack frame.
func (Frame) Format ¶
Format formats the frame according to the fmt.Formatter interface.
%s source file %d source line %n function name %v equivalent to %s:%d
Format accepts flags that alter the printing of some verbs, as follows:
%+s path of source file relative to the compile time GOPATH %#s function name and path of source file %+n function name prefixed by its package name %#n function name prefixed by its full package path %+v equivalent to %+s:%d %#v equivalent to %#s:%d
type StackTrace ¶
type StackTrace []Frame
StackTrace is stack of Frames from innermost (newest) to outermost (oldest).
func CaptureStackTrace ¶
func CaptureStackTrace(skip int) StackTrace
CaptureStackTrace walks the call stack that led to this function and records it as a StackTrace value. The skip argument is the number of stacks frames to skip, the frame for captureStackTrace is never included in the returned trace.
func (StackTrace) Format ¶
func (st StackTrace) Format(s fmt.State, verb rune)
Format formats the stack of Frames according to the fmt.Formatter interface.
%s lists source files for each Frame in the stack %v lists the source file and line number for each Frame in the stack
Format accepts flags that alter the printing of some verbs, as follows:
%+v Prints filename, function, and line number for each Frame in the stack.
type Value ¶
type Value struct { Message string Tags map[string]string Types []string Stack []string Causes []Value }
Value is a serializable error representation which carries all rich information of errors that can be constructed by this package.
This type is useful to transmit errors between programs that communicate over some IPC mechanism. It may also be used as a form of reflection to discover the various components of an error.
func ValueOf ¶
ValueOf returns an error value representing err. If err is nil the function returns the zero-value of Value.
func (Value) Err ¶
Err constructs and returns an error from v, the error message, types, and causes are rebuilt and part of the returned error to match as closely as possible the information carried by the error that this value was built from in the first place.
Note that the only information that isn't carried back from the Value into the returned error is the stack trace, because it may be coming from a different program there is no way to match it to the correct function pointers. Instead the stack trace information in the returned error is set to the call stack that led to this method call, which in general is way more relevant to the program which is calling this method.
If v is the zero-value, the method returns a nil error.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package awserrors provides functions to adapt errors of the AWS Go SDK into errors compatible with the errors-go package.
|
Package awserrors provides functions to adapt errors of the AWS Go SDK into errors compatible with the errors-go package. |
Package httperrors provides functions to construct errors from HTTP responses.
|
Package httperrors provides functions to construct errors from HTTP responses. |
Package ioerrors provides adapters for errors generated by the standard io package.
|
Package ioerrors provides adapters for errors generated by the standard io package. |
Package neterrors provides adapters for errors generated by the standard net package.
|
Package neterrors provides adapters for errors generated by the standard net package. |
Package pkgerrors provides adapters for errors generated by the github.com/pkg/errors package.
|
Package pkgerrors provides adapters for errors generated by the github.com/pkg/errors package. |
Package stderrors exposes no APIs and is used for the sole purpose of setting up global adapters for all packages of the standard library supported by the errors-go project.
|
Package stderrors exposes no APIs and is used for the sole purpose of setting up global adapters for all packages of the standard library supported by the errors-go project. |
Package twirperrors provides functions to adapt errors of the github.com/twitchtv/twirp package into errors compatible with the errors-go package.
|
Package twirperrors provides functions to adapt errors of the github.com/twitchtv/twirp package into errors compatible with the errors-go package. |