errors: add example around unwrapping errors.Join

[tpaschalis]

Go version

go version go1.21.6 linux/amd64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='amd64'
GOBIN=''
GOCACHE='/home/tpaschalis/.cache/go-build'
GOENV='/home/tpaschalis/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMODCACHE='/home/tpaschalis/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='/home/tpaschalis/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.21.6'
GCCGO='gccgo'
GOAMD64='v1'
AR='ar'
CC='gcc'
CXX='g++'
CGO_ENABLED='1'
GOMOD='/home/tpaschalis/Workspace/lox-go/go.mod'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build3067468203=/tmp/go-build -gno-record-gcc-switches'

What did you do?

I used errors.Join to group a bunch of errors together, but then realized that getting the individual entries back is not straightforward (unless I'm missing something); the ways I could spot to get the errors back would be to use errors.As or an inline cast to Unwrap() []error.

Should we include an example that shows people to handle this task to set some best practices/precedence?

https://go.dev/play/p/G5vw-xdqBvm

What did you see happen?

The errors package documentation states:

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 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 also states that

Join returns an error that wraps the given errors. Any nil error values are discarded.
[...]
A non-nil error returned by Join implements the Unwrap() []error method.

and that

Unwrap only calls a method of the form "Unwrap() error". In particular Unwrap does not unwrap errors returned by Join

I think that the two following statements are contradictory since calling errors.Unwrap(errors.Join(err1, err2)) will return nil, even though we said that Join returns a wrapped error. The first statement is only true for a kind of wrapped errors.

A nil error returned from e.Unwrap() indicates that e does not wrap any error
Join returns an error that wraps the given errors

What did you expect to see?

An documented way to get the individual errors back instead of fiddling to find the right interface to cast to.

[gabyhelp]

Related Issues and Documentation

• proposal: errors: add Errors function to undo Join #57358 (closed)
• errors: Using `errors.Join` on a `joinError` should expand the existing joined error #60209 (closed)
• errors: add support for wrapping multiple errors #53435 (closed)
• errors: documentation for errors.Unwrap mentions non existing interface Wrapper #32130 (closed)
• proposal: errors: unwarap joinError to avoid deeply-nested joins #65676 (closed)
• errors: improve the godoc for Join and Unwrap #59301 (closed)
• Package errors > func Unwrap ¶ 1.13
• Package errors > func Join ¶ 1.20
• proposal: errors: add NewJoinedErrors #48831 (closed)
• errors: unwrap joinError to avoid deeply-nested joins #65360 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[seankhliao]

see #57358
Is and As are the intended ways to interact with errors.

[tpaschalis]

@seankhliao I'm not proposing a new way of interacting with these errors, but adding an example with errors.As and joined errors so that it's easier for people to get the individual items.

Would you object to that?

[ianlancetaylor]

I think the example would be OK if you want to send it. No issue is required. See https://go.dev/doc/contribute. Thanks.