errx

Documentation

Overview

This package defines and implements an error interface that includes: definition of an error kind that can be referenced in error handlers; a chain of errors that are the causes of the current error; a stack trace. The stack trace is based on runtime/debug/Stack.

Index

• Variables
• func PanicLog(logger func(args ...interface{}))
• func PanicOnError(err error)
• func StackTraceOf(err error) string
• func TODO[T any](args ...string) T
• type Errx
  • func ErrxOf(r any) Errx
  • func NewErrx(cause error, rawMsg string, args ...any) Errx
• type Kind
  • func KindOf(err error) *Kind
  • func NewKind(name string, superKinds ...*Kind) *Kind
  • func (s *Kind) Decorate(cause Errx, rawMsg string, args ...any) Errx
  • func (s *Kind) IsSubKindOf(kind *Kind) bool
  • func (s *Kind) Make(cause error, rawMsg string, args ...any) Errx
  • func (s *Kind) SuperKinds() map[*Kind]struct{}

Variables

var DefaultKind = NewKind("Errx")

DefaultKind is used for on-the-fly construction of Errx instances.

Functions

func PanicLog

func PanicLog(logger func(args ...interface{}))

func PanicOnError

func PanicOnError(err error)

func StackTraceOf

func StackTraceOf(err error) string

StackTraceOf returns err.StackTrace() if err is of type Errx, an empty string otherwise.

func TODO

func TODO[T any](args ...string) T

This function is a placeholder for code to be implemented. It panics on execution, with an errx.Errx as the panic argument. It takes an optional string argument that is used as the message for the aforementioned error object. If a message is not provided, the default "missing implementation" is used.

Types

type Errx

type Errx interface {
	error

	// Kind returns the error's Kind
	Kind() *Kind

	// Cause returns the error's cause, which may be nil.
	// This method is named for consistency with Go's standard errors package.
	Unwrap() error

	// Args returns the arguments that are substituted into KindMsg().
	Args() []any

	// RawMsg returns the raw message for the error, i.e., without args substitution.
	RawMsg() string

	// Msg returns the error's message with arguments substituted.
	Msg() string

	// RecursiveMsg returns a message string that combines the error messages of all errors
	// in the error's cause chain (which includes the error itself).
	RecursiveMsg() string

	// ErrxChain returns the error followed by all its preceding causes of type Errx.
	ErrxChain() []Errx

	// CauseChain returns the error followed by all its preceding causes.
	CauseChain() []error

	// InnermostCause returns the innermost cause in the error's cause chain.
	InnermostCause() error

	// InnermostErrx returns the innermost cause of type Errx in the error's cause chain.
	InnermostErrx() Errx

	// StackTrace returns a stack trace from the point where the error was created.
	StackTrace() string

	// Customize changes the raw error message and arguments of the receiver.
	// Returns the modified receiver.
	Customize(rawMsg string, args ...any) Errx
}

Errx defines an error type with support for error kinds, a cause chain, recursive error message, and a stack trace.

func ErrxOf

func ErrxOf(r any) Errx

ErrxOf creates an Errx from r. If r is nil, nil is returned. If r is an Errx, r is returned. If r is an error, NewErrx is used to instantiate an Errx with r as its cause. Otherwise, NewErrx is used to instantiate an Errx with nil as the cause argument and r's string rendering as the msg argument.

func NewErrx

func NewErrx(cause error, rawMsg string, args ...any) Errx

NewErrx creates an Errx whose Kind is defined on-the-fly using msg.

type Kind

type Kind struct {
	// contains filtered or unexported fields
}

Kind encapsulates an error messag string (possibly with argument placeholders) and a list of direct super-kinds it is to be considered to be related to.

func KindOf

func KindOf(err error) *Kind

KindOf returns a pointer to the kind of an Errx or nil if err is not an Errx.

func NewKind

func NewKind(name string, superKinds ...*Kind) *Kind

NewKind instantiates a Kind.

func (*Kind) Decorate

func (s *Kind) Decorate(cause Errx, rawMsg string, args ...any) Errx

Decorate instantiates an Errx from a Kind pointer. The cause argument must be an Errx. The difference between Make and Decorate is that Make sets a new stack trace at the point of instantiation while Decorate effectively relies on the the stack trace provided by causes or its most recent cause which has a stack trace.

func (*Kind) IsSubKindOf

func (s *Kind) IsSubKindOf(kind *Kind) bool

func (*Kind) Make

func (s *Kind) Make(cause error, rawMsg string, args ...any) Errx

Make instantiates an Errx from a Kind pointer, creating a stack trace at the point of instantiation.

func (*Kind) SuperKinds

func (s *Kind) SuperKinds() map[*Kind]struct{}

SuperKinds returns the set of all super-kinds of the receiver, including the receiver itself.