README
¶
go-errs
Errs is a Go package designed to make working with (custom) errors an easy task. It supports adding stacktrace frames so tracing the cause of an error is a breeze.
go get github.com/roeldev/go-errs
import "github.com/roeldev/go-errs"
Creating an error
Wrapping existing errors
Error that is created with errs.New() and has an additional stack frame captured errs.Trace():
some error: something happened:
main.doSomething
.../go-errs/examples/2_trace/main.go:17
main.someAction
.../go-errs/examples/2_trace/main.go:12
A json unmarshalling error that's traced with errs.Trace():
some error: something bad happened while performing someAction:
main.someAction
.../go-errs/examples/3_trace_existing/main.go:22
- invalid character 'i' looking for beginning of value:
main.unmarshal
.../go-errs/examples/3_trace_existing/main.go:16
Documentation
Additional detailed documentation is available at go.dev
Created with
License
GPL-3.0+ © 2019-2020 Roel Schut
Documentation
¶
Index ¶
- Constants
- Variables
- func Append(dest *error, err error) error
- func Combine(errors ...error) error
- func Filter(errors []error) []error
- func FormatError(err error, s fmt.State, v rune)
- func Must(args ...interface{})
- func New(kind Kind, msg string) error
- func Newf(kind Kind, format string, a ...interface{}) error
- func Trace(err error) error
- func TraceSkip(err error, skip uint) error
- func UnwrapAll(err error) []error
- func UnwrapCause(err error) error
- func Wrap(cause error, kind Kind, msg string) error
- func WrapPanic(prefix string)
- func Wrapf(cause error, kind Kind, format string, a ...interface{}) error
- type ErrLister
- type ErrorWithFrames
- type ErrorWithKind
- type ErrorWithUnwrap
- type Frames
- type Inner
- type Kind
- type List
- type MultiError
- type WaitGroup
Constants ¶
const UnknownError string = "unknown error"
UnknownError is an error message that is returned when an error has no message and is of `UnknownKind`
Variables ¶
var DefaultFramesCapacity uint = 5
var DefaultListCapacity uint = 8
var MustPanicFormat = "errs.Must: %+v"
MustPanicFormat is the template string used by the `Must()` function to format its panic message.
Functions ¶
func Append ¶ added in v0.3.0
Append appends multiple non-nil errors to a single multi error `dest`.
Important: when using Append with defer, the pointer to the `dest` error must be a named return variable. For addition details see https://golang.org/ref/spec#Defer_statements.
func Combine ¶ added in v0.3.0
Combine returns a multi error when there are more than one non-nil errors provided. If only one non-nil error is provided, it will act as if `TraceSkip` is called. It returns nil when all provided errors are nil.
func Filter ¶ added in v0.3.0
Filter returns a slice of errors without nil values in between them. It returns the slice with the length of the amount of non-nil errors but keeps its original capacity.
func FormatError ¶ added in v0.2.0
FormatError prints the error using `xerrors.FormatError()` and a formatter that implements the `xerrors.Formatter` interface. See the `golang.org/x/xerrors` package for additional information.
func Must ¶ added in v0.3.0
func Must(args ...interface{})
Must panics when any of the given args is a non-nil error. Its message is the error message of the first encountered error.
func Newf ¶ added in v0.2.0
Newf formats an error message according to a format specifier and provided arguments and creates a new error the same way `New()` does.
func Trace ¶ added in v0.2.0
Trace wraps an existing error with information about the stack frame its called from. Errors that implement the `ErrorWithStackTrace` interface add the frame to the existing stack trace. Other "simple" errors are wrapped in a `traceErr` type.
func TraceSkip ¶ added in v0.3.0
TraceSkip, just like Trace(), wraps an existing error with information about the stack frame its called from. The stack frame is selected based on the skip argument.
func UnwrapAll ¶
UnwrapAll returns the complete chain of errors, starting with the supplied error and ending with the error that started the chain.
func UnwrapCause ¶
UnwrapCause walks through all wrapped errors and returns the last error in the chain which is the "cause" error.
func Wrap ¶
Wrap creates a new error that wraps around the causing error, thus extending the error chain. In contrast to `New()`, it will only create a new error when the cause error is not `nil`.
Types ¶
type ErrLister ¶ added in v0.4.0
type ErrLister interface {
// ErrList returns a List of collected non-nil errors that were encountered.
ErrList() *List
}
type ErrorWithFrames ¶ added in v0.2.0
ErrorWithFrames interfaces provide access to a stack of frames.
type ErrorWithKind ¶
ErrorWithKind interfaces provide access to a `Kind`.
type ErrorWithUnwrap ¶
ErrorWithUnwrap interfaces provide access to an underlying error further down the error chain, if any.
type Frames ¶ added in v0.2.0
func CaptureFrames ¶ added in v0.2.0
CaptureFrames captures `n` frames starting from `skip`.
func (*Frames) Capture ¶ added in v0.2.0
Capture captures a `xerrors.Frame` that describes a frame on the caller's stack. The argument skip is the number of frames to skip over. Capture(0) returns the frame for the caller of Capture. It returns a bool false when the captured frame contains a nil pointer.
func (Frames) Format ¶ added in v0.2.0
Format formats the captured frames using xerror's format functionality.
type Inner ¶ added in v0.2.0
type Inner struct {
// contains filtered or unexported fields
}
Inner is by itself not an error and is designed to be embedded in (custom) errors.
func (*Inner) Frames ¶ added in v0.2.0
Frames returns a slice of captured `xerrors.Frame` types linked to this error.
type Kind ¶
type Kind string
Kind describes the kind/type of error that has occurred. For example "auth error", "unmarshal error", etc. This way errors can be of the same `Kind` but still contain different error messages or additional fields. It is recommended to define each `Kind` as a constant.
const UnknownKind Kind = ""
UnknownKind is used for errors that are created without a distinct `Kind`.
type List ¶ added in v0.4.0
func (*List) Append ¶ added in v0.4.0
Append an error to the list. It guarantees only non-nil errors are added. It returns `false` when a nil error is encountered. And `true` when the error is appended to the list.
func (*List) Combine ¶ added in v0.4.0
Combine the collected errors. It uses the same rules and logic as the `Combine` function.
type MultiError ¶ added in v0.4.0
type WaitGroup ¶ added in v0.4.0
type WaitGroup struct {
// contains filtered or unexported fields
}
A WaitGroup is a collection of goroutines working on subtasks that are part of the same overall task. Unlike `errgroup.Group`, it collects possible errors returned from the subtasks and does not cancel the group when an error is encountered.
func (*WaitGroup) ErrList ¶ added in v0.4.0
ErrList returns a List of collected errors from the called goroutines.
Source Files
Directories