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>

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
 //