README
¶
errx
golang errors with stack traces, based off pkg/errors modified for use within my own projects.
errx implements error utilities which make adding context to errors more developer friendly while also preserving the original error.
Create an error
// using errx.New
if ok := someOperation(); !ok {
return errx.New("someOperation failed")
}
// using errx.Errorf
if ok := someOperation(); !ok {
return errx.Errorf("%s failed", "someOperation()")
}
Add context to an error
// using errx.Wrap
_, err := someOperationThatMayErr()
if err != nil {
return errx.Wrap(err, "someOperationThatMayErr() failed")
}
// using errx.Wrapf
_, err := someOperationThatMayErr()
if err != nil {
return errx.Wrapf(err, "%s failed", "someOperationThatMayErr()")
}
Print with stack trace
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
log.Printf("%v", err) // or use %s
yields
outer: middle: inner
at main.main(examples/main.go:13)
at runtime.main(runtime/proc.go:207)
at runtime.goexit(runtime/asm_amd64.s:2362)
Print without stack trace
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
log.Printf("%-v", err) // or use %-s
yields
outer: middle: inner
Print top most error
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
if e, ok := err.(*errx.Error); ok {
log.Print(e.Message)
}
yields
outer
Documentation
¶
Overview ¶
Package errx implements error utilities which make adding context to errors more developer friendly while also preserving the original error.
Add context to an error
// using errx.Wrap
_, err := someOperationThatMayErr()
if err != nil {
return errx.Wrap(err, "someOperationThatMayErr() failed")
}
// using errx.Wrapf
_, err := someOperationThatMayErr()
if err != nil {
return errx.Wrapf(err, "%s failed", "someOperationThatMayErr()")
}
Create an error
// using errx.New
if ok := someOperation(); !ok {
return errx.New("someOperation failed")
}
// using errx.Errorf
if ok := someOperation(); !ok {
return errx.Errorf("%s failed", "someOperation()")
}
Printing error messages with stack traces:
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
log.Printf("%v", err) // or use %s
results in the following:
outer: middle: inner at main.main(examples/main.go:13) at runtime.main(runtime/proc.go:207) at runtime.goexit(runtime/asm_amd64.s:2362)
Printing error messages without stack traces:
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
log.Printf("%-v", err) // or use %-s
results in the following:
outer: middle: inner
Printing top most error message only:
err := errx.Wrap(errx.Wrap(errors.New("inner"), "middle"), "outer")
if e, ok := err.(*errx.Error); ok {
log.Print(e.Message)
}
results in the following:
outer
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdjustCallerSkipLevel ¶
func AdjustCallerSkipLevel(amt int)
AdjustCallerSkipLevel sets the number of callers to skip when building a stack frame. By default if this function is not called, all stack traces will originate at the point where errx.New, errx.Errorf, errx.Wrap, or errx.Wrapf was called.
If any of these functions is wrapped, AdjustCallerSkipLevel should be called with the number of wrapping functions. It is not goroutine safe and is intended to be set as part of an initialization routine.
For example, if errx.New was wrapped in a helper function, e.g. SetupError(args...), then AdjustCallerSkipLevel should be called with a value of 1.
func Errorf ¶
Errorf creates a new error with a stack trace at the point which Errorf was called, a formatted message, and a nil inner error.
func New ¶
New creates a new error with a stack trace at the point which New was called, a message, and a nil inner error.
Types ¶
type Error ¶
type Error struct {
// Inner represents the inner error of this error, it can be nil.
Inner error
// Message represents the message associated with this error.
Message string
// StackTrace is the StackTrace of the inner most error, hoisted up into this error.
StackTrace StackTrace
}
Error wraps an error and has a message and stack trace associated with it. It implements the fmt.Formatter interface and responds to different format verbs and flags.
To print with stack traces use %v, %s. To omit stack traces use %-v, %-s.
type StackFrame ¶
type StackFrame struct {
// FunctionName is the function which created this stack frame.
FunctionName string
// FileName is the file in which the function exists as an absolute path (includes $GOPATH/src)
FileName string
// TrimmedFileName represents the FileName without the $GOPATH/src prepended
TrimmedFileName string
// Line is the line number associated with the stack frame
Line int
}
StackFrame is a description of a function in a stack trace
func (*StackFrame) String ¶
func (s *StackFrame) String() string
type StackTrace ¶
type StackTrace []StackFrame
StackTrace represents a slice of StackFrame, a StackTrace will usually contain at least 2 elements, however, it should be treated as if it could contain zero StackFrames
func (StackTrace) String ¶
func (s StackTrace) String() string
Source Files