← Back to branch summary

~nskaggs/+junk/juju-packaging-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/errors/README.md

  • Committer: Nicholas Skaggs
  • Date: 2016-10-27 20:23:11 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161027202311-sux4jk2o73p1d6rg
Re-add src

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/errors/README.md
 
1
 
 
2
# errors
 
3
    import "github.com/juju/errors"
 
4
 
 
5
[![GoDoc](https://godoc.org/github.com/juju/errors?status.svg)](https://godoc.org/github.com/juju/errors)
 
6
 
 
7
The juju/errors provides an easy way to annotate errors without losing the
 
8
orginal error context.
 
9
 
 
10
The exported `New` and `Errorf` functions are designed to replace the
 
11
`errors.New` and `fmt.Errorf` functions respectively. The same underlying
 
12
error is there, but the package also records the location at which the error
 
13
was created.
 
14
 
 
15
A primary use case for this library is to add extra context any time an
 
16
error is returned from a function.
 
17
 
 
18
 
 
19
            if err := SomeFunc(); err != nil {
 
20
                    return err
 
21
                }
 
22
 
 
23
This instead becomes:
 
24
 
 
25
 
 
26
            if err := SomeFunc(); err != nil {
 
27
                    return errors.Trace(err)
 
28
                }
 
29
 
 
30
which just records the file and line number of the Trace call, or
 
31
 
 
32
 
 
33
            if err := SomeFunc(); err != nil {
 
34
                    return errors.Annotate(err, "more context")
 
35
                }
 
36
 
 
37
which also adds an annotation to the error.
 
38
 
 
39
When you want to check to see if an error is of a particular type, a helper
 
40
function is normally exported by the package that returned the error, like the
 
41
`os` package does.  The underlying cause of the error is available using the
 
42
`Cause` function.
 
43
 
 
44
 
 
45
        os.IsNotExist(errors.Cause(err))
 
46
 
 
47
The result of the `Error()` call on an annotated error is the annotations joined
 
48
with colons, then the result of the `Error()` method for the underlying error
 
49
that was the cause.
 
50
 
 
51
 
 
52
        err := errors.Errorf("original")
 
53
        err = errors.Annotatef(err, "context")
 
54
        err = errors.Annotatef(err, "more context")
 
55
        err.Error() -> "more context: context: original"
 
56
 
 
57
Obviously recording the file, line and functions is not very useful if you
 
58
cannot get them back out again.
 
59
 
 
60
 
 
61
        errors.ErrorStack(err)
 
62
 
 
63
will return something like:
 
64
 
 
65
 
 
66
        first error
 
67
        github.com/juju/errors/annotation_test.go:193:
 
68
        github.com/juju/errors/annotation_test.go:194: annotation
 
69
        github.com/juju/errors/annotation_test.go:195:
 
70
        github.com/juju/errors/annotation_test.go:196: more context
 
71
        github.com/juju/errors/annotation_test.go:197:
 
72
 
 
73
The first error was generated by an external system, so there was no location
 
74
associated. The second, fourth, and last lines were generated with Trace calls,
 
75
and the other two through Annotate.
 
76
 
 
77
Sometimes when responding to an error you want to return a more specific error
 
78
for the situation.
 
79
 
 
80
 
 
81
            if err := FindField(field); err != nil {
 
82
                    return errors.Wrap(err, errors.NotFoundf(field))
 
83
                }
 
84
 
 
85
This returns an error where the complete error stack is still available, and
 
86
`errors.Cause()` will return the `NotFound` error.
 
87
 
 
88
 
 
89
 
 
90
 
 
91
 
 
92
 
 
93
## func AlreadyExistsf
 
94
``` go
 
95
func AlreadyExistsf(format string, args ...interface{}) error
 
96
```
 
97
AlreadyExistsf returns an error which satisfies IsAlreadyExists().
 
98
 
 
99
 
 
100
## func Annotate
 
101
``` go
 
102
func Annotate(other error, message string) error
 
103
```
 
104
Annotate is used to add extra context to an existing error. The location of
 
105
the Annotate call is recorded with the annotations. The file, line and
 
106
function are also recorded.
 
107
 
 
108
For example:
 
109
 
 
110
 
 
111
        if err := SomeFunc(); err != nil {
 
112
            return errors.Annotate(err, "failed to frombulate")
 
113
        }
 
114
 
 
115
 
 
116
## func Annotatef
 
117
``` go
 
118
func Annotatef(other error, format string, args ...interface{}) error
 
119
```
 
120
Annotatef is used to add extra context to an existing error. The location of
 
121
the Annotate call is recorded with the annotations. The file, line and
 
122
function are also recorded.
 
123
 
 
124
For example:
 
125
 
 
126
 
 
127
        if err := SomeFunc(); err != nil {
 
128
            return errors.Annotatef(err, "failed to frombulate the %s", arg)
 
129
        }
 
130
 
 
131
 
 
132
## func Cause
 
133
``` go
 
134
func Cause(err error) error
 
135
```
 
136
Cause returns the cause of the given error.  This will be either the
 
137
original error, or the result of a Wrap or Mask call.
 
138
 
 
139
Cause is the usual way to diagnose errors that may have been wrapped by
 
140
the other errors functions.
 
141
 
 
142
 
 
143
## func DeferredAnnotatef
 
144
``` go
 
145
func DeferredAnnotatef(err *error, format string, args ...interface{})
 
146
```
 
147
DeferredAnnotatef annotates the given error (when it is not nil) with the given
 
148
format string and arguments (like fmt.Sprintf). If *err is nil, DeferredAnnotatef
 
149
does nothing. This method is used in a defer statement in order to annotate any
 
150
resulting error with the same message.
 
151
 
 
152
For example:
 
153
 
 
154
 
 
155
        defer DeferredAnnotatef(&err, "failed to frombulate the %s", arg)
 
156
 
 
157
 
 
158
## func Details
 
159
``` go
 
160
func Details(err error) string
 
161
```
 
162
Details returns information about the stack of errors wrapped by err, in
 
163
the format:
 
164
 
 
165
 
 
166
        [{filename:99: error one} {otherfile:55: cause of error one}]
 
167
 
 
168
This is a terse alternative to ErrorStack as it returns a single line.
 
169
 
 
170
 
 
171
## func ErrorStack
 
172
``` go
 
173
func ErrorStack(err error) string
 
174
```
 
175
ErrorStack returns a string representation of the annotated error. If the
 
176
error passed as the parameter is not an annotated error, the result is
 
177
simply the result of the Error() method on that error.
 
178
 
 
179
If the error is an annotated error, a multi-line string is returned where
 
180
each line represents one entry in the annotation stack. The full filename
 
181
from the call stack is used in the output.
 
182
 
 
183
 
 
184
        first error
 
185
        github.com/juju/errors/annotation_test.go:193:
 
186
        github.com/juju/errors/annotation_test.go:194: annotation
 
187
        github.com/juju/errors/annotation_test.go:195:
 
188
        github.com/juju/errors/annotation_test.go:196: more context
 
189
        github.com/juju/errors/annotation_test.go:197:
 
190
 
 
191
 
 
192
## func Errorf
 
193
``` go
 
194
func Errorf(format string, args ...interface{}) error
 
195
```
 
196
Errorf creates a new annotated error and records the location that the
 
197
error is created.  This should be a drop in replacement for fmt.Errorf.
 
198
 
 
199
For example:
 
200
 
 
201
 
 
202
        return errors.Errorf("validation failed: %s", message)
 
203
 
 
204
 
 
205
## func IsAlreadyExists
 
206
``` go
 
207
func IsAlreadyExists(err error) bool
 
208
```
 
209
IsAlreadyExists reports whether the error was created with
 
210
AlreadyExistsf() or NewAlreadyExists().
 
211
 
 
212
 
 
213
## func IsNotFound
 
214
``` go
 
215
func IsNotFound(err error) bool
 
216
```
 
217
IsNotFound reports whether err was created with NotFoundf() or
 
218
NewNotFound().
 
219
 
 
220
 
 
221
## func IsNotImplemented
 
222
``` go
 
223
func IsNotImplemented(err error) bool
 
224
```
 
225
IsNotImplemented reports whether err was created with
 
226
NotImplementedf() or NewNotImplemented().
 
227
 
 
228
 
 
229
## func IsNotSupported
 
230
``` go
 
231
func IsNotSupported(err error) bool
 
232
```
 
233
IsNotSupported reports whether the error was created with
 
234
NotSupportedf() or NewNotSupported().
 
235
 
 
236
 
 
237
## func IsNotValid
 
238
``` go
 
239
func IsNotValid(err error) bool
 
240
```
 
241
IsNotValid reports whether the error was created with NotValidf() or
 
242
NewNotValid().
 
243
 
 
244
 
 
245
## func IsUnauthorized
 
246
``` go
 
247
func IsUnauthorized(err error) bool
 
248
```
 
249
IsUnauthorized reports whether err was created with Unauthorizedf() or
 
250
NewUnauthorized().
 
251
 
 
252
 
 
253
## func Mask
 
254
``` go
 
255
func Mask(other error) error
 
256
```
 
257
Mask hides the underlying error type, and records the location of the masking.
 
258
 
 
259
 
 
260
## func Maskf
 
261
``` go
 
262
func Maskf(other error, format string, args ...interface{}) error
 
263
```
 
264
Mask masks the given error with the given format string and arguments (like
 
265
fmt.Sprintf), returning a new error that maintains the error stack, but
 
266
hides the underlying error type.  The error string still contains the full
 
267
annotations. If you want to hide the annotations, call Wrap.
 
268
 
 
269
 
 
270
## func New
 
271
``` go
 
272
func New(message string) error
 
273
```
 
274
New is a drop in replacement for the standard libary errors module that records
 
275
the location that the error is created.
 
276
 
 
277
For example:
 
278
 
 
279
 
 
280
        return errors.New("validation failed")
 
281
 
 
282
 
 
283
## func NewAlreadyExists
 
284
``` go
 
285
func NewAlreadyExists(err error, msg string) error
 
286
```
 
287
NewAlreadyExists returns an error which wraps err and satisfies
 
288
IsAlreadyExists().
 
289
 
 
290
 
 
291
## func NewNotFound
 
292
``` go
 
293
func NewNotFound(err error, msg string) error
 
294
```
 
295
NewNotFound returns an error which wraps err that satisfies
 
296
IsNotFound().
 
297
 
 
298
 
 
299
## func NewNotImplemented
 
300
``` go
 
301
func NewNotImplemented(err error, msg string) error
 
302
```
 
303
NewNotImplemented returns an error which wraps err and satisfies
 
304
IsNotImplemented().
 
305
 
 
306
 
 
307
## func NewNotSupported
 
308
``` go
 
309
func NewNotSupported(err error, msg string) error
 
310
```
 
311
NewNotSupported returns an error which wraps err and satisfies
 
312
IsNotSupported().
 
313
 
 
314
 
 
315
## func NewNotValid
 
316
``` go
 
317
func NewNotValid(err error, msg string) error
 
318
```
 
319
NewNotValid returns an error which wraps err and satisfies IsNotValid().
 
320
 
 
321
 
 
322
## func NewUnauthorized
 
323
``` go
 
324
func NewUnauthorized(err error, msg string) error
 
325
```
 
326
NewUnauthorized returns an error which wraps err and satisfies
 
327
IsUnauthorized().
 
328
 
 
329
 
 
330
## func NotFoundf
 
331
``` go
 
332
func NotFoundf(format string, args ...interface{}) error
 
333
```
 
334
NotFoundf returns an error which satisfies IsNotFound().
 
335
 
 
336
 
 
337
## func NotImplementedf
 
338
``` go
 
339
func NotImplementedf(format string, args ...interface{}) error
 
340
```
 
341
NotImplementedf returns an error which satisfies IsNotImplemented().
 
342
 
 
343
 
 
344
## func NotSupportedf
 
345
``` go
 
346
func NotSupportedf(format string, args ...interface{}) error
 
347
```
 
348
NotSupportedf returns an error which satisfies IsNotSupported().
 
349
 
 
350
 
 
351
## func NotValidf
 
352
``` go
 
353
func NotValidf(format string, args ...interface{}) error
 
354
```
 
355
NotValidf returns an error which satisfies IsNotValid().
 
356
 
 
357
 
 
358
## func Trace
 
359
``` go
 
360
func Trace(other error) error
 
361
```
 
362
Trace adds the location of the Trace call to the stack.  The Cause of the
 
363
resulting error is the same as the error parameter.  If the other error is
 
364
nil, the result will be nil.
 
365
 
 
366
For example:
 
367
 
 
368
 
 
369
        if err := SomeFunc(); err != nil {
 
370
            return errors.Trace(err)
 
371
        }
 
372
 
 
373
 
 
374
## func Unauthorizedf
 
375
``` go
 
376
func Unauthorizedf(format string, args ...interface{}) error
 
377
```
 
378
Unauthorizedf returns an error which satisfies IsUnauthorized().
 
379
 
 
380
 
 
381
## func Wrap
 
382
``` go
 
383
func Wrap(other, newDescriptive error) error
 
384
```
 
385
Wrap changes the Cause of the error. The location of the Wrap call is also
 
386
stored in the error stack.
 
387
 
 
388
For example:
 
389
 
 
390
 
 
391
        if err := SomeFunc(); err != nil {
 
392
            newErr := &packageError{"more context", private_value}
 
393
            return errors.Wrap(err, newErr)
 
394
        }
 
395
 
 
396
 
 
397
## func Wrapf
 
398
``` go
 
399
func Wrapf(other, newDescriptive error, format string, args ...interface{}) error
 
400
```
 
401
Wrapf changes the Cause of the error, and adds an annotation. The location
 
402
of the Wrap call is also stored in the error stack.
 
403
 
 
404
For example:
 
405
 
 
406
 
 
407
        if err := SomeFunc(); err != nil {
 
408
            return errors.Wrapf(err, simpleErrorType, "invalid value %q", value)
 
409
        }
 
410
 
 
411
 
 
412
 
 
413
## type Err
 
414
``` go
 
415
type Err struct {
 
416
    // contains filtered or unexported fields
 
417
}
 
418
```
 
419
Err holds a description of an error along with information about
 
420
where the error was created.
 
421
 
 
422
It may be embedded in custom error types to add extra information that
 
423
this errors package can understand.
 
424
 
 
425
 
 
426
 
 
427
 
 
428
 
 
429
 
 
430
 
 
431
 
 
432
 
 
433
### func NewErr
 
434
``` go
 
435
func NewErr(format string, args ...interface{}) Err
 
436
```
 
437
NewErr is used to return an Err for the purpose of embedding in other
 
438
structures.  The location is not specified, and needs to be set with a call
 
439
to SetLocation.
 
440
 
 
441
For example:
 
442
 
 
443
 
 
444
        type FooError struct {
 
445
            errors.Err
 
446
            code int
 
447
        }
 
448
        
 
449
        func NewFooError(code int) error {
 
450
            err := &FooError{errors.NewErr("foo"), code}
 
451
            err.SetLocation(1)
 
452
            return err
 
453
        }
 
454
 
 
455
 
 
456
 
 
457
 
 
458
### func (\*Err) Cause
 
459
``` go
 
460
func (e *Err) Cause() error
 
461
```
 
462
The Cause of an error is the most recent error in the error stack that
 
463
meets one of these criteria: the original error that was raised; the new
 
464
error that was passed into the Wrap function; the most recently masked
 
465
error; or nil if the error itself is considered the Cause.  Normally this
 
466
method is not invoked directly, but instead through the Cause stand alone
 
467
function.
 
468
 
 
469
 
 
470
 
 
471
### func (\*Err) Error
 
472
``` go
 
473
func (e *Err) Error() string
 
474
```
 
475
Error implements error.Error.
 
476
 
 
477
 
 
478
 
 
479
### func (\*Err) Location
 
480
``` go
 
481
func (e *Err) Location() (filename string, line int)
 
482
```
 
483
Location is the file and line of where the error was most recently
 
484
created or annotated.
 
485
 
 
486
 
 
487
 
 
488
### func (\*Err) Message
 
489
``` go
 
490
func (e *Err) Message() string
 
491
```
 
492
Message returns the message stored with the most recent location. This is
 
493
the empty string if the most recent call was Trace, or the message stored
 
494
with Annotate or Mask.
 
495
 
 
496
 
 
497
 
 
498
### func (\*Err) SetLocation
 
499
``` go
 
500
func (e *Err) SetLocation(callDepth int)
 
501
```
 
502
SetLocation records the source location of the error at callDepth stack
 
503
frames above the call.
 
504
 
 
505
 
 
506
 
 
507
### func (\*Err) StackTrace
 
508
``` go
 
509
func (e *Err) StackTrace() []string
 
510
```
 
511
StackTrace returns one string for each location recorded in the stack of
 
512
errors. The first value is the originating error, with a line for each
 
513
other annotation or tracing of the error.
 
514
 
 
515
 
 
516
 
 
517
### func (\*Err) Underlying
 
518
``` go
 
519
func (e *Err) Underlying() error
 
520
```
 
521
Underlying returns the previous error in the error stack, if any. A client
 
522
should not ever really call this method.  It is used to build the error
 
523
stack and should not be introspected by client calls.  Or more
 
524
specifically, clients should not depend on anything but the `Cause` of an
 
525
error.
 
526
 
 
527
 
 
528
 
 
529
 
 
530
 
 
531
 
 
532
 
 
533
 
 
534
 
 
535
- - -
 
536
Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)
 
 
b'\\ No newline at end of file'