README
¶
Package errors
Package errors is an errors wrapping package to help propagate and chain errors as well as attach stack traces, tags(additional information) and even a Type classification system to categorize errors into types eg. Permanent vs Transient.
Common Questions
Why another package? There are two main reasons.
-
I think that the programs generating the original error(s) should be responsible for handling them, even though this package allows access to the original error, and that the callers are mainly interested in:
- If the error is Transient or Permanent for retries.
- Additional details for logging.
-
IMO most of the existing packages either don't take the error handling far enough, too far or down right unfriendly to use/consume.
Features
- works with go-playground/log, the Tags will be added as Field Key Values and Types will be concatenated as well when using
WithError - helpers to extract and classify error types using
RegisterHelper(...), many already existing such as ioerrors, neterrors, awserrors... - built in helpers only need to be imported, eg.
_ github.com/go-playground/errors/v5/helpers/neterrorsallowing libraries to register their own helpers not needing the caller to do or guess what needs to be imported.
Installation
Use go get.
go get -u github.com/go-playground/errors/v5
Usage
package main
import (
"fmt"
"io"
"github.com/go-playground/errors/v5"
)
func main() {
err := level1("testing error")
fmt.Println(err)
if errors.HasType(err, "Permanent") {
// os.Exit(1)
fmt.Println("it is a permanent error")
}
// root error
cause := errors.Cause(err)
fmt.Println("CAUSE:", cause)
// can even still inspect the internal error
fmt.Println(errors.Cause(err) == io.EOF) // will extract the cause for you
fmt.Println(errors.Cause(cause) == io.EOF)
// and still in a switch
switch errors.Cause(err) {
case io.EOF:
fmt.Println("EOF error")
default:
fmt.Println("unknown error")
}
}
func level1(value string) error {
if err := level2(value); err != nil {
return errors.Wrap(err, "level2 call failed")
}
return nil
}
func level2(value string) error {
err := io.EOF
return errors.Wrap(err, "failed to do something").AddTypes("Permanent").AddTags(errors.T("value", value))
}
or using stack only
package main
import (
"fmt"
"github.com/go-playground/errors/v5"
)
func main() {
// maybe you just want to grab a stack trace and process on your own like go-playground/log
// uses it to produce a stack trace log message
frame := errors.Stack()
fmt.Printf("Function: %s File: %s Line: %d\n", frame.Function(), frame.File(), frame.Line())
// and still have access to the underlying runtime.Frame
fmt.Printf("%+v\n", frame.Frame)
}
Package Versioning
Using Go modules and proper semantic version releases (as always).
License
Distributed under MIT License, please see license file in code for more details.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cause ¶
Cause extracts and returns the root wrapped error (the naked error with no additional information
func HasType ¶
HasType is a helper function that will recurse up from the root error and check that the provided type is present using an equality check
func RegisterHelper ¶
func RegisterHelper(helper Helper)
RegisterHelper adds a new helper function to extract Type and Tag information. errors will run all registered helpers until a match is found. NOTE helpers are run in the order they are added.
Types ¶
type Chain ¶
type Chain []*Link
Chain contains the chained errors, the links, of the chains if you will
func New ¶
New creates an error with the provided text and automatically wraps it with line information.
func Newf ¶
Newf creates an error with the provided text and automatically wraps it with line information. it also accepts a varadic for optional message formatting.
func Wrap ¶
Wrap encapsulates the error, stores a contextual prefix and automatically obtains a stack trace.
func WrapSkipFrames ¶
WrapSkipFrames is a special version of Wrap that skips extra n frames when determining error location. Normally only used when wrapping the library
func Wrapf ¶
Wrapf encapsulates the error, stores a contextual prefix and automatically obtains a stack trace. it also accepts a varadic for prefix formatting.
type Helper ¶
Helper is a function which will automatically extract Type and Tag information based on the supplied err and add it to the supplied *Link error; this can be used independently or by registering using errors.RegisterHelper(...), which will run the registered helper every time errors.Wrap(...) is called.
type Link ¶
type Link struct {
// Err is the wrapped error, either the original or already wrapped
Err error
// Prefix contains the error prefix text
Prefix string
// Type stores one or more categorized types of error set by the caller using AddTypes and is optional
Types []string
// Tags contains an array of tags associated with this error, if any
Tags []Tag
// Source contains the name, file and lines obtained from the stack trace
Source runtimeext.Frame
}
Link contains a single error entry, unless it's the top level error, in which case it only contains an array of errors
Source Files
Directories