errors

README

errors

A simple error management library for go.

It implements the same basic interface as the standard "errors" library for interop, and more useful and composable features.

Also adds a simple AddStack function for easier debugging.

This library was made with performance in mind, and even traditionally expensive functions are fast and lazy, so if you don't print the error it is even faster.

Documentation

Overview

Package errors implements functions for handling errors It implements the same functions as the standard "errors" package, with a few added ones for ease of use

Except where noted, functions that take a nil as their error will retrun nil, and do so very cheaply, so that you can use potentially expensive calls in main path.

See godoc.org/errors for in-depth details about Is, As, Unwrap and New

Index

• func AddStack(err error) error
• func Append(err error, others ...error) error
• func AppendInto(err *error, errs ...error)
• func As(err error, target interface{}) bool
• func AutoWrap(err error) error
• func CallInto(err *error, fn func() error)
• func Is(err, target error) bool
• func New(text string) error
• func RecoverInto(err *error)
• func Unwrap(err error) error
• func Wrap(err error, msg string) error
• func Wrapf(err error, msg string, a ...interface{}) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Is(err error) bool
  • func (e *Error) MarshalJSON() ([]byte, error)
  • func (e *Error) Unwrap() error
• type Multi
  • func (m *Multi) As(target interface{}) bool
  • func (m *Multi) Error() string
  • func (m *Multi) Is(target error) bool

Functions

func AddStack

func AddStack(err error) error

AddStack wraps err to add a stack trace

Quite a bit more expensive call compared to Wrap, but extremely useful, and run time should still be around the microsecond (few nanoseconds for Wrap)

If err is nil, returns nil

If call stack is extremely deep (10k+), has very poor performance (but you shouldn't record call stack in recursive functions anyway).

func Append

func Append(err error, others ...error) error

Append returns a *Multi (or nil) containing all errors

Use like you would append: err = Append(err, myerror)

if err is already a *Multi, appends to it otherwise, create a *Multi with err as first error.

func AppendInto

func AppendInto(err *error, errs ...error)

AppendInto appends errs into err, useful for repetitive appends.

func As

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

As is a proxy to std errors.As, provided for ease of transition.

func AutoWrap

func AutoWrap(err error) error

AutoWrap returns an error that wraps err

Additionally, it adds the name of the caller function (and package) to the message

Quite slower than manual Wrap("package.Func", err).

func CallInto

func CallInto(err *error, fn func() error)

CallInto appends fn() into err

Useful for defer : defer errors.CallInto(&err, file.Close).

func Is

func Is(err, target error) bool

Is is a proxy to std errors.Is, provided for ease of transition.

func New

func New(text string) error

New returns an error that formats as the given text Each call to New returns a distinct error value even if the text is identical.

func RecoverInto

func RecoverInto(err *error)

RecoverInto tries to recover, and appends a representation of the error to err. If the recovered value is not an error, will create a new error based on fmt.Sprint(value)

Use like: defer RecoverInto(&err).

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error.

Otherwise, Unwrap returns nil.

func Wrap

func Wrap(err error, msg string) error

Wrap returns an error that wraps err

Additionally, it adds msg to the Error() message.

If err is nil, returns nil.

func Wrapf

func Wrapf(err error, msg string, a ...interface{}) error

Wrapf returns an error that wraps err

Additionally, it adds fmt.Sprintf(msg, a...) To the Error() message.

If err is nil, returns nil.

Types

type Error

type Error struct {
	Message string
	Err     error
	Stack   []uintptr
}

Error represents a simple error and its message.

It may also optionally hold a wrapped error, and/or a stack trace.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(err error) bool

func (*Error) MarshalJSON

func (e *Error) MarshalJSON() ([]byte, error)

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Multi

type Multi struct {
	Errors []error `json:"errors"`
}

Multi is an error that is actually composed of multiple errors An empty *Multi makes no sense, and should be nil instead.

func (*Multi) As

func (m *Multi) As(target interface{}) bool

As implements errors.As by attempting to map to the first error.

func (*Multi) Error

func (m *Multi) Error() string

func (*Multi) Is

func (m *Multi) Is(target error) bool

Is implements errors.Is by comparing the first error directly.