oops

README

oops

Oops implements the batteries that are missing from errors:

• Stack traces: attach a stack trace to any error
• Chaining: combining multiple errors into a single stack of errors (as you might want when handling the errors from disposing resources like [file_close][file.Close()])
• Namespacing: create an error factory that prefixes errors with a given name
• Shadowing: hide the exact error behind a package level error (as you might want when trying to stabilize your API's supported errors)

---

Documentation

Overview

Package oops implements the batteries missing from Package errors.

Index

• Variables
• func Chain(errs ...error) error
• func ChainP(err *error, errs ...error)
• func ErrorIndent(err error, format, indent string) []string
• func ErrorLines(err error, format string) []string
• func ErrorMarshalJSON(e error) (bs []byte, err error)
• func New(format string, a ...any) error
• func Shadow(hidden, err error) error
• func ShadowF(hidden *error, err error) func()
• func ShadowP(hidden *error, err error)
• type Capturer
• type ChainError
  • func (ce ChainError) Error() string
  • func (ce ChainError) Format(f fmt.State, verb rune)
  • func (ce ChainError) Unwrap() error
• type Namespace
  • func (n Namespace) New(err error) *NamespaceError
  • func (n Namespace) NewP(err *error)
• type NamespaceError
  • func (ne *NamespaceError) Error() string
  • func (ne *NamespaceError) Format(f fmt.State, verb rune)
  • func (ne *NamespaceError) MarshalJSON() (bs []byte, err error)
  • func (ne *NamespaceError) Unwrap() error
• type ShadowError
  • func (se *ShadowError) Error() string
  • func (se *ShadowError) Format(f fmt.State, verb rune)
  • func (se *ShadowError) MarshalJSON() (bs []byte, err error)
  • func (se *ShadowError) Unwrap() error
• type TraceError
  • func Trace(err error) *TraceError
  • func TraceN(err error, skip int) *TraceError
  • func TraceWithOptions(err error, options TraceOptions) *TraceError
  • func (te *TraceError) Error() string
  • func (te *TraceError) Format(f fmt.State, verb rune)
  • func (te *TraceError) MarshalJSON() (bs []byte, err error)
  • func (te *TraceError) Unwrap() error
• type TraceOptions

Variables

var Capture = func(_ error, skip int) (data any) {
	callers := make([]uintptr, 10)
	n := runtime.Callers(skip, callers)
	callers = callers[:n]

	cfs := runtime.CallersFrames(callers)

	frames := make([]runtime.Frame, 0, n)
	for {
		frame, more := cfs.Next()
		if !more {
			break
		}

		frames = append(frames, frame)
	}

	return frames
}

Capture is used to capture trace data. By default it is configured to capture stack frames.

Functions

func Chain

func Chain(errs ...error) error

Chain combines errors into a chain of errors. nil errors are removed.

func ChainP

func ChainP(err *error, errs ...error)

ChainP combines errors into a chain of errors. nil errors are removed.

func ErrorIndent

func ErrorIndent(err error, format, indent string) []string

ErrorIndent returns the error's string prefixed by indent. The first line is not indented.

func ErrorLines

func ErrorLines(err error, format string) []string

ErrorLines returns the error's string in the given format as an array of lines.

func ErrorMarshalJSON

func ErrorMarshalJSON(e error) (bs []byte, err error)

ErrorMarshalJSON uses e's json.Marshaler if it implements one otherwise it uses the output from e.Error() (marshalled into a JSON string).

func New

func New(format string, a ...any) error

New returns a new error from fmt.Errorf with a stack trace.

func Shadow

func Shadow(hidden, err error) error

Shadow hides internal errors with another error.

func ShadowF

func ShadowF(hidden *error, err error) func()

ShadowF returns a function that shadows hidden in place.

func ShadowP

func ShadowP(hidden *error, err error)

ShadowP replaces hidden with error.

Types

type Capturer

type Capturer interface {
	Capture(err error, skip int) (data any)
}

Capturer provides a method for capturing trace data.

type ChainError

type ChainError []error

ChainError is a list of errors oldest to newest.

func (ChainError) Error

func (ce ChainError) Error() string

func (ChainError) Format

func (ce ChainError) Format(f fmt.State, verb rune)

Format implements fmt.Format.

func (ChainError) Unwrap

func (ce ChainError) Unwrap() error

type Namespace

type Namespace struct {
	Name string
}

Namespace provides a name prefix for new errors.

func (Namespace) New

func (n Namespace) New(err error) *NamespaceError

New returns the error wrapped in the namespace.

func (Namespace) NewP

func (n Namespace) NewP(err *error)

NewP replaces err with a namespaced error.

type NamespaceError

type NamespaceError struct {
	Name string
	Err  error
}

NamespaceError prefixes errors with the given namespace.

func (*NamespaceError) Error

func (ne *NamespaceError) Error() string

func (*NamespaceError) Format

func (ne *NamespaceError) Format(f fmt.State, verb rune)

Format implements fmt.Format.

func (*NamespaceError) MarshalJSON

func (ne *NamespaceError) MarshalJSON() (bs []byte, err error)

MarshalJSON implements json.Marshaler.

func (*NamespaceError) Unwrap

func (ne *NamespaceError) Unwrap() error

type ShadowError

type ShadowError struct {
	Hidden error `json:"hidden"`
	Err    error `json:"err"`
}

ShadowError is an error with a hidden error inside.

func (*ShadowError) Error

func (se *ShadowError) Error() string

func (*ShadowError) Format

func (se *ShadowError) Format(f fmt.State, verb rune)

Format implements fmt.Format.

func (*ShadowError) MarshalJSON

func (se *ShadowError) MarshalJSON() (bs []byte, err error)

MarshalJSON implements json.Marshaler.

func (*ShadowError) Unwrap

func (se *ShadowError) Unwrap() error

type TraceError

type TraceError struct {
	Data any
	Err  error
}

TraceError is an error with trace data.

func Trace

func Trace(err error) *TraceError

Trace captures a trace and combines it with err. Tracer is use to capture the trace data and 2 levels are skipped.

func TraceN

func TraceN(err error, skip int) *TraceError

TraceN captures a trace and combines it with err. Capturer is use to capture the trace data with skipped levels.

func TraceWithOptions

func TraceWithOptions(err error, options TraceOptions) *TraceError

TraceWithOptions captures a trace using the given options.

func (*TraceError) Error

func (te *TraceError) Error() string

Error implements error.

func (*TraceError) Format

func (te *TraceError) Format(f fmt.State, verb rune)

Format implements fmt.Format.

func (*TraceError) MarshalJSON

func (te *TraceError) MarshalJSON() (bs []byte, err error)

MarshalJSON implements json.Marshaler.

func (*TraceError) Unwrap

func (te *TraceError) Unwrap() error

Error implements errors.Unwraper.

type TraceOptions

type TraceOptions struct {
	// Skip the given number of levels of tracing. Default is 0.
	Skip int

	// Capturer controls the specific capturer implementation to use. If
	// not set, then the package level Capture will be used.
	Capturer Capturer
}

TraceOptions allows setting specific options for the trace.