README
¶
faults
Wrap errors with stack trace
Usage
Errorf
The most common usage should be faults.Errorf that can be a replacement for fmt.Errorf
err := errors.New("Bad data") // created by a call to an external lib
err = faults.Errorf("Unable to process data: %w", err)
The output of err.Error() will be the same as fmt.Errorf.
Unable to process data: Bad data
To print the stack trace we have to use %+v.
fmt.Printf("%+v\n", err)
Unable to process data: Bad data
/.../app/process.go:28
/.../app/caller.go:1123
Additional calls to faults.Errorf will not change the stack trace.
Wrap
We can also wrap any error with faults.Wrap(err)
err := errors.New("Bad data") // created by a call to an external lib
err = faults.Wrap(err)
If the error is nil or is already wrapped, no action will be taken, otherwise the error will be wrapped with a stack trace info.
This means that we can just use faults.Wrap(err) on any error without thinking if it is already wrapped or not.
New
If we have to create a new error on the fly, we can use faults.New
return faults.New("Bad data")
Don't use
faults.Newwhen declaring a global variable because the stack trace will be relatively to the point of declaration
Catch
utility function to be used in our function calls to trace call values, for example.
func doAnotherStuff(b int) (err error) {
defer Catch(&err, "doAnotherStuff(b=%d)", b)
if b <= 0 {
return ErrInvalidArgument
}
return nil
}
on error this would output
doAnotherStuff(b=-1): invalid argument
/.../app/stuff.go:28
/.../app/caller.go:123
WrapUp
starts the caller stack trace one level up. This allows us to remove the extra stack trace line if we want to use this lib in custom utility code.
eg: write a different Catch() method.
Documentation
¶
Index ¶
- func Catch(errp *error, format string, args ...any)
- func Errorf(format string, args ...any) error
- func Join(errs ...error) error
- func New(text string, args ...any) error
- func SetFormatter(f Formatter)
- func Wrap(err error, args ...any) error
- func WrapMsg(err error, msg string, args ...any) error
- func WrapUp(err error, args ...any) error
- func Wrapf(err error, format string, args ...any) error
- type Formatter
- type LinkedError
- type Message
- type TextFormatter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Catch ¶ added in v1.2.1
Catch allow us to implement a different pattern of error tracing where it is the responsibility of the callee to say that it was called. This allows us to not worry about adding an message on every error return.
func (o *Something) MethodM(a TypeA) (_ Stuff, er error) {
defer faults.Catch(&er, "calling MethodM(a=%v)", a)
x, err := doSomething(a) // will also have a Catch() inside
if err != nil {
return Stuff{}, faults.Wrap(err)
}
s, err := stuff.New(a, x) // will also have a Catch() inside
if err != nil {
return Stuff{}, faults.Wrap(err)
}
return s, nil
}
where the error message would be: "calling MethodM(a=-2): calling doSomething(a=-2): value must > 0"
func Errorf ¶
Errorf creates a new error based on format and wraps it in a stack trace. The format string can include the %w verb.
func New ¶
New creates a new error with a stack trace and additional data. When the error is printed, it will show the message text. If additional flags are set, it will also show the data in the error message and the stack trace.
'+' flag will show the stack trace.
'#' flag will show the data in the error message.
eg: fmt.Printf("%+v", err) // will show the message and stack trace,
fmt.Printf("%#v", err) // will show the message and the data in the error message.
fmt.Printf("%+#v", err) // will show the message, the data in the error message and the stack trace.
NB: The additional data is not used in the error message, but can be retrieved using the Data() method, to be used when logging.
func SetFormatter ¶ added in v1.1.0
func SetFormatter(f Formatter)
func Wrap ¶
Wrap annotates the given error with a stack trace and additional data. If a stack trace already exists, it will not create a new one.
NB: The additional data is not used in the error message, but can be retrieved using the Data() method, to be used when logging.
func WrapMsg ¶ added in v1.8.0
Wrap annotates the given error with a stack trace and additional data. If a stack trace already exists, it will not create a new one.
NB: The additional data is not used in the error message, but can be retrieved using the Data() method, to be used when logging.
Types ¶
type LinkedError ¶ added in v1.5.0
type LinkedError struct {
Err error
Next *LinkedError
}
func (*LinkedError) As ¶ added in v1.5.0
func (e *LinkedError) As(target interface{}) bool
func (*LinkedError) Error ¶ added in v1.5.0
func (e *LinkedError) Error() string
func (*LinkedError) Is ¶ added in v1.5.0
func (e *LinkedError) Is(target error) bool
func (*LinkedError) Unwrap ¶ added in v1.5.0
func (e *LinkedError) Unwrap() error
type TextFormatter ¶ added in v1.1.0
type TextFormatter struct{}
Source Files