vendor/github.com/hashicorp/errwrap/README.md

   1 # errwrap
   2
   3 `errwrap` is a package for Go that formalizes the pattern of wrapping errors
   4 and checking if an error contains another error.
   5
   6 There is a common pattern in Go of taking a returned `error` value and
   7 then wrapping it (such as with `fmt.Errorf`) before returning it. The problem
   8 with this pattern is that you completely lose the original `error` structure.
   9
  10 Arguably the _correct_ approach is that you should make a custom structure
  11 implementing the `error` interface, and have the original error as a field
  12 on that structure, such [as this example](http://golang.org/pkg/os/#PathError).
  13 This is a good approach, but you have to know the entire chain of possible
  14 rewrapping that happens, when you might just care about one.
  15
  16 `errwrap` formalizes this pattern (it doesn't matter what approach you use
  17 above) by giving a single interface for wrapping errors, checking if a specific
  18 error is wrapped, and extracting that error.
  19
  20 ## Installation and Docs
  21
  22 Install using `go get github.com/hashicorp/errwrap`.
  23
  24 Full documentation is available at
  25 http://godoc.org/github.com/hashicorp/errwrap
  26
  27 ## Usage
  28
  29 #### Basic Usage
  30
  31 Below is a very basic example of its usage:
  32
  33 ```go
  34 // A function that always returns an error, but wraps it, like a real
  35 // function might.
  36 func tryOpen() error {
  37         _, err := os.Open("/i/dont/exist")
  38         if err != nil {
  39                 return errwrap.Wrapf("Doesn't exist: {{err}}", err)
  40         }
  41
  42         return nil
  43 }
  44
  45 func main() {
  46         err := tryOpen()
  47
  48         // We can use the Contains helpers to check if an error contains
  49         // another error. It is safe to do this with a nil error, or with
  50         // an error that doesn't even use the errwrap package.
  51         if errwrap.Contains(err, "does not exist") {
  52                 // Do something
  53         }
  54         if errwrap.ContainsType(err, new(os.PathError)) {
  55                 // Do something
  56         }
  57
  58         // Or we can use the associated `Get` functions to just extract
  59         // a specific error. This would return nil if that specific error doesn't
  60         // exist.
  61         perr := errwrap.GetType(err, new(os.PathError))
  62 }
  63 ```
  64
  65 #### Custom Types
  66
  67 If you're already making custom types that properly wrap errors, then
  68 you can get all the functionality of `errwraps.Contains` and such by
  69 implementing the `Wrapper` interface with just one function. Example:
  70
  71 ```go
  72 type AppError {
  73   Code ErrorCode
  74   Err  error
  75 }
  76
  77 func (e *AppError) WrappedErrors() []error {
  78   return []error{e.Err}
  79 }
  80 ```
  81
  82 Now this works:
  83
  84 ```go
  85 err := &AppError{Err: fmt.Errorf("an error")}
  86 if errwrap.ContainsType(err, fmt.Errorf("")) {
  87         // This will work!
  88 }
  89 ```