https://github.com/bdlm/errors
Simple, concise error handling and annotation for Go
https://github.com/bdlm/errors
error-stacks errors exceptions go golang stack-trace
Last synced: 24 days ago
JSON representation
Simple, concise error handling and annotation for Go
- Host: GitHub
- URL: https://github.com/bdlm/errors
- Owner: bdlm
- License: mit
- Created: 2018-05-17T07:01:30.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-05-12T22:56:41.000Z (over 4 years ago)
- Last Synced: 2025-08-13T20:56:59.202Z (6 months ago)
- Topics: error-stacks, errors, exceptions, go, golang, stack-trace
- Language: Go
- Homepage: https://pkg.go.dev/github.com/bdlm/errors/v2
- Size: 95.7 KB
- Stars: 6
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# errors
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). This package is considered mature, you should expect package stability in Minor and Patch version releases
- **Major**: backwards incompatible package updates
- **Minor**: feature additions, removal of deprecated features
- **Patch**: bug fixes, backward compatible model and function changes, etc.
**[CHANGELOG](CHANGELOG.md)**
`errors` provides simple, concise, useful error handling and annotation. This package aims to implement the [Error Inspection](https://go.googlesource.com/proposal/+/master/design/go2draft-error-inspection.md) and [Error Values](https://go.googlesource.com/proposal/+/master/design/go2draft-error-values-overview.md) Go2 [draft designs](https://go.googlesource.com/proposal/+/master/design/go2draft.md).
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:
```go
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](https://pkg.go.dev/github.com/bdlm/errors#pkg-examples) for more examples. All package methods work with any `error` type as well as `nil` values, and error instances implement the [`Unwrap`](https://go.googlesource.com/proposal/+/master/design/go2draft-error-inspection.md), [`Is`](https://go.googlesource.com/proposal/+/master/design/go2draft-error-inspection.md), [`Marshaler`](https://golang.org/pkg/encoding/json/#Marshaler), and [`Formatter`](https://golang.org/pkg/fmt/#Formatter) interfaces as well as the [`github.com/bdlm/std/errors`](https://github.com/bdlm/std/tree/master/errors) interfaces.
#### Create an error
```go
var MyError = errors.New("My error")
```
#### Create an error using formatting verbs
```go
var MyError = errors.Errorf("My error #%d", 1)
```
#### Wrap an error
```go
if nil != err {
return errors.Wrap(err, "the operation failed")
}
```
#### Wrap an error with another error
```go
err := try1()
if nil != err {
err2 := try2()
if nil != err2 {
return errors.WrapE(err, err2)
}
return err
}
```
#### Get the previous error, if any
```go
err := doWork()
if prevErr := errors.Unwrap(err); nil != prevErr {
...
}
```
#### Test to see if a specific error type exists anywhere in an error stack
```go
var MyError = errors.New("My error")
func main() {
err := doWork()
if errors.Is(err, MyError) {
...
}
}
```
#### Iterate through an error stack
```go
err := doWork()
for nil != err {
fmt.Println(err)
err = errors.Unwrap(err)
}
```
#### Formatting verbs
`errors` implements the `%s` and `%v` [`fmt.Formatter`](https://golang.org/pkg/fmt/#hdr-Printing) 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)`
```json
{"error":"An error occurred"}
```
`fmt.Printf("%#-v", err)`
```json
{"caller":"#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)","error":"An error occurred"}
```
`fmt.Printf("%#+v", err)`
```json
[{"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)`
```json
{
"caller": "#0 stack_test.go:40 (github.com/bdlm/error_test.TestErrors)",
"error": "An error occurred"
}
```
`fmt.Printf("% #+v", err)`
```json
[
{
"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](https://godoc.org/github.com/bdlm/errors#pkg-examples) for more examples.