oops

package module
v0.0.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 23, 2023 License: MIT Imports: 6 Imported by: 1

README

oops

Go Reference Go Report Card

Oops implements the batteries that are missing from the errors package:

  • 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 that are missing from the errors package.

Index

Examples

Constants

View Source 
const TraceSkipInternal = 7

TraceSkipInternal is the number of frames created by internal oops calls. This is the number of frames to skip if you would like to only include frames up til the site where TraceN is called.

Variables

View Source 
var CaptureRuntimeFramesChunk = 64

CaptureRuntimeFramesChunk is the initial and additional amount of frames gathered in CaptureRuntimeFrames. When there are more than this many frames to capture the frame buffer will be reallocated with this much additional space (repeating until all frames are able to be captured).

Functions

func CaptureRuntimeFrames added in v0.0.2 

func CaptureRuntimeFrames(_ error, skip int) []runtime.Frame

CaptureRuntimeFrames returns the captured stack as []runtime.Frame.

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

Example 
package main

import (
	"fmt"

	"github.com/calebcase/oops"
)

func main() {
	a := func() error {
		return oops.New("bad stuff")
	}

	b := func() error {
		return a()
	}

	c := func() error {
		return b()
	}

	err := c()

	fmt.Printf("error: %v\n", err)
}

Output:

error: bad stuff
Example (Details) 
package main

import (
	"fmt"

	"github.com/calebcase/oops"
)

func main() {
	a := func() error {
		return oops.New("bad stuff")
	}

	b := func() error {
		return a()
	}

	c := func() error {
		return b()
	}

	err := c()

	fmt.Printf("error: %+v\n", err)
}

Output:

func SetDefaultCapturer added in v0.0.2 

func SetDefaultCapturer(c Capturer)

SetDefaultCapturer changes the default trace capturer used by calls to Trace, TraceN, and TraceWithOptions. The default capturer creates a capture using CaptureFrames.

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.

func Trace 

func Trace(err error) error

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

func TraceN 

func TraceN(err error, skip int) error

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) error

TraceWithOptions captures a trace using the given options.

func Verbose added in v0.0.10 

func Verbose(err error) error

Verbose wraps an error making its string output verbose ("%+v").

Types

type CaptureFunc added in v0.0.2 

type CaptureFunc[T any] func(error, int) T

CaptureFunc defines a Capturer that calls the given function to generate the capture.

func (CaptureFunc[T]) Capture added in v0.0.2 

func (cf CaptureFunc[T]) Capture(err error, skip int) any

Capture implements Capturer.

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) As added in v0.0.6 

func (ce ChainError) As(target any) bool

As implements the implied interface for errors.As.

func (ChainError) Error 

func (ce ChainError) Error() string

Error implements the implied interface for error.

func (ChainError) Format 

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

Format implements fmt.Format.

func (ChainError) Is added in v0.0.6 

func (ce ChainError) Is(err error) bool

Is implements the implied interface for errors.Is.

func (ChainError) Unwrap 

func (ce ChainError) Unwrap() error

Unwrap implements the implied interface for errors.Unwrap.

type Frames added in v0.0.2 

type Frames []runtime.Frame

Frames wraps []runtime.Frame to provide a custom stringer.

func CaptureFrames added in v0.0.2 

func CaptureFrames(err error, skip int) (data Frames)

CaptureFrames returns the captured stack as Frames.

func (Frames) String added in v0.0.2 

func (fs Frames) String() string

String returns the frames formatted as an numbered intended array of frames.

type Namespace 

type Namespace string

Namespace provides a name prefix for new errors.

func (Namespace) Chain added in v0.0.8 

func (n Namespace) Chain(errs ...error) error

func (Namespace) ChainP added in v0.0.8 

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

func (Namespace) New 

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

func (Namespace) Shadow added in v0.0.8 

func (n Namespace) Shadow(hidden, err error) error

func (Namespace) ShadowF added in v0.0.8 

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

func (Namespace) ShadowP added in v0.0.8 

func (n Namespace) ShadowP(hidden *error, err error)

func (Namespace) Trace added in v0.0.8 

func (n Namespace) Trace(err error) error

func (Namespace) TraceN added in v0.0.8 

func (n Namespace) TraceN(err error, skip int) error

func (Namespace) TraceWithOptions added in v0.0.8 

func (n Namespace) TraceWithOptions(err error, options TraceOptions) error

func (Namespace) Wrap added in v0.0.8 

func (n Namespace) Wrap(err error) error

Wrap returns the error wrapped in the namespace.

func (Namespace) WrapP added in v0.0.8 

func (n Namespace) WrapP(err *error)

WrapP replaces the error with one wrapped in the namespace.

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 Namespacer added in v0.0.8 

type Namespacer interface {
	Wrap(err error) error
	WrapP(err *error)

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

	Trace(err error) error
	TraceN(err error, skip int) error
	TraceWithOptions(err error, options TraceOptions) error

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

	Shadow(hidden, err error) error
	ShadowP(hidden *error, err error)
	ShadowF(hidden *error, err error) func()
}

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 (*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

Unwrap implements the implied interface for errors.Unwrap.

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.

type VerboseError added in v0.0.10 

type VerboseError struct {
	Err error
}

VerboseError is an error that uses %+v for detailed formatting.

func (*VerboseError) Error added in v0.0.10 

func (ve *VerboseError) Error() string

Error implements error.

func (*VerboseError) Unwrap added in v0.0.10 

func (ve *VerboseError) Unwrap() error

Unwrap implements the implied interface for errors.Unwrap.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.