errors

README

Errors

Go errors library.

Features

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

Message

New() creates an error with a message.

Wrap() adds a message to an error.

err := errors.New("error")
err = errors.Wrap(err, "message")
fmt.Println(err) // "message: error"

Stack trace

Errors created by New() and wrapped by Wrap() have a stack trace.

The error verbose message includes the stack trace.

errstack.Frames() 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 Write()/String()/Formatter() 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/integration_test_test.Test integration_test.go:17
    testing.tRunner testing.go:1576
    runtime.goexit asm_amd64.s:1598

Extend

Create a custom error type:

• Create a type implementing the error interface
• Optionally implement the Unwrap() error method
• Optionally implement the errverbose.Interface interface

See the provided packages as example:

• errbase: create a base error (e.g. sentinel error)
• errmsg: add a message to an error
• errstack: add a stack trace to an error
• 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 New(msg string) error
• func Newf(format string, args ...any) error
• func Unwrap(err error) error
• func Wrap(err error, msg string) error
• func Wrapf(err error, format string, args ...any) error

Examples

• New
• Wrap

Functions

func As

func As(err error, target any) bool

As calls std_errors.As.

See https://pkg.go.dev/errors#As .

func Is

func Is(err, target error) bool

Is calls std_errors.Is.

See https://pkg.go.dev/errors#Is .

func New

func New(msg string) error

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

Example

err := New("error")
fmt.Println(err)

Output:
error

func Newf

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

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

func Unwrap

func Unwrap(err error) error

Unwrap calls std_errors.Unwrap.

See https://pkg.go.dev/errors#Unwrap .

func Wrap

func Wrap(err error, msg string) error

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

Example

err := errbase.New("error")
err = Wrap(err, "wrap")
fmt.Println(err)

Output:
wrap: error

func Wrapf

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

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