errs

Documentation

Overview

Package errs implements a detailed error object that provides stack traces with source locations, along with nested causes, if any.

Index

• func Recovery(handler RecoveryHandler)
• func Wrap(cause error) error
• type Causer
• type Error
  • func Append(err error, errs ...error) *Error
  • func New(message string) *Error
  • func NewWithCause(message string, cause error) *Error
  • func NewWithCausef(cause error, format string, v ...any) *Error
  • func Newf(format string, v ...any) *Error
  • func WrapTyped(cause error) *Error
  • func (d *Error) Count() int
  • func (d *Error) Detail(trimRuntime bool) string
  • func (d Error) Error() string
  • func (d *Error) ErrorOrNil() error
  • func (d *Error) Format(state fmt.State, verb rune)
  • func (d *Error) Message() string
  • func (d *Error) RawStackTrace() []uintptr
  • func (d *Error) StackTrace(trimRuntime bool) string
  • func (d *Error) Unwrap() error
  • func (d *Error) WrappedErrors() []error
• type ErrorWrapper
• type RecoveryHandler
• type StackError

Examples

• Error

Functions

func Recovery

func Recovery(handler RecoveryHandler)

Recovery provides an easy way to run code that may panic. 'handler' will be called with the panic turned into an error. Pass in nil to silently ignore any panic.

Typical usage:

func runSomeCode(handler errs.RecoveryHandler) {
    defer errs.Recovery(handler)
    // ... run the code here ...
}

func Wrap

func Wrap(cause error) error

Wrap an error and turn it into a detailed error. If error is already a detailed error or nil, it will be returned as-is.

Types

type Causer

type Causer interface {
	Cause() error
}

Causer defines the interface for determining the error the caused an error.

type Error

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

Error holds the detailed error message.

Example

package main

import (
	"fmt"

	"github.com/richardwilkes/toolbox/errs"
)

func main() {
	var bad *int
	func() int {
		defer func() {
			if r := recover(); r != nil {
				if err, ok := r.(error); ok {
					fmt.Println(errs.NewWithCause("Caught panic", err))
				}
			}
		}()
		return *bad // trigger a panic due to a nil pointer dereference
	}()
}

func Append

func Append(err error, errs ...error) *Error

Append one or more errors to an existing error. err may be nil.

func New

func New(message string) *Error

New creates a new detailed error with the 'message'.

func NewWithCause

func NewWithCause(message string, cause error) *Error

NewWithCause creates a new detailed error with the 'message' and underlying 'cause'.

func NewWithCausef

func NewWithCausef(cause error, format string, v ...any) *Error

NewWithCausef creates a new detailed error with an underlying 'cause' and using fmt.Sprintf() to format the message.

func Newf

func Newf(format string, v ...any) *Error

Newf creates a new detailed error using fmt.Sprintf() to format the message.

func WrapTyped

func WrapTyped(cause error) *Error

WrapTyped wraps an error and turns it into a detailed error. If error is already a detailed error or nil, it will be returned as-is. This method returns the error as an *Error. Use Wrap() to receive a generic error.

func (*Error) Count

func (d *Error) Count() int

Count returns the number of contained errors, not including causes.

func (*Error) Detail

func (d *Error) Detail(trimRuntime bool) string

Detail returns the fully detailed error message, which includes the primary message, the call stack, and potentially one or more chained causes.

func (Error) Error

func (d Error) Error() string

Error implements the error interface.

func (*Error) ErrorOrNil

func (d *Error) ErrorOrNil() error

ErrorOrNil returns an error interface if this Error represents one or more errors, or nil if it is empty.

func (*Error) Format

func (d *Error) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

Supported formats:

• "%s" Just the message
• "%q" Just the message, but quoted
• "%v" The message plus a stack trace, trimmed of golang runtime calls
• "%+v" The message plus a stack trace

func (*Error) Message

func (d *Error) Message() string

Message returns the message attached to this error.

func (*Error) RawStackTrace

func (d *Error) RawStackTrace() []uintptr

RawStackTrace returns the raw call stack pointers.

func (*Error) StackTrace

func (d *Error) StackTrace(trimRuntime bool) string

StackTrace returns just the stack trace portion of the message.

func (*Error) Unwrap

func (d *Error) Unwrap() error

Unwrap implements errors.Unwrap and returns the underlying cause, if any.

func (*Error) WrappedErrors

func (d *Error) WrappedErrors() []error

WrappedErrors returns the contained errors.

type ErrorWrapper

type ErrorWrapper interface {
	error
	Count() int
	WrappedErrors() []error
}

ErrorWrapper contains methods for interacting with the wrapped errors.

type RecoveryHandler

type RecoveryHandler func(error)

RecoveryHandler defines the callback used when panics occur with Recovery.

type StackError

type StackError interface {
	error
	Message() string
	Detail(trimRuntime bool) string
	StackTrace(trimRuntime bool) string
}

StackError contains methods with the stack trace and message.