README
¶
Package errors
Package errors is an errors wrapping package to help propagate and chain errors as well as attach stack traces, tags(additional information) and even a Type classification system to categorize errors into types eg. Permanent vs Transient.
It is a drop in replacement for the std Go errors package. It is also 100% compatible with the Is, As and Unwrap interfaces used within the std library and can be mixed with the built-in error wrapping.
Common Questions
Why another package? There are two main reasons.
-
I think that the programs generating the original error(s) should be responsible for adding internal metadata and details to them. Ultimately developers are concerned with:
- If the error is Transient or Permanent for retries.
- Additional details for logging.
-
IMO most of the existing packages either don't take the error handling far enough, too far or down right unfriendly to use/consume.
Features
- works with go-playground/log, the Tags will be added as Field Key Values and Types will be concatenated as well when using
WithError - helpers to extract and classify error types using
RegisterHelper(...), many already existing such as ioerrors, neterrors, awserrors... - built in helpers only need to be imported, eg.
_ github.com/go-playground/errors/v5/helpers/neterrorsallowing libraries to register their own helpers not needing the caller to do or guess what needs to be imported.
Installation
Use go get.
go get -u github.com/go-playground/errors/v5
Usage
package main
import (
"fmt"
"io"
"github.com/go-playground/errors/v5"
)
func main() {
err := level1("testing error")
fmt.Println(err)
if errors.HasType(err, "Permanent") {
// os.Exit(1)
fmt.Println("it is a permanent error")
}
// root error
cause := errors.Cause(err)
fmt.Println("CAUSE:", cause)
// can even still inspect the internal error
fmt.Println(errors.Cause(err) == io.EOF) // will extract the cause for you
fmt.Println(errors.Cause(cause) == io.EOF)
// and still in a switch
switch errors.Cause(err) {
case io.EOF:
fmt.Println("EOF error")
default:
fmt.Println("unknown error")
}
}
func level1(value string) error {
if err := level2(value); err != nil {
return errors.Wrap(err, "level2 call failed")
}
return nil
}
func level2(value string) error {
err := io.EOF
return errors.Wrap(err, "failed to do something").AddTypes("Permanent").AddTags(errors.T("value", value))
}
Package Versioning
Using Go modules and proper semantic version releases (as always).
License
Distributed under MIT License, please see license file in code for more details.
Documentation
¶
Index ¶
- func As(err error, target any) bool
- func Cause(err error) error
- func HasType(err error, typ string) bool
- func Is(err, target error) bool
- func Join(errs ...error) error
- func LookupTag(err error, key string) any
- func RegisterErrorFormatFn(fn ErrorFormatFn)
- func RegisterHelper(helper Helper)
- type Chain
- func (c Chain) AddTag(key string, value any) Chain
- func (c Chain) AddTags(tags ...Tag) Chain
- func (c Chain) AddTypes(typ ...string) Chain
- func (c Chain) As(target any) bool
- func (c Chain) Error() string
- func (c Chain) Is(target error) bool
- func (c Chain) Unwrap() error
- func (c Chain) Wrap(prefix string) Chain
- type ErrorFormatFn
- type Helper
- type Link
- type Tag
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶ added in v5.1.0
As is to allow this library to be a drop-in replacement to the std library.
As finds the first error in the error chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(any) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
An error type might provide an As method, so it can be treated as if it were a different error type.
As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.
func Cause ¶
Cause extracts and returns the root wrapped error (the naked error with no additional information)
func HasType ¶
HasType is a helper function that will recurse up from the root error and check that the provided type is present using an equality check
func Is ¶ added in v5.1.0
Is allows this library to be a drop-in replacement to the std library.
Is reports whether any error in the error chain matches target.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
An error type might provide an Is method, so it can be treated as equivalent to an existing error. For example, if MyError defines
func (m MyError) Is(target error) bool { return target == os.ErrExist }
then Is(MyError{}, os.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library.
func Join ¶ added in v5.4.0
Join allows this library to be a drop-in replacement to the std library.
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.
A non-nil error returned by Join implements the Unwrap() []error method.
It is the responsibility of the caller to then check for nil and wrap this error if desired.
func RegisterErrorFormatFn ¶ added in v5.1.0
func RegisterErrorFormatFn(fn ErrorFormatFn)
RegisterErrorFormatFn sets a custom error formatting function in order for the error output to be customizable.
func RegisterHelper ¶
func RegisterHelper(helper Helper)
RegisterHelper adds a new helper function to extract Type and Tag information. errors will run all registered helpers until a match is found. NOTE helpers are run in the order they are added.
Types ¶
type Chain ¶
type Chain []*Link
Chain contains the chained errors, the links, of the chains if you will
func New ¶
New creates an error with the provided text and automatically wraps it with line information.
func Newf ¶
Newf creates an error with the provided text and automatically wraps it with line information. it also accepts a variadic for optional message formatting.
func Wrap ¶
Wrap encapsulates the error, stores a contextual prefix and automatically obtains a stack trace.
func WrapSkipFrames ¶
WrapSkipFrames is a special version of Wrap that skips extra n frames when determining error location. Normally only used when wrapping the library
func Wrapf ¶
Wrapf encapsulates the error, stores a contextual prefix and automatically obtains a stack trace. it also accepts a variadic for prefix formatting.
func (Chain) As ¶ added in v5.1.0
As finds the first error in the error chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(any) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
An error type might provide an As method, so it can be treated as if it were a different error type.
As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.
type ErrorFormatFn ¶ added in v5.1.0
ErrorFormatFn represents the error formatting function for a Chain of errors.
type Helper ¶
Helper is a function which will automatically extract Type and Tag information based on the supplied err and add it to the supplied *Link error; this can be used independently or by registering using errors.RegisterHelper(...), which will run the registered helper every time errors.Wrap(...) is called.
type Link ¶
type Link struct {
// Err is the wrapped error, either the original or already wrapped
Err error
// Prefix contains the error prefix text
Prefix string
// Type stores one or more categorized types of error set by the caller using AddTypes and is optional
Types []string
// Tags contains an array of tags associated with this error, if any
Tags []Tag
// Source contains the name, file and lines obtained from the stack trace
Source runtimeext.Frame
}
Link contains a single error entry contained in an error Chain.
Source Files
Directories