errors

CHANGELOG - This project adheres to Semantic Versioning. You should expect API stability in Minor and Patch version releases

Code has proven satisfactory and is in wide production use, cleanup of the underlying code may cause some minor changes. Backwards-compatibility is guaranteed.

errors provides simple, concise, useful error handling and annotation. This package aims to implement the Error Inspection and Error Values Go2 draft designs.

One of the biggest frustrations with Go error handling is the lack of forensic and meta information errors should provide. By default errors are just a string and possibly a type. They can't tell you where they occurred or the path through the call stack they followed. The error implementation in Go is robust enough to control program flow but it's not very efficient for troubleshooting or analysis.

Since the idom in Go is that we pass the error back up the stack anyway:

if nil != err {
	return err
}

it's trivial to make errors much more informative with a simple error package. bdlm/errors makes this easy and supports tracing the call stack and the error callers with relative ease. Custom error types are also fully compatible with this package and can be used freely.

Install

go get github.com/bdlm/errors/v2

Quick start

See the documentation for more examples. All package methods work with any error type as well as nil values, and error instances implement the Unwrap, Is, Marshaler, and Formatter interfaces as well as the github.com/bdlm/std/errors interfaces.

Create an error

var MyError = errors.New("My error")

Create an error using formatting verbs

var MyError = errors.Errorf("My error #%d", 1)

Wrap an error

if nil != err {
	return errors.Wrap(err, "the operation failed")
}

Wrap an error with another error

err := try1()
if nil != err {
	err2 := try2()
	if nil != err2 {
		return errors.WrapE(err, err2)
	}
	return err
}

Get the previous error, if any

err := doWork()
if prevErr := errors.Unwrap(err); nil != prevErr {
	...
}

Test to see if a specific error type exists anywhere in an error stack

var MyError = errors.New("My error")
func main() {
	err := doWork()
	if errors.Is(err, MyError) {
		...
	}
}

Iterate through an error stack

err := doWork()
for nil != err {
	fmt.Println(err)
	err = errors.Unwrap(err)
}

Formatting verbs

errors implements the %s and %v fmt.Formatter formatting verbs and several modifier flags:

Verbs

• %s - Returns the error string of the last error added.
• %v - Alias for %s

Flags

• # - JSON formatted output, useful for logging
• - - Output caller details, useful for troubleshooting
• + - Output full error stack details, useful for debugging
• - (space) Add whitespace formatting for readability, useful for development

Examples

fmt.Printf("%s", err)

An error occurred

fmt.Printf("%v", err)

An error occurred

fmt.Printf("%-v", err)

#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors) - An error occurred

fmt.Printf("%+v", err)

#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors) - An error occurred #1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors) - An error occurred

fmt.Printf("%#v", err)

{"error":"An error occurred"}

fmt.Printf("%#-v", err)

{"caller":"#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"}

fmt.Printf("%#+v", err)

[{"caller":"#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"},{"caller":"#1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"}]

fmt.Printf("% #-v", err)

{
    "caller": "#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)",
    "error": "An error occurred"
}

fmt.Printf("% #+v", err)

[
    {
        "caller": "#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)",
        "error": "An error occurred"
    },
    {
        "caller": "#1 stack_test.go:39 (github.com/bdlm/error_test.TestErrors)",
        "error": "An error occurred"
    }
]

See the documentation for more examples.