Documentation ¶
Overview ¶
Package errors is a drop-in replacement and extension of the Go standard library's package errors.
Index ¶
- Variables
- func Annotate(err error, format string, args ...any) (annotated error)
- func As(err error, target any) (ok bool)
- func Is(err, target error) (ok bool)
- func Join(errs ...error) error
- func List(msg string, errs ...error) (err error)deprecated
- func New(msg string) (err error)deprecated
- func Unwrap(err error) (unwrapped error)
- func WithDeferred(returned, deferred error) (result error)
- type Aser
- type Deferred
- type Error
- type Iser
- type Pair
- type Wrapper
- type WrapperSlice
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = stderrors.ErrUnsupported
ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported. For example, a call to os.Link when using a file system that does not support hard links.
Functions ¶
func Annotate ¶
Annotate annotates the error with the message, unless the error is nil. The last verb in format must be a verb compatible with errors, for example "%w".
In Defers ¶
The primary use case for this function is to simplify code like this:
func (f *foo) doStuff(s string) (err error) { defer func() { if err != nil { err = fmt.Errorf("bad foo %q: %w", s, err) } }() // … }
Instead, write:
func (f *foo) doStuff(s string) (err error) { defer func() { err = errors.Annotate(err, "bad foo %q: %w", s) }() // … }
At The End Of Functions ¶
Another possible use case is to simplify final checks like this:
func (f *foo) doStuff(s string) (err error) { // … if err != nil { return fmt.Errorf("doing stuff with %s: %w", s, err) } return nil }
Instead, you could write:
func (f *foo) doStuff(s string) (err error) { // … return errors.Annotate(err, "doing stuff with %s: %w", s) }
Warning ¶
This function requires that there be only ONE error named "err" in the function and that it is always the one that is returned. Example (Bad) provides an example of the incorrect usage of WithDeferred.
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.
It calls errors.As from the Go standard library.
func Is ¶
Is reports whether any error in err's chain matches target.
It calls errors.Is from the Go standard library.
func Join ¶ added in v0.12.1
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if errs contains no non-nil values. 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.
It calls errors.Join from the Go standard library.
func List
deprecated
List wraps several errors into a single error with an additional message.
Deprecated: Use errors.Join instead.
Example ¶
Output: msg only : "fail" <nil> msg and err : "fail: stage 1" "stage 1" msg and errs : "fail: 2 errors: \"stage 1\", \"stage 2\"" "stage 1"
func New
deprecated
New returns an error that formats as the given msg. Each call to New returns a distinct error value even if the text is identical.
It calls errors.New from the Go standard library.
Deprecated: Use type Error and constant errors instead.
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.
It calls errors.Unwrap from the Go standard library.
func WithDeferred ¶
WithDeferred is a helper function for deferred errors. For example, to preserve errors from the Close method, replace this:
defer f.Close()
With this:
defer func() { err = errors.WithDeferred(err, f.Close()) }
If returned is nil and deferred is non-nil, the returned error implements the Deferred interface. If both returned and deferred are non-nil, result has the underlying type of *Pair.
Warning ¶
This function requires that there be only ONE error named "err" in the function and that it is always the one that is returned. Example (Bad) provides an example of the incorrect usage of WithDeferred.
Example ¶
Output: without errs : <nil> with returned err : not found with deferred err : deferred: close fail with both errs : returned: "not found", deferred: "close fail"
Types ¶
type Aser ¶
Aser is a copy of the hidden aser interface from the Go standard library. It is added here for tests, linting, etc.
type Deferred ¶
Deferred is the interface for errors that were returned by cleanup functions, such as Close. This is useful in APIs which desire to handle such errors differently, for example to log them as warnings.
Method Deferred returns a bool to mirror the behavior of types like net.Error and allow implementations to decide if the error is a deferred one dynamically. Users of this API must check it's return value as well as the result errors.As.
if derr := errors.Deferred(nil); errors.As(err, &derr) && derr.Deferred() { // … }
type Iser ¶
Iser is a copy of the hidden iser interface from the Go standard library. It is added here for tests, linting, etc.
type Pair ¶
Pair is a pair of errors. The Returned error is the main error that has been returned by a function. The Deferred error is the error returned by the cleanup function, such as Close.
In pairs returned from WithDeferred, the Deferred error always implements the Deferred interface.
Example ¶
Output: err : returned: "not found", deferred: "close fail" unwrapped : not found deferred : deferred: close fail deferred unwrapped : close fail deferred check : true
type Wrapper ¶
type Wrapper interface {
Unwrap() error
}
Wrapper is a copy of the hidden wrapper interface from the Go standard library. It is added here for tests, linting, etc.
type WrapperSlice ¶ added in v0.12.1
type WrapperSlice interface {
Unwrap() []error
}
WrapperSlice is a copy of the hidden wrapper interface added to the Go standard library in Go 1.20. It is added here for tests, linting, etc.