README
¶
exception
This is a simple library for wrapping an error with a stack trace.
Key Concepts
An exception is an error with additional context; message and most importantly, the stack trace at creation.
Concepts:
Class: A grouping error; you should be able to test if exceptions are similar by comparing the exception classes. When an exception is created from an error, the class is set to the original error.Message: Additional context that is variable, that would otherwise break equatibility with exceptions. You should put extra descriptive information in the message.Inner: A causing exception or error; if you have to chan multiple errors together as a larger grouped exception chain, useWithInner(...).StackTrace: A stack of function pointer / frames giving important context to where an exception was created.
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. If you'd like to add variable context to an exception, you can use WithMessagef(...):
If we want to wrap an existing golang error all we have to do is call New on that error.
file, err := os.ReadFile("my_file.txt")
if err != nil {
return exception.New(err)
}
If we want to add an inner exception, i.e. a causing exception, we can just add it with .WithInner(...)
file, err := os.ReadFile("my_file.txt")
if err != nil {
return exception.New("problems reading the config").WithInner(err)
}
A couple properties of New:
- It will return nil if the input
classis nil. - It will not modify an error that is actually an exception, it will simply return it untouched.
- It will create a stack trace for the class if it is not nil, and assign the class from the existing error.
Formatted Output
If we run fmt.Printf("%+v", exception.New("this is a sample error")) we will get the following output (assuming we're running the statement in an http server somewhere):
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()
Documentation
¶
Overview ¶
Package exception adds the ability to wrap errors with stack traces, structured error classes and free form descriptive messages. Most packages in go-sdk return exceptions instead of strict string errors.
Index ¶
- func ErrClass(err interface{}) string
- func ErrMessage(err interface{}) string
- func GetStackTrace() string
- func Inner(err interface{}) error
- func Is(err interface{}, cause error) bool
- type Class
- type Ex
- func (e *Ex) Class() error
- 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) WithClass(class error) Exception
- func (e *Ex) WithInner(err error) Exception
- func (e *Ex) WithMessage(message string) 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 ErrClass ¶
func ErrClass(err interface{}) string
ErrClass returns the exception class or the error message. This depends on if the err is itself an exception or not.
func ErrMessage ¶
func ErrMessage(err interface{}) string
ErrMessage returns the exception message. This depends on if the err is itself an exception or not. If it is not an exception, this will return empty string.
func GetStackTrace ¶
func GetStackTrace() string
GetStackTrace is a utility method to get the current stack trace at call time.
Types ¶
type Class ¶
type Class string
Class is a string wrapper that implements `error`. Use this to implement constant exception causes.
func (Class) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
type Ex ¶
type Ex struct {
// contains filtered or unexported fields
}
Ex is an error with a stack trace. It also can have an optional cause, it implements `Exception`
func (*Ex) Class ¶
Class returns the exception class. This error should be equatable, that is, you should be able to use it to test if an error is a similar class to another error.
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) WithMessage ¶
WithMessage sets the exception message.
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(error) Exception
Class() error
WithMessage(string) Exception
WithMessagef(string, ...interface{}) Exception
Message() string
WithInner(error) Exception
Inner() error
WithStack(StackTrace) Exception
Stack() StackTrace
Decompose() map[string]interface{}
}
Exception is an exception.
type Frame ¶
type Frame uintptr
Frame represents a program counter inside a stack frame.
func (Frame) File ¶
File returns the full path to the file that contains the function for this Frame's pc.
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) String ¶
func (st StackPointers) String() string
String returns a single string representation of the stack pointers.
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) String ¶
func (ss StackStrings) String() string
String returns a single string representation of the stack pointers.
func (StackStrings) Strings ¶
func (ss StackStrings) Strings() []string
Strings returns the stack strings as a string slice.
Source Files