vendor/github.com/hashicorp/go-multierror/README.md

   1 # go-multierror
   2
   3 `go-multierror` is a package for Go that provides a mechanism for
   4 representing a list of `error` values as a single `error`.
   5
   6 This allows a function in Go to return an `error` that might actually
   7 be a list of errors. If the caller knows this, they can unwrap the
   8 list and access the errors. If the caller doesn't know, the error
   9 formats to a nice human-readable format.
  10
  11 `go-multierror` implements the
  12 [errwrap](https://github.com/hashicorp/errwrap) interface so that it can
  13 be used with that library, as well.
  14
  15 ## Installation and Docs
  16
  17 Install using `go get github.com/hashicorp/go-multierror`.
  18
  19 Full documentation is available at
  20 http://godoc.org/github.com/hashicorp/go-multierror
  21
  22 ## Usage
  23
  24 go-multierror is easy to use and purposely built to be unobtrusive in
  25 existing Go applications/libraries that may not be aware of it.
  26
  27 **Building a list of errors**
  28
  29 The `Append` function is used to create a list of errors. This function
  30 behaves a lot like the Go built-in `append` function: it doesn't matter
  31 if the first argument is nil, a `multierror.Error`, or any other `error`,
  32 the function behaves as you would expect.
  33
  34 ```go
  35 var result error
  36
  37 if err := step1(); err != nil {
  38         result = multierror.Append(result, err)
  39 }
  40 if err := step2(); err != nil {
  41         result = multierror.Append(result, err)
  42 }
  43
  44 return result
  45 ```
  46
  47 **Customizing the formatting of the errors**
  48
  49 By specifying a custom `ErrorFormat`, you can customize the format
  50 of the `Error() string` function:
  51
  52 ```go
  53 var result *multierror.Error
  54
  55 // ... accumulate errors here, maybe using Append
  56
  57 if result != nil {
  58         result.ErrorFormat = func([]error) string {
  59                 return "errors!"
  60         }
  61 }
  62 ```
  63
  64 **Accessing the list of errors**
  65
  66 `multierror.Error` implements `error` so if the caller doesn't know about
  67 multierror, it will work just fine. But if you're aware a multierror might
  68 be returned, you can use type switches to access the list of errors:
  69
  70 ```go
  71 if err := something(); err != nil {
  72         if merr, ok := err.(*multierror.Error); ok {
  73                 // Use merr.Errors
  74         }
  75 }
  76 ```
  77
  78 **Returning a multierror only if there are errors**
  79
  80 If you build a `multierror.Error`, you can use the `ErrorOrNil` function
  81 to return an `error` implementation only if there are errors to return:
  82
  83 ```go
  84 var result *multierror.Error
  85
  86 // ... accumulate errors here
  87
  88 // Return the `error` only if errors were added to the multierror, otherwise
  89 // return nil since there are no errors.
  90 return result.ErrorOrNil()
  91 ```