|
@@ -1,10 +1,11 @@
|
|
# go-multierror
|
|
# go-multierror
|
|
|
|
|
|
-[][travis]
|
|
|
|
-[][godocs]
|
|
|
|
|
|
+[](https://circleci.com/gh/hashicorp/go-multierror)
|
|
|
|
+[](https://pkg.go.dev/github.com/hashicorp/go-multierror)
|
|
|
|
+
|
|
|
|
|
|
-[travis]: https://travis-ci.org/hashicorp/go-multierror
|
|
|
|
-[godocs]: https://godoc.org/github.com/hashicorp/go-multierror
|
|
|
|
|
|
+[circleci]: https://app.circleci.com/pipelines/github/hashicorp/go-multierror
|
|
|
|
+[godocs]: https://pkg.go.dev/github.com/hashicorp/go-multierror
|
|
|
|
|
|
`go-multierror` is a package for Go that provides a mechanism for
|
|
`go-multierror` is a package for Go that provides a mechanism for
|
|
representing a list of `error` values as a single `error`.
|
|
representing a list of `error` values as a single `error`.
|
|
@@ -14,16 +15,35 @@ be a list of errors. If the caller knows this, they can unwrap the
|
|
list and access the errors. If the caller doesn't know, the error
|
|
list and access the errors. If the caller doesn't know, the error
|
|
formats to a nice human-readable format.
|
|
formats to a nice human-readable format.
|
|
|
|
|
|
-`go-multierror` implements the
|
|
|
|
-[errwrap](https://github.com/hashicorp/errwrap) interface so that it can
|
|
|
|
-be used with that library, as well.
|
|
|
|
|
|
+`go-multierror` is fully compatible with the Go standard library
|
|
|
|
+[errors](https://golang.org/pkg/errors/) package, including the
|
|
|
|
+functions `As`, `Is`, and `Unwrap`. This provides a standardized approach
|
|
|
|
+for introspecting on error values.
|
|
|
|
|
|
## Installation and Docs
|
|
## Installation and Docs
|
|
|
|
|
|
Install using `go get github.com/hashicorp/go-multierror`.
|
|
Install using `go get github.com/hashicorp/go-multierror`.
|
|
|
|
|
|
Full documentation is available at
|
|
Full documentation is available at
|
|
-http://godoc.org/github.com/hashicorp/go-multierror
|
|
|
|
|
|
+https://pkg.go.dev/github.com/hashicorp/go-multierror
|
|
|
|
+
|
|
|
|
+### Requires go version 1.13 or newer
|
|
|
|
+
|
|
|
|
+`go-multierror` requires go version 1.13 or newer. Go 1.13 introduced
|
|
|
|
+[error wrapping](https://golang.org/doc/go1.13#error_wrapping), which
|
|
|
|
+this library takes advantage of.
|
|
|
|
+
|
|
|
|
+If you need to use an earlier version of go, you can use the
|
|
|
|
+[v1.0.0](https://github.com/hashicorp/go-multierror/tree/v1.0.0)
|
|
|
|
+tag, which doesn't rely on features in go 1.13.
|
|
|
|
+
|
|
|
|
+If you see compile errors that look like the below, it's likely that
|
|
|
|
+you're on an older version of go:
|
|
|
|
+
|
|
|
|
+```
|
|
|
|
+/go/src/github.com/hashicorp/go-multierror/multierror.go:112:9: undefined: errors.As
|
|
|
|
+/go/src/github.com/hashicorp/go-multierror/multierror.go:117:9: undefined: errors.Is
|
|
|
|
+```
|
|
|
|
|
|
## Usage
|
|
## Usage
|
|
|
|
|
|
@@ -81,6 +101,39 @@ if err := something(); err != nil {
|
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
|
|
+You can also use the standard [`errors.Unwrap`](https://golang.org/pkg/errors/#Unwrap)
|
|
|
|
+function. This will continue to unwrap into subsequent errors until none exist.
|
|
|
|
+
|
|
|
|
+**Extracting an error**
|
|
|
|
+
|
|
|
|
+The standard library [`errors.As`](https://golang.org/pkg/errors/#As)
|
|
|
|
+function can be used directly with a multierror to extract a specific error:
|
|
|
|
+
|
|
|
|
+```go
|
|
|
|
+// Assume err is a multierror value
|
|
|
|
+err := somefunc()
|
|
|
|
+
|
|
|
|
+// We want to know if "err" has a "RichErrorType" in it and extract it.
|
|
|
|
+var errRich RichErrorType
|
|
|
|
+if errors.As(err, &errRich) {
|
|
|
|
+ // It has it, and now errRich is populated.
|
|
|
|
+}
|
|
|
|
+```
|
|
|
|
+
|
|
|
|
+**Checking for an exact error value**
|
|
|
|
+
|
|
|
|
+Some errors are returned as exact errors such as the [`ErrNotExist`](https://golang.org/pkg/os/#pkg-variables)
|
|
|
|
+error in the `os` package. You can check if this error is present by using
|
|
|
|
+the standard [`errors.Is`](https://golang.org/pkg/errors/#Is) function.
|
|
|
|
+
|
|
|
|
+```go
|
|
|
|
+// Assume err is a multierror value
|
|
|
|
+err := somefunc()
|
|
|
|
+if errors.Is(err, os.ErrNotExist) {
|
|
|
|
+ // err contains os.ErrNotExist
|
|
|
|
+}
|
|
|
|
+```
|
|
|
|
+
|
|
**Returning a multierror only if there are errors**
|
|
**Returning a multierror only if there are errors**
|
|
|
|
|
|
If you build a `multierror.Error`, you can use the `ErrorOrNil` function
|
|
If you build a `multierror.Error`, you can use the `ErrorOrNil` function
|