194 lines
3.7 KiB
Markdown
194 lines
3.7 KiB
Markdown
# adverr
|
|
--
|
|
import "adverr"
|
|
|
|
Package adverr implements errors with call stack traces as well as error
|
|
templates for error equality
|
|
|
|
|
|
Usage examples
|
|
|
|
Creating templates:
|
|
|
|
var (
|
|
ErrDoStuffFailed = adverr.NewErrTmpl("ErrDoStuffFailed", "Could'nt do stuff because of %s")
|
|
)
|
|
|
|
Creating independent error (without error template):
|
|
|
|
func doStuffWithIndependentErr() error {
|
|
return adverr.New("Could'nt do stuff")
|
|
}
|
|
|
|
Creating error based on template:
|
|
|
|
func doStuff() error {
|
|
return ErrDoStuffFailed.New("reasons")
|
|
}
|
|
|
|
Printing errors on stderr convieniently:
|
|
|
|
Print(myErr)
|
|
Println(myErr)
|
|
|
|
Printing errors on stderr and exit with exitcode:
|
|
|
|
Fatal(myErr, 1)
|
|
Fatalln(myErr, 1)
|
|
|
|
Advantages of error templates
|
|
|
|
two errors made by the same template will return true when called with errors.Is()
|
|
|
|
## Usage
|
|
|
|
```go
|
|
var CallStackLength int = 100
|
|
```
|
|
CallStackLength decides how many calls from the call stack should be gathered at
|
|
most
|
|
|
|
```go
|
|
var (
|
|
// ErrTmplUsedAsErr is returned from ErrTmpl.Error() because an error template should never be used as an actual error value
|
|
ErrTmplUsedAsErr = NewErrTmpl("ErrTmplUsedAsErr", "Error template used as error value: %s")
|
|
)
|
|
```
|
|
|
|
```go
|
|
var TraceCallStack bool = true
|
|
```
|
|
TraceCallStack decides if any call stack traces will be gathered when creating
|
|
Errors If your application is doing performance-heavy tasks with lots of Error
|
|
creations, you may consider setting this to false If set to false, all
|
|
CallTraces in Error will be nil
|
|
|
|
#### func Fatal
|
|
|
|
```go
|
|
func Fatal(err error, exitcode int)
|
|
```
|
|
Fatal prints the given err to stderr and exits immediately with the given exit
|
|
code
|
|
|
|
#### func Fatalln
|
|
|
|
```go
|
|
func Fatalln(err error, exitcode int)
|
|
```
|
|
Fatalln prints the given err to stderr followed by a newline and exits
|
|
immediately with the given exit code
|
|
|
|
#### func Print
|
|
|
|
```go
|
|
func Print(err error)
|
|
```
|
|
Print prints the given err to stderr
|
|
|
|
#### func Println
|
|
|
|
```go
|
|
func Println(err error)
|
|
```
|
|
Println prints the given err to stderr followed by a newline
|
|
|
|
#### type CallTrace
|
|
|
|
```go
|
|
type CallTrace struct {
|
|
}
|
|
```
|
|
|
|
CallTrace represents a call stack trace similar to Java's stack trace
|
|
|
|
#### func Trace
|
|
|
|
```go
|
|
func Trace(skip int) *CallTrace
|
|
```
|
|
Trace returns a new CallTrace starting from this call Use skip to skip the first
|
|
entries in the trace
|
|
|
|
#### func (*CallTrace) String
|
|
|
|
```go
|
|
func (ct *CallTrace) String() string
|
|
```
|
|
|
|
#### type ErrTmpl
|
|
|
|
```go
|
|
type ErrTmpl struct {
|
|
}
|
|
```
|
|
|
|
ErrTmpl is an error template to define equalities between different errors
|
|
|
|
#### func NewErrTmpl
|
|
|
|
```go
|
|
func NewErrTmpl(name, format string) *ErrTmpl
|
|
```
|
|
NewErrTmpl returns a new error template with the given format string as a
|
|
predefined error message
|
|
|
|
#### func (*ErrTmpl) Error
|
|
|
|
```go
|
|
func (t *ErrTmpl) Error() string
|
|
```
|
|
Error implementation just for satisfying the error interface Please dont use
|
|
ErrTmpls as actual errors
|
|
|
|
#### func (*ErrTmpl) New
|
|
|
|
```go
|
|
func (t *ErrTmpl) New(args ...interface{}) *Error
|
|
```
|
|
New returns a new Error in which the given values are being formatted into the
|
|
format string of its template
|
|
|
|
#### type Error
|
|
|
|
```go
|
|
type Error struct {
|
|
}
|
|
```
|
|
|
|
Error is a wrapper for error with stack trace
|
|
|
|
#### func New
|
|
|
|
```go
|
|
func New(msg string) *Error
|
|
```
|
|
New returns a new Error with the given message
|
|
|
|
#### func Wrap
|
|
|
|
```go
|
|
func Wrap(msg string, cause error) *Error
|
|
```
|
|
Wrap returns a new Error with the given message which is caused by cause
|
|
|
|
#### func (*Error) Error
|
|
|
|
```go
|
|
func (e *Error) Error() string
|
|
```
|
|
|
|
#### func (*Error) Is
|
|
|
|
```go
|
|
func (e *Error) Is(target error) bool
|
|
```
|
|
Is implements the error equality function used by errors.Is() It returns true if
|
|
the error is the same instance or is created using the same ErrTmpl
|
|
|
|
#### func (*Error) Unwrap
|
|
|
|
```go
|
|
func (e *Error) Unwrap() error
|
|
```
|