errors

README

Errors

Go errors library.

Features

• Stack trace
• Message
• Verbose message
• Drop-in replacement of the std errors package
• Easy to extend

Message

New and Newf functions create an error with a message and a stack.

err := errors.New("error")

err := errors.Newf("error %s", "foo")

Wrap and Wrapf functions add a message to an error, and optionally add a stack if the error doesn't have one.

err = errors.Wrap(err, "message")

err = errors.Wrapf(err, "message %d", 1)

Message and Messagef functions add a message to an error. Most applications should use Wrap and Wrapf instead, because they automatically add a stack.

err = errors.WithMessage(err, "message")

err = errors.WithMessagef(err, "message %d", 1)

Stack trace

Stack function adds a stack to an error. This is only useful if the wrapped error has a stack from a different goroutine. Most applications should use Wrap and Wrapf instead.

err = errors.Stack(err)

StackFrames function returns the stack frames of the error.

frames := errors.StackFrames(err)

Verbose message

The error verbose message shows additional information about the error. Wrapping functions may provide a verbose message (stack, tag, value, etc.)

The Verbose/VerboseString/VerboseFormatter functions write/return/format the error verbose message.

The first line is the error's message. The following lines are the verbose message of the error chain.

Example:

test: error
value c = d
tag a = b
temporary = true
ignored
stack
    github.com/pierrre/errors_test.TestIntegration integration_test.go:15
    testing.tRunner testing.go:1446
    runtime.goexit asm_amd64.s:1594

Extend

Create a custom error type:

• Create a type implementing the error interface
• Optionally implement the Unwrap() error method
• Optionally implement the Verboser interface

See the provided packages as example:

• errtag: add a tag to an error
• errval: add a value to an error
• errignore: mark an error as ignored
• errtmp: mark an error as temporary

Migrate from the std errors package

• Replace the import errors with github.com/pierrre/errors
• Replace fmt.Errorf("some wessage: %w", err) with errors.Wrap(err, "some message")

Documentation

Overview

Package errors provides error management.

By convention, wrapping functions return a nil error if the given error is nil.

Index

• func As(err error, target any) bool
• func Is(err, target error) bool
• func Message(err error, msg string) error
• func Messagef(err error, format string, args ...any) error
• func New(msg string) error
• func Newf(format string, args ...any) error
• func Stack(err error) error
• func StackFrames(err error) []*runtime.Frames
• func Unwrap(err error) error
• func Verbose(w io.Writer, err error)
• func VerboseFormatter(err error) fmt.Formatter
• func VerboseString(err error) string
• func Wrap(err error, msg string) error
• func Wrapf(err error, format string, args ...any) error
• type Verboser

Functions

func As

func As(err error, target any) bool

As calls std_errors.As.

func Is

func Is(err, target error) bool

Is calls std_errors.Is.

func Message

func Message(err error, msg string) error

Message adds a message to an error.

The error message is "<msg>: <err>".

If the given message is empty, the returned error is the given error.

func Messagef

func Messagef(err error, format string, args ...any) error

Messagef adds a formatted message to an error.

func New

func New(msg string) error

New returns a new error with a message and a stack.

func Newf

func Newf(format string, args ...any) error

Newf returns a new error with a formatted message and a stack.

func Stack

func Stack(err error) error

Stack adds a stack to an error.

The verbose message contains the stack.

func StackFrames

func StackFrames(err error) []*runtime.Frames

StackFrames returns the list of runtime.Frames associated to an error.

func Unwrap

func Unwrap(err error) error

Unwrap calls std_errors.Unwrap.

func Verbose

func Verbose(w io.Writer, err error)

Verbose writes the error's verbose message to the writer.

The first line is the error's message. The following lines are the verbose message of the error chain.

func VerboseFormatter

func VerboseFormatter(err error) fmt.Formatter

VerboseFormatter returns a fmt.Formatter that writes the error's verbose message.

func VerboseString

func VerboseString(err error) string

VerboseString returns the error's verbose message as a string.

func Wrap

func Wrap(err error, msg string) error

Wrap adds a message to an error, and optionnally add a stack if it doesn't have one.

See Message() and Stack() for more information.

func Wrapf

func Wrapf(err error, format string, args ...any) error

Wrapf adds a formatted message to an error, and optionnally add a stack if it doesn't have one.

Types

type Verboser

type Verboser interface {
	// ErrorVerbose writes the verbose message of the error to the writer.
	// It must only write the verbose message of the error, not the error chain.
	// It is responsible for writing a new line character at the end.
	ErrorVerbose(io.Writer)
}

Verboser is an error that provides verbose information.

It is used by Verbose().