perrors

Documentation

Overview

Package perrors 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

perrors used to be called error116 becaue Rob Pike was going to put it into go1.16

© 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 Deferr(label string, errp *error, fn func(format string, a ...interface{})) (message string)
• func Error0(err 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 ErrorfPF(format string, a ...interface{}) (err error)
• func HasStack(err error) (hasStack bool)
• func Is(errp *error, format string, a ...interface{}) (isBad bool)
• func Is2(errp *error, e error, format string, a ...interface{}) (isBad bool)
• func Is2PF(errp *error, e error, format string, a ...interface{}) (isBad bool)
• func IsError[T error](err T) (isError bool)
• func IsPF(errp *error, format string, a ...interface{}) (isBad bool)
• func IsPanic(err error) (isPanic bool, stack pruntime.Stack, recoveryIndex, panicIndex int)
• func IsType(err error, pointerToErrorValue interface{}) (hadErrpType bool)
• func IsWarning(err error) (isWarning bool)
• func Long(err error) (s string)
• func LongShort(err error) (message string)
• func New(s string) (err error)
• func NewPF(s string) (err error)
• func Short(err error) (s string)
• func Stack(err error) (err2 error)
• func Stackn(err error, framesToSkip int) (err2 error)
• func TagErr(err error, tags ...string) (err2 error)
• func Warning(err error) (err2 error)
• type SupportsIs

Functions

func AddKeyValue

func AddKeyValue(err error, key, value string) (e error)

AddKeyValue attaches a string value to err

• values can be retrieved using 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

func AppendError(err error, err2 error) (e error)

AppendError associates an additional error with err.

• return value is nil if and only if both err and err2 are nil
• if either err or err2 is nil, return value is the non-nil argument
• if both err and err2 are non-nil, the return value is err with err2 associated
• associated error instances can be retrieved using:
• — perrors.AllErrors,
• — perros.ErrorList or
• — by rich error printing of perrors package: perrors.Long or
• — “%+v”

func Deferr

func Deferr(label string, errp *error, fn func(format string, a ...interface{})) (message string)

Deferr invokes a printing function for an error pointer

• label: message prepended. A colon and a space is appended to label.
• errp: pointer to error
• — if *errp contains an error it is printed in Short form
• — “label: Error message at error116.(*csTypeName).FuncName-chainstring_test.go:26”
• — if *errp is nil, “OK” is printed
• errp nil: message returned bnut not printed: “perrors.Deferr: errp nil”
• fn: optional printf function eg. parl.Log. If missing nothing is printed
• —
• deferrable and returns the message

func Error0

func Error0(err error) (e error)

Error0 returns the last error in err’s error chain or nil if err is nil

func ErrorData

func ErrorData(err error) (list []string, keyValues map[string]string)

ErrorData returns any embedded data values from err and its error chain as a list and map

• list contains values where key was empty, oldest first
• keyValues are string values associated with a key string, overwriting older values
• err list keyValues may be nil

func ErrorList

func ErrorList(err error) (errs []error)

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, length 1, 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

func Errorf(format string, a ...interface{}) (err error)

Errorf is similar to fmt.Errorf but ensures that the returned err has at least one stack trace associated

func ErrorfPF

func ErrorfPF(format string, a ...interface{}) (err error)

Errorf is similar to fmt.Errorf but ensures that the returned err has at least one stack trace associated

• prepends error message with package name and function identifiers
• “perrors NewPF s cannot be empty”

func HasStack

func HasStack(err error) (hasStack bool)

HasStack detects if the error chain already contains a stack trace

• hasStack: true if err is non-nil and contains a stack trace

func Is

func Is(errp *error, format string, a ...interface{}) (isBad bool)

Is returns true if *errp contains a non-nil error

• if return value is true and format is not empty string, *errp is updated with fmt.Errorf using format and a, typically including “%w” and an error
• if *errp is non-nil and does not have a stack, a stack is inserted into its error chain
• errp cannot be nil or panic

func Is2

func Is2(errp *error, e error, format string, a ...interface{}) (isBad bool)

Is2 is similar to Is but receives it error in e

• if errp and e both non-nil, e is appended to *errp

func Is2PF

func Is2PF(errp *error, e error, format string, a ...interface{}) (isBad bool)

Is2PF is similar to IsPF but receives it error in e

• if errp and e both non-nil, e is appended to *errp

func IsError

func IsError[T error](err T) (isError bool)

IsError determines if err represents error condition for all error implementations

• eg. unix.Errno that is uintptr

func IsPF

func IsPF(errp *error, format string, a ...interface{}) (isBad bool)

IsPF returns true if *errp contains a non-nil error

• package and function identifiers are prepended
• if return value is true and format is not empty string, *errp is updated with fmt.Errorf using format and a, typically including “%w” and an error
• if *errp is non-nil and does not have a stack, a stack is inserted into its error chain
• errp cannot be nil or panic

func IsPanic

func IsPanic(err error) (isPanic bool, stack pruntime.Stack, recoveryIndex, panicIndex int)

IsPanic determines if err is the result of a panic. Thread-safe

• isPanic is true if a panic was detected in the inner-most stack trace of err’s error chain
• err must have stack trace from perrors.ErrorfPF perrors.Stackn or similar function
• stack[recoveryIndex] is the code line of the deferred function containing recovery invocation
• stack[panicIndex] is the code line causing the panic
• perrors.Short displays the error message along with the code location raising panic
• perrors.Long displays all available information about the error

func IsType

func IsType(err error, pointerToErrorValue interface{}) (hadErrpType bool)

IsType determines if the chain of err contains an error of type target.

• IsType is different from errors.Is in that IsType matches the type of err, not its value.
• IsType is different from errors.Is in that it works for error implementations missing the Is() method.
• IsType uses reflection.

pointerToErrorValue argument is a pointer to an error implementation value, ie:

• if the target struct has pointer reciever, the argument type *targetStruct
• if the target struct has value receiver, the argument type targetStruct

func IsWarning

func IsWarning(err error) (isWarning bool)

IsWarning determines if an error has been flagged as a warning

• isWarning true if err was wrapped by Warning function

func Long

func Long(err error) (s string)

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 LongShort

func LongShort(err error) (message string)

LongShort picks output format

• no error: “OK”
• no panic: “error-message at runtime.gopanic:26”
• panic: long format with all stack traces and values
• associated errors are always printed

func New

func New(s string) (err error)

New is similar to errors.New but ensures that the returned error has at least one stack trace associated

• if s is empty “StackNew from …”

func NewPF

func NewPF(s string) (err error)

NewPF is similar to errors.New but ensures that the returned error has at least one stack trace associated

• if s is empty “StackNew from …”
• prepends error message with package name and function identifiers
• “perrors NewPF s cannot be empty”

func Short

func Short(err error) (s string)

perrors.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

func Stack(err error) (err2 error)

Stack ensures the err has a stack trace associated.

• err nil returns nil

func Stackn

func Stackn(err error, framesToSkip int) (err2 error)

Stackn always attaches a new stack trace to non-nil err

• framesToSkip: 0 is caller, larger skips stack frames

func TagErr

func TagErr(err error, tags ...string) (err2 error)

TagErr prepends err’s error message with tags

• “perrors NewPF tag1 tag2: s cannot be empty”
• err2 is enrued to have a stack trace from caller of TagErr

func Warning

func Warning(err error) (err2 error)

Warning indicates that err is a problem of less severity than error

• err: an error to be considered a warning
• err: nil: returns nil
• err2 is ensured to have a stack tgrace based on Warning caller
• Warning is detected using IsWarning

Types

type SupportsIs

type SupportsIs interface {
	error
	Is(target error) (isThisType bool)
}

SupportsIs is used for type assertions determining if an error value implements the Is() method, therefore supports errors.Is()