README
¶
errors
A package that provides enriched errors. It uses the same conventions and extends the Go standard errors package.
Install
go get -u github.com/aukilabs/go-tooling/pkg/errors
Usage
Create
err := errors.New("error message") // With a message.
err := errors.Newf("error message with format: %v", 42) // With a formatted message.
Enrich With A Custom Type
err := errors.New("handling http request failed").WithType("httpError")
Enrich With Tags
err := errors.New("handing http request failed").
WithTag("method", "GET").
WithTag("path", "/cookies").
WithTag("code", 401)
Wrap Another Error
err := errors.New("handling http request failed").Wrap(fmt.Errorf("a fake simple http error"))
Compose Multiple Enrichments
err := errors.New("handing http request failed").
WithType("httpError").
WithTag("method", "GET").
WithTag("path", "/cookies").
WithTag("code", 401).
Wrap(fmt.Errorf("a fake simple http error"))
Get Error Type
var err error
t := errors.Type(err)
Get Error Tag
var err error
foo := errors.Tag(err, "foo")
Documentation
¶
Index ¶
- Variables
- func As(err error, target any) bool
- func Is(err, target error) bool
- func IsType(err error, v string) bool
- func Message(err error) string
- func SetIndentEncoder()
- func SetInlineEncoder()
- func Tag(err error, k string) string
- func Type(err error) string
- func Unwrap(err error) error
- type Error
- type MultiUnwrappableError
- type UnwrappableError
Constants ¶
This section is empty.
Variables ¶
var ( // The function used to encode errors and their tags. Encoder func(any) ([]byte, error) )
Functions ¶
func As ¶
As finds the first error in err's chain that matches target, and if one is found, 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 Is ¶
Is reports whether any error in err's 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 == fs.ErrExist }
then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library. An Is method should only shallowly compare err and the target and not call Unwrap on either.
func IsType ¶
IsType reports whether any error in err's chain matches the given type.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches the given type if the error has a method Type() string such that Type() returns a string equal to the given type.
func SetIndentEncoder ¶
func SetIndentEncoder()
SetIndentEncoder is a helper function that set the error encoder to a function that uses json.MarshalIndent.
func SetInlineEncoder ¶
func SetInlineEncoder()
SetInlineEncoder is a helper function that set the error encoder to json.Marshal.
func Tag ¶
Tag returns the first tag value in err's chain that matches the given key.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error has a tag when it has a method Tag(string) string such that Tag(k) returns a non-empty string value.
Types ¶
type Error ¶
type Error interface {
error
// Returns the file line where the error was created.
Line() string
// Returns the error message.
Message() string
// Sets the given type to the error.
WithType(v string) Error
// Returns the type of the error.
Type() string
// Sets the tag key with the given value. The value is converted to a
// string.
WithTag(k string, v any) Error
// Return the tag value associated with the given key.
Tag(k string) string
// Returns the tags as a list of key-value pairs.
Tags() map[string]string
// Wraps the given error.
Wrap(err error) Error
// Returns the wrapped error. Returns nil when there is no wrapped error.
Unwrap() error
}
Error is the interface that describes an enriched error.
func Newf ¶
Newf returns an error with the given formatted message that can be enriched with a type and tags.
func ToRichError ¶ added in v0.14.7
ToRichError returns an enriched error created from a passed-in error. If the passed-in error is already enriched, it is returned as is.
type MultiUnwrappableError ¶ added in v0.14.7
type MultiUnwrappableError interface {
// Returns the wrapped errors. Returns nil when there is no wrapped error.
Unwrap() []error
}
MultiUnwrappableError is an interface describing error types that can be wrapping multiple errors.
type UnwrappableError ¶ added in v0.14.7
type UnwrappableError interface {
// Returns the wrapped error. Returns nil when there is no wrapped error.
Unwrap() error
}
UnwrappableError is an interface describing error types that can be unwrapped.
Source Files