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() creates an error with a message and a stack.

err := errors.New("error")

Wrap() adds a message to an error, and optionally adds a stack if the error doesn't have one.

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

Message() adds a message to an error. Most applications should use Wrap() instead, because it automatically adds a stack.

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

Stack trace

Stack() 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() instead.

err = errors.Stack(err)

StackFrames() 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() 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

• Variables
• func As(err error, target any) bool
• func Is(err, target error) bool
• func Message(err error, msg string) error
• func New(msg string) 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
• type Verboser

Examples

• Message
• New
• Stack
• Verbose
• VerboseFormatter
• VerboseString
• Wrap

Variables

var StackFrameVerboseWriter = func(w io.Writer, f runtime.Frame) {
	_, file := filepath.Split(f.File)
	_, _ = fmt.Fprintf(w, "\t%s %s:%d\n", f.Function, file, f.Line)
}

StackFrameVerboseWriter writes a runtime.Frame to an error verbose message.

It must write a new line character at the end.

It can be changed in order to customize how runtime.Frame are formatted.

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 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.

// Use fmt.Sprintf() to format the message.

Example

err := New("error")
err = Message(err, "message")
fmt.Println(err)

Output:
message: error

func New

func New(msg string) error

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

Use fmt.Sprintf() to format the message.

Example

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

Output:
error

func Stack

func Stack(err error) error

Stack adds a stack to an error.

The verbose message contains the stack.

See https://pkg.go.dev/runtime#Frames .

Example

err := New("error")
err = Stack(err)
fmt.Println(err)
sfs := StackFrames(err)
fmt.Println(len(sfs))

Output:
error
2

func StackFrames

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

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

See https://pkg.go.dev/runtime#Frames .

func Unwrap

func Unwrap(err error) error

Unwrap calls std_errors.Unwrap.

See https://pkg.go.dev/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.

Example

err := New("error")
buf := new(strings.Builder)
Verbose(buf, err)
s := buf.String()
fmt.Println(s)

func VerboseFormatter

func VerboseFormatter(err error) fmt.Formatter

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

Example

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

func VerboseString

func VerboseString(err error) string

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

Example

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

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.

Example

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

Output:
wrap: error

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().