README
¶
Emperror: Errors
Drop-in replacement for the standard library errors package and github.com/pkg/errors.
This is a single, lightweight library merging the features of standard library errors package
and github.com/pkg/errors. It also backports a few features
(like Go 1.13 error handling related features).
Standard library features:
Newcreates an error with stack traceUnwrapsupports both Go 1.13 wrapper (interface { Unwrap() error }) and pkg/errors causer (interface { Cause() error }) interface- Backported
IsandAsfunctions
github.com/pkg/errors features:
New,Errorf,WithMessage,WithMessagef,WithStack,Wrap,Wrapffunctions behave the same way as in the original libraryCausesupports both Go 1.13 wrapper (interface { Unwrap() error }) and pkg/errors causer (interface { Cause() error }) interface
Additional features:
NewPlaincreates a new error without any attached context, like stack traceWithStackDepthallows attaching stack trace with a custom caller depth
Installation
go get emperror.dev/errors
Usage
package main
import "emperror.dev/errors"
var ErrSomethingWentWrong = errors.NewPlain("something went wrong")
type ErrMyError struct {
Msg string
}
func (e ErrMyError) Error() string {
return e.Msg
}
func foo() error {
return errors.Wrap(ErrSomethingWentWrong, "error")
}
func bar() error {
return errors.Wrap(ErrMyError{"something went wrong"}, "error")
}
func main() {
if err := foo(); err != nil {
if errors.Cause(err) == ErrSomethingWentWrong {
// handle error
}
}
if err := bar(); err != nil {
if errors.As(err, &ErrMyError{}) {
// handle error
}
}
}
Development
When all coding and testing is done, please run the test suite:
$ make check
License
The MIT License (MIT). Please see License File for more information.
Documentation
¶
Overview ¶
Package errors is a drop-in replacement for the standard errors package and github.com/pkg/errors.
Index ¶
- func As(err error, target interface{}) bool
- func Cause(err error) error
- func Errorf(format string, a ...interface{}) error
- func Is(err, target error) bool
- func New(message string) error
- func NewPlain(message string) error
- func Unwrap(err error) error
- func WithMessage(err error, message string) error
- func WithMessagef(err error, format string, a ...interface{}) error
- func WithStack(err error) error
- func WithStackDepth(err error, depth int) error
- func Wrap(err error, message string) error
- func Wrapf(err error, format string, a ...interface{}) error
- type Frame
- type StackTrace
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's chain that matches the type to which target points, and if so, sets the target to its value and returns true. An error matches a type if it is assignable to the target type, or if it has a method As(interface{}) bool such that As(target) returns true. As will panic if target is not a non-nil pointer to a type which implements error or is of interface type.
The As method should set the target to its value and return true if err matches the type to which target points.
Example ¶
package main
import (
"fmt"
"os"
"emperror.dev/errors"
)
func main() {
if _, err := os.Open("non-existing"); err != nil {
var pathError *os.PathError
if errors.As(err, &pathError) {
fmt.Println("Failed at path:", pathError.Path)
} else {
fmt.Println(err)
}
}
}
Output: Failed at path: non-existing
func Cause ¶
Cause returns the last error (root cause) in an error chain. If the error has no cause, it is returned directly.
It supports both Go 1.13 errors.Wrapper and github.com/pkg/errors.Causer interfaces (the former takes precedence).
func Errorf ¶
Errorf returns a new error with a formatted message and annotated with stack trace at the point Errorf is called.
func Is ¶
Is reports whether any error in err's chain matches target.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
func NewPlain ¶
NewPlain returns a simple error without any annotated context, like stack trace. Useful for creating sentinel errors and in testing.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err implements Unwrap. Otherwise, Unwrap returns nil.
It supports both Go 1.13 Unwrap and github.com/pkg/errors.Causer interfaces (the former takes precedence).
func WithMessage ¶
WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.
func WithMessagef ¶
WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil.
func WithStack ¶
WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.
func WithStackDepth ¶
WithStackDepth annotates err with a stack trace at the given call depth. Zero identifies the caller of WithStackDepth itself. If err is nil, WithStackDepth returns nil.
Types ¶
type Frame ¶
Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.
It is an alias of the same type in github.com/pkg/errors.
type StackTrace ¶
type StackTrace = errors.StackTrace
StackTrace is stack of Frames from innermost (newest) to outermost (oldest).
It is an alias of the same type in github.com/pkg/errors.
Source Files