README
¶
Errors
Go errors library.
Features
Message
New() creates an error with a message.
Wrap() adds a message to an error.
err := errors.New("error")
err = errors.Wrap(err, "message")
fmt.Println(err) // "message: error"
Stack trace
Errors created by New() and wrapped by Wrap() have a stack trace.
The error verbose message includes the stack trace.
errstack.Frames() returns the stack frames of the error.
frames := errors.StackFrames(err)
It's compatible with Sentry.
Verbose message
The error verbose message shows additional information about the error. Wrapping functions may provide a verbose message (stack, tag, value, etc.)
The Write()/String()/Formatter() functions write/return/format the error verbose message.
The first line is the error's message. The following lines are the verbose message of the error chain.
Example:
test: error
value c = d
tag a = b
temporary = true
ignored
stack
github.com/pierrre/errors/integration_test_test.Test integration_test.go:17
testing.tRunner testing.go:1576
runtime.goexit asm_amd64.s:1598
Extend
Create a custom error type:
- Create a type implementing the
errorinterface - Optionally implement the
Unwrap() errormethod - Optionally implement the
errverbose.Interfaceinterface
See the provided packages as example:
errbase: create a base error (e.g. sentinel error)errmsg: add a message to an errorerrstack: add a stack trace to an errorerrtag: add a tag to an errorerrval: add a value to an errorerrignore: mark an error as ignorederrtmp: mark an error as temporary
Migrate from the std errors package
- Replace the import
errorswithgithub.com/pierrre/errors - Replace
fmt.Errorf("some wessage: %w", err)witherrors.Wrap(err, "some message") - Use
errbase.New()for sentinel error
Documentation
¶
Overview ¶
Package errors provides error management.
By convention, wrapping functions return a nil error if the provided error is nil.
Index ¶
- Variables
- func As(err error, target any) bool
- func Is(err, target error) bool
- func Join(errs ...error) error
- func New(msg string) error
- func Newf(format string, args ...any) error
- func Unwrap(err error) error
- func Wrap(err error, msg string) error
- func Wrapf(err error, format string, args ...any) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = std_errors.ErrUnsupported
ErrUnsupported is an alias for std_errors.ErrUnsupported.
var ReportGlobalInit func(error) = func() func(error) { var f func(error) if testing.Testing() { f = func(err error) { panic(err) } } return f }()
ReportGlobalInit reports a global error initialization. It is discouraged to call New or Newf to create a global (sentinel) error, as it will contain the stack of the (main) goroutine that created it. Instead, call errbase.New or errbase.Newf, and Wrap it before returning it, which will add the stack of the goroutine returning the error.
Example:
var ErrGlobal = errbase.New("global error")
func myFunc() error {
return errors.Wrap(ErrGlobal, "myFunc error")
}
The default values's behavior is to panic during tests, and do nothing during normal execution. It can be disabled by setting it to nil.
The implementation of New and Newf checks if the error is created by a function named "init". It doesn't report errors created by "init()" functions, which are named "init.N" where N is a number.
Functions ¶
func Join ¶ added in v0.3.0
Join calls std_errors.Join and adds a stack.
func New ¶
New returns a new error with a message and a stack.
Warning: don't use this function to create a global (sentinel) error, as it will contain the stack of the (main) goroutine creating it. Use errbase.New instead.
Example ¶
err := New("error")
fmt.Println(err)
Output: error
func Newf ¶
Newf returns a new error with a formatted message and a stack.
It supports the %w verb.
Warning: don't use this function to create a global (sentinel) error, as it will contain the stack of the (main) goroutine creating it. Use errbase.Newf instead.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package errbase provides a simple error type.
|
Package errbase provides a simple error type. |
|
Package errignore provides a way to mark errors as ignored.
|
Package errignore provides a way to mark errors as ignored. |
|
Package erriter provides a way to iterate over errors tree.
|
Package erriter provides a way to iterate over errors tree. |
|
Package errmsg provides a way to add messages to errors.
|
Package errmsg provides a way to add messages to errors. |
|
Package errstack provides utilities to manage error stack traces.
|
Package errstack provides utilities to manage error stack traces. |
|
Package errtag provides a way to add tags to errors.
|
Package errtag provides a way to add tags to errors. |
|
Package errtmp provides a way to mark errors as temporary.
|
Package errtmp provides a way to mark errors as temporary. |
|
Package errval provides a way to add values to errors.
|
Package errval provides a way to add values to errors. |
|
Package errverbose provides utilities to manage error verbose messages.
|
Package errverbose provides utilities to manage error verbose messages. |