README
¶
golang package for enhanced errors that capture file and line number information, the call stack, relevant identifiers, and a handle back to the original error for type switching.
Replacement for fmt.Errorf(...):
err := errors.Errorf("Failed to do something; here's a value %v",len(data))
fmt.Printf("%#v\n",err) // Prints full stack trace.
Wrap another function's error:
_, err := net.Dial( "tcp", "localhost:8080" )
if err != nil {
return errors.Go( err )
}
Obtain the original error in order to type switch:
func connect() error {
_, err := net.Dial( "tcp", "localhost:0" )
if err != nil {
return errors.Go( err )
}
return nil
}
err := connect()
switch errors.Original( err ).(type) {
case *net.OpError:
// We know the original type!
}
See the godoc link for more information.
Documentation
¶
Overview ¶
Package errors provides enhanced error reporting and specific error types.
This package provides errors with more information about when and where they occurred; the call to Printf will print file name, line number, and stack information.
err := errors.Errorf("An error occurred because len() == %v", len(something))
fmt.Printf("%#v\n",err) // Prints full stack trace.
Go() can wrap an existing error within the Error interface defined in this package.
err := someApi()
if err != nil {
return errors.Go(err)
}
Utility Methods ¶
For receivers that are pointers:
func (me *Type) Do() error {
if me == nil {
return errors.NilReceiver().Type(me)
}
}
For required arguments that are nil:
func Make( arg *Conf ) (*Type, error) {
if arg == nil {
return nil, errors.NilArgument( "arg" ).Type( arg );
}
}
Original Error ¶
It may be helpful for your error handling code to type switch on the original error when wrapping it within errors.Go(); see documentation and example for Original().
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Original ¶
func Original(err error) interface{}
Original returns a non-nil interface if the incoming type is an Error from this package.
Example ¶
package main
import (
"fmt"
"net"
"github.com/nofeaturesonlybugs/errors"
)
func main() {
// Demonstrates how to type switch on the original error when using this package.
var err error
// This test block ensures type switching works when nil is passed to Original.
noError := func() error {
return nil
}
err = noError()
switch errors.Original(err).(type) {
default:
fmt.Printf("Works when error is nil.\n")
}
// This test block ensures type switching works when the error is Error from this package
// but has a nil return value for Interface() method.
errorf := func() error {
return errors.Errorf("A formatted error!")
}
err = errorf()
switch errors.Original(err).(type) {
default:
fmt.Printf("Works when error is error.Error but nil interface.\n")
}
// This test block shows the more practical usage of looking for a specifc error.
netOpError := func() error {
_, err := net.Dial("blurp", "localhost:0")
if err != nil {
return errors.Go(err)
}
return nil
}
err = netOpError()
switch errors.Original(err).(type) {
case *net.OpError:
fmt.Printf("Got expected *net.OpErr\n")
default:
fmt.Printf("Expected *net.OpError; got %T\n", err)
}
// This final example shows an unwrapped error is returned as-is by Original.
netOpErrorUnwrapped := func() error {
_, err := net.Dial("blurp", "localhost:0")
return err
}
err = netOpErrorUnwrapped()
if originalErr := errors.Original(err); originalErr == err {
fmt.Println("Original error returned when unwrapped.")
}
}
Output: Works when error is nil. Works when error is error.Error but nil interface. Got expected *net.OpErr Original error returned when unwrapped.
Types ¶
type Error ¶
type Error interface {
// Error returns a string value of the Error and satisfies built-in error interface.
Error() string
// Format implements fmt.Formatter interface; %#v, %+v will print error information plus call stack.
Format(fmt.State, rune)
// Interface returns the underlying error in order to support type switching; this allows error types from
// other packages to be wrapped with Go() but still type switch on the underlying type.
Interface() interface{}
// Stack returns slice of Frame objects to represent the stack frame.
Stack() []Frame
// Tag adds extra information to the error and returns the type for method chaining.
Tag(name, value string) Error
// Type adds a special Tag() with type=%T information.
Type(interface{}) Error
}
Error is the interface returned by functions in this package.
Example (NilArgument) ¶
package main
import (
"fmt"
"github.com/nofeaturesonlybugs/errors"
)
func main() {
type T struct{}
fn := func(arg *T) error {
if arg == nil {
return errors.NilArgument("arg").Type(arg)
}
return nil
}
if err := fn(nil); err != nil {
fmt.Println(err)
_ = fmt.Sprintf("%#v", err)
}
}
Output: Nil argument; identifier=arg; type=*errors_test.T
Example (NilMember) ¶
package main
import (
"fmt"
"github.com/nofeaturesonlybugs/errors"
)
type B struct {
V *int
}
func (b *B) DoIt() error {
if b == nil {
return errors.NilReceiver()
} else if b.V == nil {
return errors.NilMember("V").Type(b.V)
}
fmt.Println("Did it!")
return nil
}
func (b *B) String() (string, error) {
if b == nil {
return "", errors.NilReceiver().Type(b)
}
return "Hello, World!", nil
}
func main() {
var b *B
b = &B{}
if s, err := b.String(); err != nil {
fmt.Println(err)
} else {
fmt.Println(s)
}
if err := b.DoIt(); err != nil {
fmt.Println(err)
}
b = nil
if s, err := b.String(); err != nil {
fmt.Println(err)
} else {
fmt.Println(s)
}
}
Output: Hello, World! Nil member; member=V; type=*int Nil receiver; type=*errors_test.B
Example (NilReceiver) ¶
package main
import (
"fmt"
"github.com/nofeaturesonlybugs/errors"
)
type A struct{}
func (a *A) String() (string, error) {
if a == nil {
return "", errors.NilReceiver().Type(a)
}
return "Hello, World!", nil
}
func main() {
var a *A
a = &A{}
if s, err := a.String(); err != nil {
fmt.Println(err)
} else {
fmt.Println(s)
}
a = nil
if s, err := a.String(); err != nil {
fmt.Println(err)
} else {
fmt.Println(s)
}
}
Output: Hello, World! Nil receiver; type=*errors_test.A
func AlreadyStarted ¶
func AlreadyStarted() Error
AlreadyStarted returns an error representing a service that has already started and can not start again.
func Errorf ¶
Errorf is similar to fmt.Errorf except it returns the enhanced Error interface from this package.
func Go ¶
Go returns an Error if the passed `err` is non-nil; the purpose of this function is to wrap contextual information, such as call stack, to the initial error.
func NilArgument ¶
NilArgument creates an error when a function argument is nil.
func MyFunc(a *int) (int, error) {
if a == nil {
return 0, NilArgument("a").Type(a)
}
return *a, nil
}
func NilMember ¶
NilMember creates an error when a struct member is nil.
func (me SomeType) DoIt() error {
if me.member == nil {
return NilMember("me.member").Type(me.member)
}
return nil
}
func NilReceiver ¶
func NilReceiver() Error
NilReceiver creates an error when a receiver is nil.
func (me *SomeType) DoIt() error {
if me == nil {
return NilReceiver()
}
return nil
}
Source Files