README
¶
phayes/errors: Better error handling for go
Go's standard errors package is a simple error package for handling errors, and works fine for shallow codebases, but has several shortcomings that phayes/errors
hopes to remediate.
The biggest anti-pattern that the standard errors package encourages is one we are all familiar with:
if err != nil
return errors.New(err.Error() + ". Some more details about the error")
}
This anti-pattern is corrected in phayes/errors by allowing you to cleanly wrap one error with another like so:
if err != nil {
return errors.Append(err, "Some more details about the error")
}
This allows us to cleanly add more details to an error, while preseving the underlying error for later inspection.
It also plays nicely with standard library errors and predefined errors
import (
"github.com/phayes/errors"
"io"
)
var ErrFailedStream = errors.New("Failed to read stream.")
func ReadStream(b []byte) error {
n, err := reader.Read(b)
if err != nil {
return errors.Append(ErrFailedStream, err)
}
}
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
if errors.IsA(err, io.EOF) {
return // Success!
} else {
log.Fatal(err) // Prints "Failed to read stream. unexpected EOF"
}
}
}
Wrapping errors
At it's most basic, phayes/errors is a drop in replacement for the standard error package.
err := errors.New("Could not parse input")
However, it also provides the ability to wrap an error to give it more context
import (
"github.com/phayes/errors"
)
func ReadStream(b []byte) error {
n, err := reader.Read(b)
if err != nil {
return errors.Wraps(err, "Failed to read stream.")
}
}
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
log.Fatal(err) // Prints "Failed to read stream. unexpected EOF"
}
}
Inspecting errors
Use the IsA function to check to if the error, or any of it's inner errors, is what you're after. This is fully compatible with errors that
are not part of phayes/errors. For example:
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
if errors.IsA(err, io.EOF) {
return // Success!
} else {
log.Fatal(err)
}
}
}
Documentation
¶
Overview ¶
Package errors provides better error handling.
Go's standard `errors` package is a simple error package for handling errors, and works fine for shallow codebases, but has several shortcomings that `phayes/errors` hopes to remediate.
The biggest anti-pattern that the standard errors package encourages is one we are all familiar with:
if err != nil
return errors.New(err.Error() + ". Some more details about the error")
}
This anti-pattern is corrected in phayes/errors by allowing you to cleanly wrap one error with another like so:
if err != nil {
return errors.Append(err, "Some more details about the error")
}
This allows us to cleanly add more details to an error, while preseving the underlying error for later inspection.
It also plays nicely with standard library errors and predefined errors:
import (
"github.com/phayes/errors"
"io"
)
var ErrFailedStream = errors.New("Failed to read stream.")
func ReadStream(b []byte) error {
n, err := reader.Read(b)
if err != nil {
return errors.Append(ErrFailedStream, err)
}
}
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
if errors.IsA(err, io.EOF) {
return // Success!
} else {
log.Fatal(err) // Prints "Failed to read stream. unexpected EOF"
}
}
}
Wrapping errors ¶
At it's most basic, `phayes/errors` is a drop in replacement for the standard error package.
err := errors.New("Could not parse input")
However, it also provides the ability to wrap an error to give it more context:
import (
"github.com/phayes/errors"
)
func ReadStream(b []byte) error {
n, err := reader.Read(b)
if err != nil {
return errors.Wraps(err, "Failed to read stream.")
}
}
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
log.Fatal(err) // Prints "Failed to read stream. unexpected EOF"
}
}
Inspecting errors ¶
Use the `IsA` function to check to if the error, or any of it's inner errors, is what you're after. This is fully compatible with errors that are not part of phayes/errors. For example:
func main() {
var b []byte
err := ReadStream(b)
if err != nil {
if errors.IsA(err, io.EOF) {
return // Success!
} else {
log.Fatal(err)
}
}
}
Index ¶
- func Append(outerErr error, innerErr error) error
- func Appendf(outerErr error, format string, args ...interface{}) error
- func Appends(outerErr error, inner string) error
- func Cause(err error) error
- func Equal(e1 error, e2 error) bool
- func IsA(outerErr error, innerErr error) bool
- func New(s string) error
- func Newf(format string, args ...interface{}) error
- func Wrap(innerErr error, outerErr error) error
- func Wrapf(err error, format string, args ...interface{}) error
- func Wraps(err error, outer string) error
- type DefaultError
- type Error
- type ErrorSet
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Appendf ¶
Appendf appends more information to the error using formatting. The reverse of Wrapf.
func Cause ¶
Cause returns the root cause of the given error. If err does not implement phayes.Error, it returns err itself.
func IsA ¶
IsA checks if two errors are the same or if the first contains the second This will recursively check their inner components to see if one is an instance of the other
func New ¶
New create new error from string. It intentionally mirrors the standard "errors" module so as to be a drop-in replacement
func Newf ¶
Newf is the same as New, but with fmt.Printf-style parameters. This is a replacement for fmt.Errorf.
Types ¶
type DefaultError ¶
type DefaultError struct {
// contains filtered or unexported fields
}
DefaultError is the default implementation of Error interface
func (DefaultError) Base ¶
func (e DefaultError) Base() error
Base gets the base error that forms the basis of the DefaultError - returns a copy of itself without inners
func (DefaultError) Error ¶
func (e DefaultError) Error() string
Error returns a string with all available error information, including inner errors that are wrapped by this errors.
func (DefaultError) Inner ¶
func (e DefaultError) Inner() error
Inner gets the inner error that is wrapped by this error
func (DefaultError) Message ¶
func (e DefaultError) Message() string
Message returns a string with error information, excluding inner errors
func (DefaultError) Wrap ¶
func (e DefaultError) Wrap(err error) Error
Wrap the passed error in this error and return a copy
type Error ¶
type Error interface {
// This returns the error message without inner errors
Message() string
// Get the inner error. Will return nil if there is no inner error
Inner() error
// Wrap the given error. Calling Inner() should retreive it. Return a copy of the outer error as an Error.
Wrap(error) Error
// Base() should return a copy of the Error without any inners
// This method is called to check two errors for equality
Base() error
// Implements the built-in error interface.
Error() string
}
Error interface may be implemented by other packages
Source Files