diff options
| author | Damien Neil <dneil@google.com> | 2022-09-22 10:43:26 -0700 |
|---|---|---|
| committer | Damien Neil <dneil@google.com> | 2022-09-29 18:40:40 +0000 |
| commit | 4a0a2b33dfa3c99250efa222439f2c27d6780e4a (patch) | |
| tree | 25b1d2541b1b1244fe86d3b7ab690bff475e7ac7 /src/errors/errors.go | |
| parent | 36f046d934c66fb6eb47d568e04665708c096ad7 (diff) | |
| download | go-4a0a2b33dfa3c99250efa222439f2c27d6780e4a.tar.xz | |
errors, fmt: add support for wrapping multiple errors
An error which implements an "Unwrap() []error" method wraps all the
non-nil errors in the returned []error.
We replace the concept of the "error chain" inspected by errors.Is
and errors.As with the "error tree". Is and As perform a pre-order,
depth-first traversal of an error's tree. As returns the first
matching result, if any.
The new errors.Join function returns an error wrapping a list of errors.
The fmt.Errorf function now supports multiple instances of the %w verb.
For #53435.
Change-Id: Ib7402e70b68e28af8f201d2b66bd8e87ccfb5283
Reviewed-on: https://go-review.googlesource.com/c/go/+/432898
Reviewed-by: Cherry Mui <cherryyz@google.com>
Reviewed-by: Rob Pike <r@golang.org>
Run-TryBot: Damien Neil <dneil@google.com>
Reviewed-by: Joseph Tsai <joetsai@digital-static.net>
Diffstat (limited to 'src/errors/errors.go')
| -rw-r--r-- | src/errors/errors.go | 31 |
1 files changed, 17 insertions, 14 deletions
diff --git a/src/errors/errors.go b/src/errors/errors.go index f2fabacd4e..8436f812a6 100644 --- a/src/errors/errors.go +++ b/src/errors/errors.go @@ -6,26 +6,29 @@ // // The New function creates errors whose only content is a text message. // -// The Unwrap, Is and As functions work on errors that may wrap other errors. -// An error wraps another error if its type has the method +// An error e wraps another error if e's type has one of the methods // // Unwrap() error +// Unwrap() []error // -// If e.Unwrap() returns a non-nil error w, then we say that e wraps w. +// If e.Unwrap() returns a non-nil error w or a slice containing w, +// then we say that e wraps w. A nil error returned from e.Unwrap() +// indicates that e does not wrap any error. It is invalid for an +// Unwrap method to return an []error containing a nil error value. // -// Unwrap unpacks wrapped errors. If its argument's type has an -// Unwrap method, it calls the method once. Otherwise, it returns nil. +// An easy way to create wrapped errors is to call fmt.Errorf and apply +// the %w verb to the error argument: // -// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb -// to the error argument: +// wrapsErr := fmt.Errorf("... %w ...", ..., err, ...) // -// errors.Unwrap(fmt.Errorf("... %w ...", ..., err, ...)) +// Successive unwrapping of an error creates a tree. The Is and As +// functions inspect an error's tree by examining first the error +// itself followed by the tree of each of its children in turn +// (pre-order, depth-first traversal). // -// returns err. -// -// Is unwraps its first argument sequentially looking for an error that matches the -// second. It reports whether it finds a match. It should be used in preference to -// simple equality checks: +// Is examines the tree of its first argument looking for an error that +// matches the second. It reports whether it finds a match. It should be +// used in preference to simple equality checks: // // if errors.Is(err, fs.ErrExist) // @@ -35,7 +38,7 @@ // // because the former will succeed if err wraps fs.ErrExist. // -// As unwraps its first argument sequentially looking for an error that can be +// As examines the tree of its first argument looking for an error that can be // assigned to its second argument, which must be a pointer. If it succeeds, it // performs the assignment and returns true. Otherwise, it returns false. The form // |
