faults

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.New when 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 ...interface{})
• func Errorf(format string, args ...interface{}) error
• func Join(errs ...error) error
• func New(text string) error
• func SetFormatter(f Formatter)
• func ToString(err error) string
• func Wrap(err error) error
• func WrapUp(err error) error
• func Wrapf(err error, format string, args ...interface{}) error
• type Formatter
• type LinkedError
  • func (e *LinkedError) As(target interface{}) bool
  • func (e *LinkedError) Error() string
  • func (e *LinkedError) Is(target error) bool
  • func (e *LinkedError) Unwrap() error
• type Message
  • func (m Message) Frames() []runtime.Frame
• type TextFormatter
  • func (TextFormatter) Format(m Message) string

Functions

func Catch

func Catch(errp *error, format string, args ...interface{})

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

func Errorf(format string, args ...interface{}) error

Errorf creates a new error based on format and wraps it in a stack trace. The format string can include the %w verb.

func Join

func Join(errs ...error) error

func New

func New(text string) error

New returns a new error creates a new

func SetFormatter

func SetFormatter(f Formatter)

func ToString

func ToString(err error) string

func Wrap

func Wrap(err error) error

Wrap annotates the given error with a stack trace

func WrapUp

func WrapUp(err error) error

WrapUp to be used by custom utility functions

func Wrapf

func Wrapf(err error, format string, args ...interface{}) error

Wrapf creates a new error based on format and wraps it in a stack trace, only if error is not nil The format string cannot include the %w verb. error will concatenated to format like: format + ": %w"

Types

type Formatter

type Formatter interface {
	Format(m Message) string
}

type LinkedError

type LinkedError struct {
	Err  error
	Next *LinkedError
}

func (*LinkedError) As

func (e *LinkedError) As(target interface{}) bool

func (*LinkedError) Error

func (e *LinkedError) Error() string

func (*LinkedError) Is

func (e *LinkedError) Is(target error) bool

func (*LinkedError) Unwrap

func (e *LinkedError) Unwrap() error

type Message

type Message struct {
	Err    error
	Expand bool
	// contains filtered or unexported fields
}

func (Message) Frames

func (m Message) Frames() []runtime.Frame

type TextFormatter

type TextFormatter struct{}

func (TextFormatter) Format

func (TextFormatter) Format(m Message) string