errors

func Append ¶

func Append(left, right error) error

Append creates a multi error from two non-nil errors. If left is already a multi error, the other error is appended to it. If either of the errors is nil, the other error is returned.

type Result struct{}

unmarshal := func() (*Result, error) {
	dest := new(Result)
	err := json.Unmarshal([]byte("invalid"), &dest) // this wil result in an error
	return dest, WithStack(err)
}

closeSomething := func() error {
	return errors.New("some error occurred while closing something")
}

doSomething := func() (err error) {
	defer AppendFunc(&err, closeSomething)

	_, err = unmarshal()
	if err != nil {
		return err
	}
	return nil
}

err := doSomething()
fmt.Println(err)

Output:

multiple errors occurred:
[1/2] invalid character 'i' looking for beginning of value;
[2/2] some error occurred while closing something

func AppendFunc ¶ added in v0.7.2

func AppendFunc(dest *error, fn func() error)

AppendFunc appends the non-nil error result of fn to dest using AppendInto.

func AppendInto ¶ added in v0.9.0

func AppendInto(dest *error, errs ...error) (errored bool)

AppendInto appends multiple non-nil errors to a single multi error dest. When the value of dest is nil and errs only contains a single error, its value is set to the value of dest.

Important: when using AppendInto with defer, the pointer to the dest error must be a named return variable. For additional details see https://golang.org/ref/spec#Defer_statements.

func As ¶

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

As is an alias of errors.As. It finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

func CatchPanic ¶ added in v0.6.0

func CatchPanic(dest *error)

CatchPanic recovers from a panic and wraps it in an error. It then calls AppendInto with the provided dest *error and wrapped panic. Use CatchPanic directly with defer. It is not possible to use CatchPanic inside a deferred function, like:

defer func(){ CatchPanic(&err }()

var err error

done := make(chan struct{})
go func() {
	defer close(done)
	defer CatchPanic(&err)

	err = New("first error")
	panic("something bad happened")
}()

<-done
fmt.Println(err)

Output:

multiple errors occurred:
[1/2] first error;
[2/2] panic: something bad happened

func Cause ¶ added in v0.7.0

func Cause(err error) error

Cause walks through all wrapped errors and returns the last error in the chain.

func Errorf ¶ added in v0.8.0

func Errorf(format string, args ...interface{}) error

Errorf formats an error message according to a format specifier and provided arguments with fmt.Errorf, and creates a new error similar to New.

err := errors.Errorf("my error %s", "message")
err := errors.Errorf("my error: %w", cause)

func FatalOnErr ¶ added in v0.7.2

func FatalOnErr(err error)

FatalOnErr prints the error to stderr and exits the program with an exit code that is not 0. When err is an ExitCoder its exit code is used.

func Filter ¶

func Filter(errors []error) []error

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 ¶

func FormatError(err error, state fmt.State, verb rune)

FormatError calls the FormatError method of err with a Printer configured according to state and verb, and writes the result to state. It will wrap err If err is not a Formatter it will wrap err, so it is capable of basic error formatting using WithFormatter.

doSomething := func() error {
	return New("something happened")
}

err := doSomething()
var fmt = new(ignoreThisLineUseFmtPackageInActualCode)
fmt.Printf("%+v\n", err)

Output:

something happened:
    github.com/go-pogo/errors.ExampleFormatError
        /path/to/errors/examples_trace_test.go:23
    github.com/go-pogo/errors.ExampleFormatError.func1
        /path/to/errors/examples_trace_test.go:20

func GetExitCode ¶

func GetExitCode(err error) int

GetExitCode returns an exit status code if the error implements the ExitCoder interface. If not, it returns 0.

func GetExitCodeOr ¶ added in v0.6.1

func GetExitCodeOr(err error, or int) int

GetExitCodeOr returns the exit status code from the first found ExitCoder in err's error chain. If none is found, it returns the provided value or.

func GetStatusCode ¶ added in v0.7.6

func GetStatusCode(err error) int

GetStatusCode returns the status code if the error implements the StatusCoder interface. If not, it returns 0.

func GetStatusCodeOr ¶ added in v0.7.6

func GetStatusCodeOr(err error, or int) int

GetStatusCodeOr returns the status code from the first found StatusCoder in err's error chain. If none is found, it returns the provided value or.

func GetTime ¶ added in v0.7.0

func GetTime(err error) (time.Time, bool)

GetTime returns the time.Time of the last found Timer in err's error chain. If none is found, it returns the provided value or.

func Is ¶

func Is(err, target error) bool

Is reports whether any error in err's chain matches target. It is fully compatible with both errors.Is and xerrors.Is.

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.

func Join ¶ added in v0.7.5

func Join(errs ...error) error

Join returns a MultiError when more than one non-nil errors are provided. It returns a single error when only one error is passed, and nil if no non-nil errors are provided.

func Must ¶

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 New ¶

func New(msg interface{}) error

New creates a new error which implements the StackTracer, Wrapper and Formatter interfaces. Argument msg can be either a string or Msg.

err := errors.New("my error message")
err := errors.New(errors.Msg("my error message"))

New records a stack trace at the point it was called. Each call returns a distinct error value even if msg is identical. It will return nil if msg is nil. Use WithStack to wrap an existing error with a StackTracer and Formatter.

doSomething := func() error {
	return New("something happened")
}

err := doSomething()
fmt.Println(err)

Output:

something happened

func Opaque ¶

func Opaque(err error) error

Opaque is an alias of xerrors.Opaque. It returns an error with the same error formatting as err but that does not match err and cannot be unwrapped.

func PanicOnErr ¶ added in v0.9.0

func PanicOnErr(err error)

PanicOnErr panics when err is not nil.

func PrintError ¶

func PrintError(p Printer, err error)

PrintError prints the error err with the provided Printer and formats and prints the error's stack frames.

func PrintFrames ¶ added in v0.8.0

func PrintFrames(p Printer, cf *runtime.Frames)

PrintFrames prints a complete stack of *runtime.Frames using Printer p.

func Unembed ¶ added in v0.7.0

func Unembed(err error) error

Unembed recursively unwraps all Embedder errors and returns the (original) error that was wrapped with extra context. If err is not an Embedder, Unembed returns err as provided.

func Unwrap ¶

func Unwrap(err error) error

Unwrap is an alias of errors.Unwrap. It 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 UnwrapAll ¶

func UnwrapAll(err error) []error

UnwrapAll returns the complete chain of errors, starting with the supplied error and ending with the root cause error.

func WithKind ¶

func WithKind(err error, kind Kind) error

WithKind wraps an error with Kind, therefore extending the error chain.

const (
	ErrSomethingWentWrong Msg  = "something went wrong"
	SomeKindOfError       Kind = "some kind of error"
)

doSomethingElse := func() error {
	return New(ErrSomethingWentWrong)
}
doSomething := func() error {
	err := doSomethingElse()
	return WithKind(err, SomeKindOfError)
}

err := doSomething()
fmt.Println(err)

Output:

some kind of error: something went wrong

func Wrap ¶

func Wrap(cause error, msg interface{}) error

Wrap creates a new error, which implements the StackTracer, Wrapper and Formatter interfaces, that wraps around the causing error. Argument msg can be either a string or Msg.

err = errors.Wrap(err, "my error message")
err = errors.Wrap(err, errors.Msg("my error message"))

Wrap records a stack trace at the point it was called. Each call returns a distinct error value even if cause and msg are identical. Wrap will return nil when cause is nil, and it will return the provided cause when msg is nil.

func WrapPanic ¶

func WrapPanic(prefix string)

WrapPanic wraps a panicking sequence with the given prefix. It then panics again.

func Wrapf ¶

func Wrapf(cause error, format string, args ...interface{}) error

Wrapf formats an error message according to a format specifier and provided arguments with fmt.Errorf, and creates a new error similar to Wrap.

err = errors.Wrapf(err, "my error %s", "message")