errors

Documentation

Index

• Variables
• func As(err error, target interface{}) bool
• func Close(into *error, x io.Closer, msg string, args ...any)
• func EnsureStack(err error) error
• func ForEachStackFrame(err error, f func(Frame))
• func Invoke(into *error, f func() error, msg string, args ...any)
• func Invoke1[T any](into *error, f func(T) error, x T, msg string, args ...any)
• func Join(errs ...error) error
• func JoinInto(into *error, err error)
• type Frame
• type StackTracer

Variables

var (
	// Cause wraps errors.Cause
	Cause = errors.Cause
	// New returns an error with the supplied message.
	// New also records the stack trace at the point it was called.
	New = errors.New
	// Errorf formats according to a format specifier and returns the string
	// as a value that satisfies error.
	// Errorf also records the stack trace at the point it was called.
	Errorf = errors.Errorf
	// Unwrap returns the underlying wrapped error if it exists, or nil otherwise.
	Unwrap = errors.Unwrap
	// Is reports whether any error in err's chain matches target. 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.
	Is = errors.Is
	// Wrap returns an error annotating err with a stack trace
	// at the point Wrap is called, and the supplied message.
	// If err is nil, Wrap returns nil.
	Wrap = errors.Wrap
	// Wrapf returns an error annotating err with a stack trace
	// at the point Wrapf is called, and the format specifier.
	// If err is nil, Wrapf returns nil.
	Wrapf = errors.Wrapf
	// WithStack annotates err with a stack trace at the point WithStack was called.
	// If err is nil, WithStack returns nil.
	WithStack = errors.WithStack
)

Functions

func As

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches the target's type, and if so, sets target to that error value and returns true. As is a wrapper for the underlying errors.As function, which may panic or return unexpected results based on how err was constructed (with or without a pointer). This works by inspecting the type of target and attempting multiple errors.As calls if necessary.

func Close

func Close(into *error, x io.Closer, msg string, args ...any)

Close enhances a very common pattern with multierrors; adding the error from Close() to the return value of the current function:

 func f(what string) (retErr error) {
     x := thing.Open(what)
     defer errors.Close(&retErr, x, "close thing %v", what)
     return x.Do()
}

A non-wrapping version is not available because an error without context is maddening.

func EnsureStack

func EnsureStack(err error) error

EnsureStack will add a stack onto the given error only if it does not already have a stack. If err is nil, EnsureStack returns nil.

func ForEachStackFrame

func ForEachStackFrame(err error, f func(Frame))

ForEachStackFrame calls f on each Frame in the StackTrace contained in err. If is a wrapper around another error it is repeatedly unwrapped and f is called with frames from the stack of the innermost error.

func Invoke

func Invoke(into *error, f func() error, msg string, args ...any)

Invoke is like Close, but for any function that returns an error.

func Invoke1

func Invoke1[T any](into *error, f func(T) error, x T, msg string, args ...any)

Invoke1 is like Invoke, but the f can take an argument.

func Join

func Join(errs ...error) error

Join joins the provided errors into a single multierror. Any nil errors are skipped, and if all errors are nil, the return value is nil.

See `go doc errors.Join` for details.

func JoinInto

func JoinInto(into *error, err error)

JoinInto appends err into *into. into can point to a nil error, and err can also be nil.

Types

type Frame

type Frame struct{ errors.Frame }

Frame is the type of a StackFrame, it is an alias for errors.Frame.

type StackTracer

type StackTracer interface {
	StackTrace() errors.StackTrace
}

StackTracer is an interface for errors that can return stack traces. Unfortuantely github.com/pkg/errors makes us define this ourselves rather than defining it for us.