README
¶
Since this page would just duplicate the documentation, simply go to https://godoc.org/github.com/soul9/errors to see examples and documentation.
Documentation
¶
Overview ¶
Package errors provides a list of errors that have stack-traces, and formattable errors that can be compared.
This is particularly useful when you want to understand the state of execution when an error was returned unexpectedly.
It provides the type *Errors which implements the standard golang error interface, so you can use this library interchangably with code that is expecting a normal error return.
It also provides two extra types: *Errf and *Errors. I wanted to be able to have comparable, more helpful errors so *Errf is a closure for Errorf that stores an error type, so each time an error made with Newf is called, it will return an error that compares as true to the original Errf, while adding extra information to the error message. I also wanted to be able to chain errors together for the case when an error is not fatal for a function, but I still want to store it which is what the *Errors type does.
The Error() function of the *Errors type displays the StackTrace by default.
For example:
package crashy
import "github.com/soul9/errors"
var Crashed = errors.Newf("oh %s")
func Crash(s string) error {
return Crashed(s)
}
This can be called as follows:
package main
import (
"crashy"
"fmt"
"github.com/soul9/errors"
)
func main() {
err := crashy.Crash("dear")
err = errors.Add(err, crashy.Crash("my"))
if err != nil {
if errors.Is(err, crashy.Crashed()) {
fmt.Println(err)
} else {
panic(err)
}
}
}
This package was original written to allow reporting to Bugsnag, but after I found similar packages by Facebook and Dropbox, it was moved to one canonical location so everyone can benefit.
Index ¶
- Variables
- func Add(e interface{}, ee interface{}) error
- func Errorf(format string, a ...interface{}) error
- func Is(e error, original error) bool
- func IsExist(err error) bool
- func IsFunc(fn func(error) bool, err error) bool
- func IsNotExist(err error) bool
- func IsPermission(err error) bool
- func New(err interface{}) error
- func NewError(e interface{}) error
- func Wrap(e interface{}, skip int) error
- func WrapPrefix(e interface{}, prefix string, skip int) error
- type Errf
- type Error
- type ErrorStacker
- type Errors
- type StackFrame
Constants ¶
This section is empty.
Variables ¶
var (
// The maximum number of stackframes on any error.
MaxStackDepth = 50
)
Functions ¶
func Add ¶
func Add(e interface{}, ee interface{}) error
Add returns a list of errors that contains both parameters, no matter their error type.
func Errorf ¶
Errorf creates a new error with the given message. You can use it as a drop-in replacement for fmt.Errorf() to provide descriptive errors in return values.
func Is ¶
Is detects whether the error is equal to a given error. Errors are considered equal by this function if they are the same object, or if they both contain the same error inside an errors.Error, or if they have the same id inside an errors.Error, or if one of the errors in an errors.Errors Is the same as the error.
func IsExist ¶
IsExist checks for os.IsExist on provided error, whether it is an *Errors, *Error, or error
func IsFunc ¶
IsFunc try-casts err for *Error or *Errors, and checks the underlying error(s) against provided fn. If error is not of type *Error or *Errors, IsFunc simply calls fn(err)
func IsNotExist ¶
IsNotExist checks for os.IsNotExist on provided error, whether it is an *Errors, *Error, or error
func IsPermission ¶
IsPermission checks for os.IsPermission on provided error, whether it is an *Errors, *Error, or error
func New ¶
func New(err interface{}) error
New returns a list of errors with the parameter added to the list.
func NewError ¶
func NewError(e interface{}) error
NewError makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The stacktrace will point to the line of code that called New.
func Wrap ¶
Wrap makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.
func WrapPrefix ¶
WrapPrefix makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The prefix parameter is used to add a prefix to the error message when calling Error(). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.
Types ¶
type Errf ¶
type Errf func(...interface{}) error
Errf is a closure around Errorf to provide comparable but descriptive errors
type Error ¶
type Error struct {
Err error
// contains filtered or unexported fields
}
Error is an error with an attached stacktrace. It can be used wherever the builtin error interface is expected.
func ParsePanic ¶
ParsePanic allows you to get an error object from the output of a go program that panicked. This is particularly useful with https://github.com/mitchellh/panicwrap.
func (*Error) ErrorStack ¶
ErrorStack returns a string that contains both the error message and the callstack. Satisfies the ErrorStacker interface.
func (*Error) Stack ¶
Stack returns the callstack formatted the same way that go does in runtime/debug.Stack()
func (*Error) StackFrames ¶
func (err *Error) StackFrames() []StackFrame
StackFrames returns an array of frames containing information about the stack.
type ErrorStacker ¶
ErrorStacker is an interface satisfying the error interface that is also aware of the stackcall of the error, printed with ErrorStack(), and able to compare itself to another error with Is(error)
type Errors ¶
type Errors struct {
// contains filtered or unexported fields
}
Errors is a list of errors with stack traces. It implements the error interface
func (*Errors) Add ¶
Add returns a list of errors with the parameter added to the receiver, it will behave correctly with a simple error, as well as with an errors.Error and an errors.Errors as parameters. It will also log the error using glog if a verbosity of 3 or more is specified.
func (*Errors) ErrorStack ¶
ErrorStack returns all the stack traces and error messages of the included errors. Satisfies the ErrorStacker interface.
type StackFrame ¶
type StackFrame struct {
// The path to the file containing this ProgramCounter
File string
// The LineNumber in that file
LineNumber int
// The Name of the function that contains this ProgramCounter
Name string
// The Package that contains this function
Package string
// The underlying ProgramCounter
ProgramCounter uintptr
}
A StackFrame contains all necessary information about to generate a line in a callstack.
func NewStackFrame ¶
func NewStackFrame(pc uintptr) (frame StackFrame)
NewStackFrame popoulates a stack frame object from the program counter.
func (*StackFrame) Func ¶
func (frame *StackFrame) Func() *runtime.Func
Func returns the function that contained this frame.
func (*StackFrame) SourceLine ¶
func (frame *StackFrame) SourceLine() (string, error)
SourceLine gets the line of code (from File and Line) of the original source if possible.
func (*StackFrame) String ¶
func (frame *StackFrame) String() string
String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()
Source Files