github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/juju/errors/README.md (about) 1 2 # errors 3 import "github.com/juju/errors" 4 5 [](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)