errors

package
v0.23.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 11, 2024 License: Unlicense Imports: 3 Imported by: 59

Documentation

Overview

Package errors is a drop-in replacement and extension of the Go standard library's package errors.

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrUnsupported = stderrors.ErrUnsupported

ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported. For example, a call to os.Link when using a file system that does not support hard links.

Functions

func Annotate

func Annotate(err error, format string, args ...any) (annotated error)

Annotate annotates the error with the message, unless the error is nil. The last verb in format must be a verb compatible with errors, for example "%w".

In Defers

The primary use case for this function is to simplify code like this:

func (f *foo) doStuff(s string) (err error) {
	defer func() {
		if err != nil {
			err = fmt.Errorf("bad foo %q: %w", s, err)
		}
	}()

	// …
}

Instead, write:

func (f *foo) doStuff(s string) (err error) {
	defer func() { err = errors.Annotate(err, "bad foo %q: %w", s) }()

	// …
}

At The End Of Functions

Another possible use case is to simplify final checks like this:

func (f *foo) doStuff(s string) (err error) {
	// …

	if err != nil {
		return fmt.Errorf("doing stuff with %s: %w", s, err)
	}

	return nil
}

Instead, you could write:

func (f *foo) doStuff(s string) (err error) {
	// …

	return errors.Annotate(err, "doing stuff with %s: %w", s)
}

Warning

This function requires that there be only ONE error named "err" in the function and that it is always the one that is returned. Example (Bad) provides an example of the incorrect usage of WithDeferred.

Example
Output:


with err    : reading "non-existing": not found
without err : <nil>
Example (Bad)
Output:


not found
Example (End)
Output:


with err    : reading "non-existing": not found
without err : <nil>

func As

func As(err error, target any) (ok bool)

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.

It calls errors.As from the Go standard library.

Example
Output:


Failed at path: non-existing

func Is

func Is(err, target error) (ok bool)

Is reports whether any error in err's chain matches target.

It calls errors.Is from the Go standard library.

Example
Output:


file does not exist

func Join added in v0.12.1

func Join(errs ...error) error

Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if errs contains no non-nil values. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string.

It calls errors.Join from the Go standard library.

func List deprecated

func List(msg string, errs ...error) (err error)

List wraps several errors into a single error with an additional message.

Deprecated: Use errors.Join instead.

Example
Output:


msg only     : "fail" <nil>
msg and err  : "fail: stage 1" "stage 1"
msg and errs : "fail: 2 errors: \"stage 1\", \"stage 2\"" "stage 1"

func New deprecated

func New(msg string) (err error)

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

It calls errors.New from the Go standard library.

Deprecated: Use type Error and constant errors instead.

Example
Output:


emit macho dwarf: elf header corrupted

func Unwrap

func Unwrap(err error) (unwrapped 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.

It calls errors.Unwrap from the Go standard library.

func WithDeferred

func WithDeferred(returned, deferred error) (result error)

WithDeferred is a helper function for deferred errors. For example, to preserve errors from the Close method, replace this:

defer f.Close()

With this:

defer func() { err = errors.WithDeferred(err, f.Close()) }

If returned is nil and deferred is non-nil, the returned error implements the Deferred interface. If both returned and deferred are non-nil, result has the underlying type of *Pair.

Warning

This function requires that there be only ONE error named "err" in the function and that it is always the one that is returned. Example (Bad) provides an example of the incorrect usage of WithDeferred.

Example
Output:


without errs      : <nil>
with returned err : not found
with deferred err : deferred: close fail
with both errs    : returned: "not found", deferred: "close fail"
Example (Bad)
Output:


not found

Types

type Aser

type Aser interface {
	As(target any) (ok bool)
}

Aser is a copy of the hidden aser interface from the Go standard library. It is added here for tests, linting, etc.

type Deferred

type Deferred interface {
	error
	Deferred() (ok bool)
}

Deferred is the interface for errors that were returned by cleanup functions, such as Close. This is useful in APIs which desire to handle such errors differently, for example to log them as warnings.

Method Deferred returns a bool to mirror the behavior of types like net.Error and allow implementations to decide if the error is a deferred one dynamically. Users of this API must check it's return value as well as the result errors.As.

if derr := errors.Deferred(nil); errors.As(err, &derr) && derr.Deferred() {
        // …
}

See https://dave.cheney.net/2014/12/24/inspecting-errors.

Example
Output:


ERROR: not found
warning: close fail

type Error

type Error string

Error is the constant error type.

See https://dave.cheney.net/2016/04/07/constant-errors.

Example
Output:


err       : opening "non-existing": not found
unwrapped : not found

func (Error) Error

func (err Error) Error() (msg string)

Error implements the error interface for Error.

type Iser

type Iser interface {
	Is(target error) (ok bool)
}

Iser is a copy of the hidden iser interface from the Go standard library. It is added here for tests, linting, etc.

type Pair

type Pair struct {
	Returned error
	Deferred error
}

Pair is a pair of errors. The Returned error is the main error that has been returned by a function. The Deferred error is the error returned by the cleanup function, such as Close.

In pairs returned from WithDeferred, the Deferred error always implements the Deferred interface.

Example
Output:


err       : returned: "not found", deferred: "close fail"
unwrapped : not found

deferred           : deferred: close fail
deferred unwrapped : close fail
deferred check     : true

func (*Pair) Error

func (err *Pair) Error() string

Error implements the error interface for *Pair.

func (*Pair) Unwrap

func (err *Pair) Unwrap() (unwrapped error)

Unwrap implements the Wrapper interface for *Pair. It returns the Returned error.

type Wrapper

type Wrapper interface {
	Unwrap() error
}

Wrapper is a copy of the hidden wrapper interface from the Go standard library. It is added here for tests, linting, etc.

type WrapperSlice added in v0.12.1

type WrapperSlice interface {
	Unwrap() []error
}

WrapperSlice is a copy of the hidden wrapper interface added to the Go standard library in Go 1.20. It is added here for tests, linting, etc.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL