1// Package errwrap implements methods to formalize error wrapping in Go. 2// 3// All of the top-level functions that take an `error` are built to be able 4// to take any error, not just wrapped errors. This allows you to use errwrap 5// without having to type-check and type-cast everywhere. 6package errwrap 7 8import ( 9 "errors" 10 "reflect" 11 "strings" 12) 13 14// WalkFunc is the callback called for Walk. 15type WalkFunc func(error) 16 17// Wrapper is an interface that can be implemented by custom types to 18// have all the Contains, Get, etc. functions in errwrap work. 19// 20// When Walk reaches a Wrapper, it will call the callback for every 21// wrapped error in addition to the wrapper itself. Since all the top-level 22// functions in errwrap use Walk, this means that all those functions work 23// with your custom type. 24type Wrapper interface { 25 WrappedErrors() []error 26} 27 28// Wrap defines that outer wraps inner, returning an error type that 29// can be cleanly used with the other methods in this package, such as 30// Contains, GetAll, etc. 31// 32// This function won't modify the error message at all (the outer message 33// will be used). 34func Wrap(outer, inner error) error { 35 return &wrappedError{ 36 Outer: outer, 37 Inner: inner, 38 } 39} 40 41// Wrapf wraps an error with a formatting message. This is similar to using 42// `fmt.Errorf` to wrap an error. If you're using `fmt.Errorf` to wrap 43// errors, you should replace it with this. 44// 45// format is the format of the error message. The string '{{err}}' will 46// be replaced with the original error message. 47func Wrapf(format string, err error) error { 48 outerMsg := "<nil>" 49 if err != nil { 50 outerMsg = err.Error() 51 } 52 53 outer := errors.New(strings.Replace( 54 format, "{{err}}", outerMsg, -1)) 55 56 return Wrap(outer, err) 57} 58 59// Contains checks if the given error contains an error with the 60// message msg. If err is not a wrapped error, this will always return 61// false unless the error itself happens to match this msg. 62func Contains(err error, msg string) bool { 63 return len(GetAll(err, msg)) > 0 64} 65 66// ContainsType checks if the given error contains an error with 67// the same concrete type as v. If err is not a wrapped error, this will 68// check the err itself. 69func ContainsType(err error, v interface{}) bool { 70 return len(GetAllType(err, v)) > 0 71} 72 73// Get is the same as GetAll but returns the deepest matching error. 74func Get(err error, msg string) error { 75 es := GetAll(err, msg) 76 if len(es) > 0 { 77 return es[len(es)-1] 78 } 79 80 return nil 81} 82 83// GetType is the same as GetAllType but returns the deepest matching error. 84func GetType(err error, v interface{}) error { 85 es := GetAllType(err, v) 86 if len(es) > 0 { 87 return es[len(es)-1] 88 } 89 90 return nil 91} 92 93// GetAll gets all the errors that might be wrapped in err with the 94// given message. The order of the errors is such that the outermost 95// matching error (the most recent wrap) is index zero, and so on. 96func GetAll(err error, msg string) []error { 97 var result []error 98 99 Walk(err, func(err error) { 100 if err.Error() == msg { 101 result = append(result, err) 102 } 103 }) 104 105 return result 106} 107 108// GetAllType gets all the errors that are the same type as v. 109// 110// The order of the return value is the same as described in GetAll. 111func GetAllType(err error, v interface{}) []error { 112 var result []error 113 114 var search string 115 if v != nil { 116 search = reflect.TypeOf(v).String() 117 } 118 Walk(err, func(err error) { 119 var needle string 120 if err != nil { 121 needle = reflect.TypeOf(err).String() 122 } 123 124 if needle == search { 125 result = append(result, err) 126 } 127 }) 128 129 return result 130} 131 132// Walk walks all the wrapped errors in err and calls the callback. If 133// err isn't a wrapped error, this will be called once for err. If err 134// is a wrapped error, the callback will be called for both the wrapper 135// that implements error as well as the wrapped error itself. 136func Walk(err error, cb WalkFunc) { 137 if err == nil { 138 return 139 } 140 141 switch e := err.(type) { 142 case *wrappedError: 143 cb(e.Outer) 144 Walk(e.Inner, cb) 145 case Wrapper: 146 cb(err) 147 148 for _, err := range e.WrappedErrors() { 149 Walk(err, cb) 150 } 151 default: 152 cb(err) 153 } 154} 155 156// wrappedError is an implementation of error that has both the 157// outer and inner errors. 158type wrappedError struct { 159 Outer error 160 Inner error 161} 162 163func (w *wrappedError) Error() string { 164 return w.Outer.Error() 165} 166 167func (w *wrappedError) WrappedErrors() []error { 168 return []error{w.Outer, w.Inner} 169} 170