1 // Package errors provides simple error handling primitives.
2 //
3 // The traditional error handling idiom in Go is roughly akin to
4 //
5 // if err != nil {
6 // return err
7 // }
8 //
9 // which when applied recursively up the call stack results in error reports
10 // without context or debugging information. The errors package allows
11 // programmers to add context to the failure path in their code in a way
12 // that does not destroy the original value of the error.
13 //
14 // Adding context to an error
15 //
16 // The errors.Wrap function returns a new error that adds context to the
17 // original error by recording a stack trace at the point Wrap is called,
18 // together with the supplied message. For example
19 //
20 // _, err := ioutil.ReadAll(r)
21 // if err != nil {
22 // return errors.Wrap(err, "read failed")
23 // }
24 //
25 // If additional control is required, the errors.WithStack and
26 // errors.WithMessage functions destructure errors.Wrap into its component
27 // operations: annotating an error with a stack trace and with a message,
28 // respectively.
29 //
30 // Retrieving the cause of an error
31 //
32 // Using errors.Wrap constructs a stack of errors, adding context to the
33 // preceding error. Depending on the nature of the error it may be necessary
34 // to reverse the operation of errors.Wrap to retrieve the original error
35 // for inspection. Any error value which implements this interface
36 //
37 // type causer interface {
38 // Cause() error
39 // }
40 //
41 // can be inspected by errors.Cause. errors.Cause will recursively retrieve
42 // the topmost error that does not implement causer, which is assumed to be
43 // the original cause. For example:
44 //
45 // switch err := errors.Cause(err).(type) {
46 // case *MyError:
47 // // handle specifically
48 // default:
49 // // unknown error
50 // }
51 //
52 // Although the causer interface is not exported by this package, it is
53 // considered a part of its stable public interface.
54 //
55 // Formatted printing of errors
56 //
57 // All error values returned from this package implement fmt.Formatter and can
58 // be formatted by the fmt package. The following verbs are supported:
59 //
60 // %s print the error. If the error has a Cause it will be
61 // printed recursively.
62 // %v see %s
63 // %+v extended format. Each Frame of the error's StackTrace will
64 // be printed in detail.
65 //
66 // Retrieving the stack trace of an error or wrapper
67 //
68 // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are
69 // invoked. This information can be retrieved with the following interface:
70 //
71 // type stackTracer interface {
72 // StackTrace() errors.StackTrace
73 // }
74 //
75 // The returned errors.StackTrace type is defined as
76 //
77 // type StackTrace []Frame
78 //
79 // The Frame type represents a call site in the stack trace. Frame supports
80 // the fmt.Formatter interface that can be used for printing information about
81 // the stack trace of this error. For example:
82 //
83 // if err, ok := err.(stackTracer); ok {
84 // for _, f := range err.StackTrace() {
85 // fmt.Printf("%+s:%d\n", f, f)
86 // }
87 // }
88 //
89 // Although the stackTracer interface is not exported by this package, it is
90 // considered a part of its stable public interface.
91 //
92 // See the documentation for Frame.Format for more details.
93 package errors
94 95 import (
96 "fmt"
97 "io"
98 )
99 100 // New returns an error with the supplied message.
101 // New also records the stack trace at the point it was called.
102 func New(message string) error {
103 return &fundamental{
104 msg: message,
105 stack: callers(),
106 }
107 }
108 109 // Errorf formats according to a format specifier and returns the string
110 // as a value that satisfies error.
111 // Errorf also records the stack trace at the point it was called.
112 func Errorf(format string, args ...interface{}) error {
113 return &fundamental{
114 msg: fmt.Sprintf(format, args...),
115 stack: callers(),
116 }
117 }
118 119 // fundamental is an error that has a message and a stack, but no caller.
120 type fundamental struct {
121 msg string
122 *stack
123 }
124 125 func (f *fundamental) Error() string { return f.msg }
126 127 func (f *fundamental) Format(s fmt.State, verb rune) {
128 switch verb {
129 case 'v':
130 if s.Flag('+') {
131 io.WriteString(s, f.msg)
132 f.stack.Format(s, verb)
133 return
134 }
135 fallthrough
136 case 's':
137 io.WriteString(s, f.msg)
138 case 'q':
139 fmt.Fprintf(s, "%q", f.msg)
140 }
141 }
142 143 // WithStack annotates err with a stack trace at the point WithStack was called.
144 // If err is nil, WithStack returns nil.
145 func WithStack(err error) error {
146 if err == nil {
147 return nil
148 }
149 return &withStack{
150 err,
151 callers(),
152 }
153 }
154 155 type withStack struct {
156 error
157 *stack
158 }
159 160 func (w *withStack) Cause() error { return w.error }
161 162 // Unwrap provides compatibility for Go 1.13 error chains.
163 func (w *withStack) Unwrap() error { return w.error }
164 165 func (w *withStack) Format(s fmt.State, verb rune) {
166 switch verb {
167 case 'v':
168 if s.Flag('+') {
169 fmt.Fprintf(s, "%+v", w.Cause())
170 w.stack.Format(s, verb)
171 return
172 }
173 fallthrough
174 case 's':
175 io.WriteString(s, w.Error())
176 case 'q':
177 fmt.Fprintf(s, "%q", w.Error())
178 }
179 }
180 181 // Wrap returns an error annotating err with a stack trace
182 // at the point Wrap is called, and the supplied message.
183 // If err is nil, Wrap returns nil.
184 func Wrap(err error, message string) error {
185 if err == nil {
186 return nil
187 }
188 err = &withMessage{
189 cause: err,
190 msg: message,
191 }
192 return &withStack{
193 err,
194 callers(),
195 }
196 }
197 198 // Wrapf returns an error annotating err with a stack trace
199 // at the point Wrapf is called, and the format specifier.
200 // If err is nil, Wrapf returns nil.
201 func Wrapf(err error, format string, args ...interface{}) error {
202 if err == nil {
203 return nil
204 }
205 err = &withMessage{
206 cause: err,
207 msg: fmt.Sprintf(format, args...),
208 }
209 return &withStack{
210 err,
211 callers(),
212 }
213 }
214 215 // WithMessage annotates err with a new message.
216 // If err is nil, WithMessage returns nil.
217 func WithMessage(err error, message string) error {
218 if err == nil {
219 return nil
220 }
221 return &withMessage{
222 cause: err,
223 msg: message,
224 }
225 }
226 227 // WithMessagef annotates err with the format specifier.
228 // If err is nil, WithMessagef returns nil.
229 func WithMessagef(err error, format string, args ...interface{}) error {
230 if err == nil {
231 return nil
232 }
233 return &withMessage{
234 cause: err,
235 msg: fmt.Sprintf(format, args...),
236 }
237 }
238 239 type withMessage struct {
240 cause error
241 msg string
242 }
243 244 func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
245 func (w *withMessage) Cause() error { return w.cause }
246 247 // Unwrap provides compatibility for Go 1.13 error chains.
248 func (w *withMessage) Unwrap() error { return w.cause }
249 250 func (w *withMessage) Format(s fmt.State, verb rune) {
251 switch verb {
252 case 'v':
253 if s.Flag('+') {
254 fmt.Fprintf(s, "%+v\n", w.Cause())
255 io.WriteString(s, w.msg)
256 return
257 }
258 fallthrough
259 case 's', 'q':
260 io.WriteString(s, w.Error())
261 }
262 }
263 264 // Cause returns the underlying cause of the error, if possible.
265 // An error value has a cause if it implements the following
266 // interface:
267 //
268 // type causer interface {
269 // Cause() error
270 // }
271 //
272 // If the error does not implement Cause, the original error will
273 // be returned. If the error is nil, nil will be returned without further
274 // investigation.
275 func Cause(err error) error {
276 type causer interface {
277 Cause() error
278 }
279 280 for err != nil {
281 cause, ok := err.(causer)
282 if !ok {
283 break
284 }
285 err = cause.Cause()
286 }
287 return err
288 }
289