From 4a0a2b33dfa3c99250efa222439f2c27d6780e4a Mon Sep 17 00:00:00 2001 From: Damien Neil Date: Thu, 22 Sep 2022 10:43:26 -0700 Subject: 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 Reviewed-by: Rob Pike Run-TryBot: Damien Neil Reviewed-by: Joseph Tsai --- src/errors/errors.go | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) (limited to 'src/errors/errors.go') 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 // -- cgit v1.3