9 // New returns an error that formats as the given text.
10 func New(text string) error {
11 return errors.New(text)
14 // wrapperError satisfies the error interface.
15 type wrapperError struct {
18 data map[string]interface{}
23 // It satisfies the error interface.
24 func (e wrapperError) Error() string {
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
31 func Root(e error) error {
32 if wErr, ok := e.(wrapperError); ok {
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 {
48 werr, ok := err.(wrapperError)
51 werr.msg = err.Error()
52 werr.stack = getStack(stackSkip+2, stackTraceSize)
55 werr.msg = msg + ": " + werr.msg
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 {
70 return wrap(err, fmt.Sprint(a...), 1)
73 // Wrapf is like Wrap, but arguments are handled as in fmt.Printf.
74 func Wrapf(err error, format string, a ...interface{}) error {
78 return wrap(err, fmt.Sprintf(format, a...), 1)
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 {
93 e1 := wrap(err, text, 1).(wrapperError)
94 e1.detail = append(e1.detail, text)
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 {
106 text := fmt.Sprintf(format, v...)
107 e1 := wrap(err, text, 1).(wrapperError)
108 e1.detail = append(e1.detail, text)
112 // Detail returns the detail message contained in err, if any.
113 // An error has a detail message if it was made by WithDetail
115 func Detail(err error) string {
116 wrapper, _ := err.(wrapperError)
117 return strings.Join(wrapper.detail, "; ")
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 {
130 e1 := wrap(err, "", 1).(wrapperError)
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 {
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) {
155 for i := 0; i < len(keyval); i += 2 {
156 newkv[keyval[i].(string)] = keyval[i+1]
158 return withData(err, newkv)
161 // Data returns the data item in err, if any.
162 func Data(err error) map[string]interface{} {
163 wrapper, _ := err.(wrapperError)
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.
171 // Sub returns nil when either root or err is nil.
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()
185 return Wrap(root, err.Error())