Documentation
¶
Overview ¶
Package error116 enrichens error values with string data, stack traces, associated errors, less severe warnings, thread-safe containers and comprehensive error string representations.
Creating errors with stack traces:
err := error116.New("error message") // adds a stacktrace contained inside of err
err = error116.Errorf("Some text: '%w'", err) // adds a stacktrace if err does not already have it
err = error116.Stackn(err, 0) // adds a stack trace even if err already has it
Enriching errors:
err = error116.AddKeyValue(err, "record", "123") // adds a key-value string, last key wins err = error116.AddKeyValue(err, "", "2022-03-19 11:10:00") // adds a string to a list, oldest first
Encapsulating associated errors allowing for a single error value to contain multiple errors:
err = error116.AppendError(err, err2) // err2 is inside of err, can be printed and retrieved fn := error116.Errp(&err) // fn(error) can be repeatedly invoked, aggregating errors in err error116.ParlError.AddError(err) // thread-safe error encapsulation
Marking errors as less severe:
warning := error116.Warning(err) // warning should not terminate the thread error116.IsWarning(err) // Determine severity of an error value
Printing rich errors:
error116.Long(err) → error-message → github.com/haraldrudell/parl/error116.(*csTypeName).FuncName → /opt/sw/privates/parl/error116/chainstring_test.go:26 → runtime.goexit → /opt/homebrew/Cellar/go/1.17.8/libexec/src/runtime/asm_arm64.s:1133 → record: 1234 → Other error: Close failed error116.Short(err) → error-message at error116.(*csTypeName).FuncName-chainstring_test.go:26 fmt.Println(err) → error-message
Can be used with Printf, but only works if last error in chain is from error116:
fmt.Printf("err: %+v", err) // same as Long()
fmt.Printf("err: %-v", err) // save as Short()
Is compatible:
fmt.Println(err) // no change
fmt.Printf("err: %v", err) // no change
err.Error() // no change
fmt.Printf("err: %s", err) // no change
fmt.Printf("err: %q", err) // no change
© 2020–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
Index ¶
- func AddKeyValue(err error, key, value string) (e error)
- func AppendError(err error, err2 error) (e error)
- func ErrorData(err error) (list []string, keyValues map[string]string)
- func ErrorList(err error) (errs []error)
- func Errorf(format string, a ...interface{}) (err error)
- func Errp(errp *error) func(e error)
- func HasStack(err error) (hasStack bool)
- func IsWarning(err error) (isWarning bool)
- func Long(err error) string
- func New(s string) error
- func PackFunc() (packageDotFunction string)
- func Short(err error) string
- func Stack(err error) (err2 error)
- func Stackn(err error, framesToSkip int) (err2 error)
- func Warning(err error) error
- type ParlError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddKeyValue ¶
error116.AddKeyValue attaches a string value to err. The values can be trrioeved using error116.ErrorData(). if key is non-empty valiue is returned in a map where last key wins. if key is empty, valuse is returned in s string slice. err can be nil.
func AppendError ¶
error116.AppendError associates an additional error with err. err and err2 can be nil. Associated error instances can be retrieved using error116.AllErrors, error116.ErrorList or by printing using rich error printing of the error116 package. TODO 220319 fill in printing
func ErrorData ¶
error116.ErrorData get possible string values associated with an error chain. list is a list of string values that were stored with an empty key, oldest first. keyValues are string values associated with a key string, newest key wins. err can be nil
func ErrorList ¶
error116.ErrorList returns all error instances from a possible error chain. If err is nil an empty slice is returned. If err does not have associated errors, a slice of err is returned. otherwise, the first error of the returned slice is err followed by other errors oldest first. Cyclic error values are dropped
func Errorf ¶
error116.Errorf is similar to fmt.Errorf but ensures that the returned err has at least one stack trace associated
func Errp ¶
error116.Errp returns a function that updates an an error pointer value with additional associated errors on subsequent invocations. It is intended to be used with parl.Recover(). for a thread-safe version, use error116.ParlError
func IsWarning ¶
error116.IsWarning determines if an error has been flagged as a warning. error116.Warning() flags an error to be of warning level
func Long ¶
error116.Long() gets a comprehensive string representation similar to printf %+v and LongFormat. ShortFormat does not print stack traces, data and associated errors. Long() prints full stack traces, string key-value and list values for both the error chain of err, and associated errors and their chains
error-message
github.com/haraldrudell/parl/error116.(*csTypeName).FuncName
/opt/sw/privates/parl/error116/chainstring_test.go:26
runtime.goexit
/opt/homebrew/Cellar/go/1.17.8/libexec/src/runtime/asm_arm64.s:1133
func New ¶
error116.New is similar to errors.New but ensures that the returned error has at least one stack trace associated
func PackFunc ¶
func PackFunc() (packageDotFunction string)
error116.PackFunc returns the package name and function name of the caller:
error116.FuncName
func Short ¶
error116.Short gets a one-line location string similar to printf %-v and ShortFormat. Short() does not print stack traces, data and associated errors. Short() does print a one-liner of the error message and a brief code location:
error-message at error116.(*csTypeName).FuncName-chainstring_test.go:26
func Stack ¶
error116.Stack ensures the err has a stack trace associated. err can be nil in which nil is returned
Types ¶
type ParlError ¶
type ParlError struct {
errorglue.SendNb // non-blocking channel for sending errors
// contains filtered or unexported fields
}
ParlError is a thread-safe error container that can optionally send errors non-blocking on a channel.
func NewParlError ¶
NewParlError provides a thread-safe error container that can optionally send incoming errors non-blocking on a channel.
If a channel is not used, a zero-value works:
var err error116.ParlError … return err
When using a channel, The error channel is closed by Shutdown():
errCh := make(chan error)
err := NewParlError(errCh)
…
err.Shutdown()
…
if err, ok := <- errCh; !ok {
// errs was shutdown
A shutdown ParlError is still usable, but will no longer send errors
func (*ParlError) AddError ¶
AddError stores additional errors in the container. Thread-safe. Returns the current state. For a non-thread-safe version, use error116.Errp
func (*ParlError) AddErrorProc ¶
AddErrorProc stores additional errors in the container It is thread-safe and has a no-return-value signature. For a non-thread-safe version, use error116.Errp
func (*ParlError) Error ¶
Error() makes ParlError behave like an error. Error is thread-safe unlike in most other Error implementations. Because code will check if ParlError is nil, which it mostly isn’t, and then invoke .Error(), it may be that Error is invoked when the error field is nil. For those situations, return “<nil>” like fmt.Print might do
Source Files