blob: 7421f326ffe8402b17f4b064d33a862d786a6ef1 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001// 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", 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.
93package errors
94
95import (
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.
102func 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.
112func 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.
120type fundamental struct {
121 msg string
122 *stack
123}
124
125func (f *fundamental) Error() string { return f.msg }
126
127func (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.
145func WithStack(err error) error {
146 if err == nil {
147 return nil
148 }
149 return &withStack{
150 err,
151 callers(),
152 }
153}
154
155type withStack struct {
156 error
157 *stack
158}
159
160func (w *withStack) Cause() error { return w.error }
161
162func (w *withStack) Format(s fmt.State, verb rune) {
163 switch verb {
164 case 'v':
165 if s.Flag('+') {
166 fmt.Fprintf(s, "%+v", w.Cause())
167 w.stack.Format(s, verb)
168 return
169 }
170 fallthrough
171 case 's':
172 io.WriteString(s, w.Error())
173 case 'q':
174 fmt.Fprintf(s, "%q", w.Error())
175 }
176}
177
178// Wrap returns an error annotating err with a stack trace
179// at the point Wrap is called, and the supplied message.
180// If err is nil, Wrap returns nil.
181func Wrap(err error, message string) error {
182 if err == nil {
183 return nil
184 }
185 err = &withMessage{
186 cause: err,
187 msg: message,
188 }
189 return &withStack{
190 err,
191 callers(),
192 }
193}
194
195// Wrapf returns an error annotating err with a stack trace
196// at the point Wrapf is called, and the format specifier.
197// If err is nil, Wrapf returns nil.
198func Wrapf(err error, format string, args ...interface{}) error {
199 if err == nil {
200 return nil
201 }
202 err = &withMessage{
203 cause: err,
204 msg: fmt.Sprintf(format, args...),
205 }
206 return &withStack{
207 err,
208 callers(),
209 }
210}
211
212// WithMessage annotates err with a new message.
213// If err is nil, WithMessage returns nil.
214func WithMessage(err error, message string) error {
215 if err == nil {
216 return nil
217 }
218 return &withMessage{
219 cause: err,
220 msg: message,
221 }
222}
223
224// WithMessagef annotates err with the format specifier.
225// If err is nil, WithMessagef returns nil.
226func WithMessagef(err error, format string, args ...interface{}) error {
227 if err == nil {
228 return nil
229 }
230 return &withMessage{
231 cause: err,
232 msg: fmt.Sprintf(format, args...),
233 }
234}
235
236type withMessage struct {
237 cause error
238 msg string
239}
240
241func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
242func (w *withMessage) Cause() error { return w.cause }
243
244func (w *withMessage) Format(s fmt.State, verb rune) {
245 switch verb {
246 case 'v':
247 if s.Flag('+') {
248 fmt.Fprintf(s, "%+v\n", w.Cause())
249 io.WriteString(s, w.msg)
250 return
251 }
252 fallthrough
253 case 's', 'q':
254 io.WriteString(s, w.Error())
255 }
256}
257
258// Cause returns the underlying cause of the error, if possible.
259// An error value has a cause if it implements the following
260// interface:
261//
262// type causer interface {
263// Cause() error
264// }
265//
266// If the error does not implement Cause, the original error will
267// be returned. If the error is nil, nil will be returned without further
268// investigation.
269func Cause(err error) error {
270 type causer interface {
271 Cause() error
272 }
273
274 for err != nil {
275 cause, ok := err.(causer)
276 if !ok {
277 break
278 }
279 err = cause.Cause()
280 }
281 return err
282}