README
¶
exception
This is a simple library for wrapping errors.Error with a stack trace.
##Sample Output
If we run ex.Error() on an Exception we will get a more detailed output than a normal errorString
Exception: this is a sample error
At: foo_controller.go:20 testExceptions()
http.go:198 func1()
http.go:213 func1()
http.go:117 func1()
router.go:299 ServeHTTP()
server.go:1862 ServeHTTP()
server.go:1361 serve()
asm_amd64.s:1696 goexit()
##Usage
If we want to create a new exception we can use New
return exception.New("this is a test exception")
New will create a stack trace at the given line. It ignores stack frames within the exception package itself.
There is also a convenience method Newf that will mimic Printf like functions.
If we want to wrap an existing golang error all we have to do is call Wrap
file, fileErr := os.ReadFile("my_file.txt")
if fileErr != nil {
return exception.Wrap(fileErr)
}
A couple properties of wrap:
- It will return nil if the input error is nil
- It will not modify an error that is actually an exception, it will simply return (propagate) it.
- It will create a stack trace for the error if it is not nil, and assign the message from the existing error.
If we want to merge a couple exceptions together, i.e. we can use WrapMany
if q.Rows != nil {
if closeErr := q.Rows.Close(); closeErr != nil {
return exception.WrapMany(q.Error, closeErr)
}
}
WrapMany will "nest" the exceptions, and this will be reflected in the output.
Documentation
¶
Index ¶
- func GetStackTrace() string
- func Is(err error) bool
- func Wrap(err error) error
- type Ex
- func (e *Ex) Class() string
- func (e *Ex) Decompose() map[string]interface{}
- func (e *Ex) Error() string
- func (e *Ex) Format(s fmt.State, verb rune)
- func (e *Ex) Inner() error
- func (e *Ex) MarshalJSON() ([]byte, error)
- func (e *Ex) Message() string
- func (e *Ex) Stack() StackTrace
- func (e *Ex) StackString() string
- func (e *Ex) WithClass(class string) Exception
- func (e *Ex) WithInner(err error) Exception
- func (e *Ex) WithMessagef(format string, args ...interface{}) Exception
- func (e *Ex) WithStack(stack StackTrace) Exception
- type Exception
- type Frame
- type StackPointers
- type StackStrings
- type StackTrace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetStackTrace ¶
func GetStackTrace() string
GetStackTrace is a utility method to get the current stack trace at call time.
Types ¶
type Ex ¶
type Ex struct {
// contains filtered or unexported fields
}
Ex is an error with a stack trace.
func (*Ex) Decompose ¶
Decompose breaks the exception down to be marshalled into an intermediate format.
func (*Ex) Format ¶
Format allows for conditional expansion in printf statements based on the token and flags used.
%+v : class + message + stack %v, %c : class %m : message %t : stack
func (*Ex) MarshalJSON ¶
MarshalJSON is a custom json marshaler.
func (*Ex) Stack ¶
func (e *Ex) Stack() StackTrace
Stack returns the stack provider. This is typically the runtime []uintptr or []string if restored after the fact.
func (*Ex) StackString ¶
StackString returns the stack trace as a string.
func (*Ex) WithMessagef ¶
WithMessagef sets the message based on a format and args, and returns the exception.
type Exception ¶
type Exception interface {
error
fmt.Formatter
json.Marshaler
WithClass(string) Exception
Class() string
WithMessagef(string, ...interface{}) Exception
Message() string
WithInner(error) Exception
Inner() error
WithStack(StackTrace) Exception
Stack() StackTrace
Decompose() map[string]interface{}
}
Exception is an exception.
func New ¶
func New(classArgs ...interface{}) Exception
New returns a new exception with a call stack.
func NewFromErr ¶
NewFromErr returns a new exception from an error.
type Frame ¶
type Frame uintptr
Frame represents a program counter inside a stack frame.
func (Frame) Format ¶
Format formats the frame according to the fmt.Formatter interface.
%s source file %d source line %n function name %v equivalent to %s:%d
Format accepts flags that alter the printing of some verbs, as follows:
%+s path of source file relative to the compile time GOPATH %+v equivalent to %+s:%d
type StackPointers ¶
type StackPointers []uintptr
StackPointers is stack of uintptr stack frames from innermost (newest) to outermost (oldest).
func (StackPointers) Format ¶
func (st StackPointers) Format(s fmt.State, verb rune)
Format formats the stack trace.
func (StackPointers) MarshalJSON ¶
func (st StackPointers) MarshalJSON() ([]byte, error)
MarshalJSON is a custom json marshaler.
func (StackPointers) Strings ¶
func (st StackPointers) Strings() []string
Strings dereferences the StackTrace as a string slice
type StackStrings ¶
type StackStrings []string
StackStrings represents a stack trace as string literals.
func (StackStrings) Format ¶
func (ss StackStrings) Format(s fmt.State, verb rune)
Format formats the stack trace.
func (StackStrings) MarshalJSON ¶
func (ss StackStrings) MarshalJSON() ([]byte, error)
MarshalJSON is a custom json marshaler.
func (StackStrings) Strings ¶
func (ss StackStrings) Strings() []string
Strings returns the stack strings as a string slice.
type StackTrace ¶
StackTrace is a stack trace provider.
Source Files