errors/errors.go

   1 package errors
   2
   3 import (
   4         "errors"
   5         "fmt"
   6         "strings"
   7 )
   8
   9 // New returns an error that formats as the given text.
  10 func New(text string) error {
  11         return errors.New(text)
  12 }
  13
  14 // wrapperError satisfies the error interface.
  15 type wrapperError struct {
  16         msg    string
  17         detail []string
  18         data   map[string]interface{}
  19         stack  []StackFrame
  20         root   error
  21 }
  22
  23 // It satisfies the error interface.
  24 func (e wrapperError) Error() string {
  25         return e.msg
  26 }
  27
  28 // Root returns the original error that was wrapped by one or more
  29 // calls to Wrap. If e does not wrap other errors, it will be returned
  30 // as-is.
  31 func Root(e error) error {
  32         if wErr, ok := e.(wrapperError); ok {
  33                 return wErr.root
  34         }
  35         return e
  36 }
  37
  38 // wrap adds a context message and stack trace to err and returns a new error
  39 // containing the new context. This function is meant to be composed within
  40 // other exported functions, such as Wrap and WithDetail.
  41 // The argument stackSkip is the number of stack frames to ascend when
  42 // generating stack straces, where 0 is the caller of wrap.
  43 func wrap(err error, msg string, stackSkip int) error {
  44         if err == nil {
  45                 return nil
  46         }
  47
  48         werr, ok := err.(wrapperError)
  49         if !ok {
  50                 werr.root = err
  51                 werr.msg = err.Error()
  52                 werr.stack = getStack(stackSkip+2, stackTraceSize)
  53         }
  54         if msg != "" {
  55                 werr.msg = msg + ": " + werr.msg
  56         }
  57
  58         return werr
  59 }
  60
  61 // Wrap adds a context message and stack trace to err and returns a new error
  62 // with the new context. Arguments are handled as in fmt.Print.
  63 // Use Root to recover the original error wrapped by one or more calls to Wrap.
  64 // Use Stack to recover the stack trace.
  65 // Wrap returns nil if err is nil.
  66 func Wrap(err error, a ...interface{}) error {
  67         if err == nil {
  68                 return nil
  69         }
  70         return wrap(err, fmt.Sprint(a...), 1)
  71 }
  72
  73 // Wrapf is like Wrap, but arguments are handled as in fmt.Printf.
  74 func Wrapf(err error, format string, a ...interface{}) error {
  75         if err == nil {
  76                 return nil
  77         }
  78         return wrap(err, fmt.Sprintf(format, a...), 1)
  79 }
  80
  81 // WithDetail returns a new error that wraps
  82 // err as a chain error messsage containing text
  83 // as its additional context.
  84 // Function Detail will return the given text
  85 // when called on the new error value.
  86 func WithDetail(err error, text string) error {
  87         if err == nil {
  88                 return nil
  89         }
  90         if text == "" {
  91                 return err
  92         }
  93         e1 := wrap(err, text, 1).(wrapperError)
  94         e1.detail = append(e1.detail, text)
  95         return e1
  96 }
  97
  98 // WithDetailf is like WithDetail, except it formats
  99 // the detail message as in fmt.Printf.
 100 // Function Detail will return the formatted text
 101 // when called on the new error value.
 102 func WithDetailf(err error, format string, v ...interface{}) error {
 103         if err == nil {
 104                 return nil
 105         }
 106         text := fmt.Sprintf(format, v...)
 107         e1 := wrap(err, text, 1).(wrapperError)
 108         e1.detail = append(e1.detail, text)
 109         return e1
 110 }
 111
 112 // Detail returns the detail message contained in err, if any.
 113 // An error has a detail message if it was made by WithDetail
 114 // or WithDetailf.
 115 func Detail(err error) string {
 116         wrapper, _ := err.(wrapperError)
 117         return strings.Join(wrapper.detail, "; ")
 118 }
 119
 120 // withData returns a new error that wraps err
 121 // as a chain error message containing v as
 122 // an extra data item.
 123 // Calling Data on the returned error yields v.
 124 // Note that if err already has a data item,
 125 // it will not be accessible via the returned error value.
 126 func withData(err error, v map[string]interface{}) error {
 127         if err == nil {
 128                 return nil
 129         }
 130         e1 := wrap(err, "", 1).(wrapperError)
 131         e1.data = v
 132         return e1
 133 }
 134
 135 // WithData returns a new error that wraps err
 136 // as a chain error message containing a value of type
 137 // map[string]interface{} as an extra data item.
 138 // The map contains the values in the map in err,
 139 // if any, plus the items in keyval.
 140 // Keyval takes the form
 141 //   k1, v1, k2, v2, ...
 142 // Values kN must be strings.
 143 // Calling Data on the returned error yields the map.
 144 // Note that if err already has a data item of any other type,
 145 // it will not be accessible via the returned error value.
 146 func WithData(err error, keyval ...interface{}) error {
 147         if err == nil {
 148                 return nil
 149         }
 150         // TODO(kr): add vet check for odd-length keyval and non-string keys
 151         newkv := make(map[string]interface{})
 152         for k, v := range Data(err) {
 153                 newkv[k] = v
 154         }
 155         for i := 0; i < len(keyval); i += 2 {
 156                 newkv[keyval[i].(string)] = keyval[i+1]
 157         }
 158         return withData(err, newkv)
 159 }
 160
 161 // Data returns the data item in err, if any.
 162 func Data(err error) map[string]interface{} {
 163         wrapper, _ := err.(wrapperError)
 164         return wrapper.data
 165 }
 166
 167 // Sub returns an error containing root as its root and
 168 // taking all other metadata (stack trace, detail, message,
 169 // and data items) from err.
 170 //
 171 // Sub returns nil when either root or err is nil.
 172 //
 173 // Use this when you need to substitute a new root error in place
 174 // of an existing error that may already hold a stack trace
 175 // or other metadata.
 176 func Sub(root, err error) error {
 177         if wrapper, ok := err.(wrapperError); ok && root != nil {
 178                 wrapper.root = Root(root)
 179                 wrapper.msg = root.Error()
 180                 root = wrapper
 181         }
 182         if err == nil {
 183                 return nil
 184         }
 185         return Wrap(root, err.Error())
 186 }