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  [![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)