grr

README

grr

Grr provides easy, context-wrapped error handling in Go

Documentation

Overview

Package grr provides easy, context-wrapped error handling in Go.

Index

• Variables
• func Errorf(format string, a ...any) error
• func Ignore1[T any](v T, err error) T
• func Ignore2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)
• func Ignore3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)
• func Log(err error) error
• func Log1[T any](v T, err error) T
• func Log2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)
• func Log3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)
• func Must(err error)
• func Must1[T any](v T, err error) T
• func Must2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)
• func Must3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)
• func New(text string) error
• func Stack() []runtime.Frame
• func Test(t TestingT, err error) error
• func TestFatal(t TestingT, err error) error
• func Wrap(err error) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) String() string
  • func (e *Error) Unwrap() error
• type TestingT

Variables

var Debug = false

Debug is whether to put the program in debug mode and print the stack traces for errors.

Functions

func Errorf

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

Errorf returns a new error with the given format and arguments, wrapped with a stack trace via Wrap. The result guaranteed to be of type *Error. It is the grr equivalent of fmt.Errorf.

func Ignore1

func Ignore1[T any](v T, err error) T

Ignore1 ignores an error return value for a function returning a value and an error, allowing direct usage of the value. The intended usage is:

a := grr.Ignore1(MyFunc(v))

func Ignore2

func Ignore2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)

Ignore2 ignores an error return value for a function returning two values and an error, allowing direct usage of the values. The intended usage is:

a, b := grr.Ignore2(MyFunc(v))

func Ignore3

func Ignore3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

Ignore3 ignores an error return value for a function returning three values and an error, allowing direct usage of the values. The intended usage is:

a, b, c := grr.Ignore3(MyFunc(v))

func Log

func Log(err error) error

Log takes the given error and logs it if it is non-nil. The intended usage is:

grr.Log(MyFunc(v))
// or
return grr.Log(MyFunc(v))

func Log1

func Log1[T any](v T, err error) T

Log1 takes the given value and error and returns the value if the error is nil, and logs the error and returns a zero value if the error is non-nil. The intended usage is:

a := grr.Log1(MyFunc(v))

func Log2

func Log2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)

Log2 takes the given two values and error and returns the values if the error is nil, and logs the error and returns zero values if the error is non-nil. The intended usage is:

a, b := grr.Log2(MyFunc(v))

func Log3

func Log3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

Log3 takes the given three values and error and returns the values if the error is nil, and logs the error and returns zero values if the error is non-nil. The intended usage is:

a, b, c := grr.Log3(MyFunc(v))

func Must

func Must(err error)

Must takes the given error and panics if it is non-nil. The intended usage is:

grr.Must(MyFunc(v))

func Must1

func Must1[T any](v T, err error) T

Must1 takes the given value and error and returns the value if the error is nil, and panics if the error is non-nil. The intended usage is:

a := grr.Must1(MyFunc(v))

func Must2

func Must2[T1, T2 any](v1 T1, v2 T2, err error) (T1, T2)

Must2 takes the given two values and error and returns the values if the error is nil, and panics if the error is non-nil. The intended usage is:

a, b := grr.Must2(MyFunc(v))

func Must3

func Must3[T1, T2, T3 any](v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

Must3 takes the given three values and error and returns the values if the error is nil, and panics if the error is non-nil. The intended usage is:

a, b, c := grr.Must3(MyFunc(v))

func New

func New(text string) error

New returns a new error with the given text, wrapped with a stack trace via Wrap. The result guaranteed to be of type *Error. It is the grr equivalent of errors.New.

func Stack

func Stack() []runtime.Frame

Stack returns the stack trace up to this caller as a slice of frames.

func Test

func Test(t TestingT, err error) error

Test takes the given error and errors the test it if it is non-nil. The intended usage is:

grr.Test(t, MyFunc(v))

func TestFatal

func TestFatal(t TestingT, err error) error

TestFatal takes the given error and fatally errors the test it if it is non-nil. The intended usage is:

grr.TestFatal(t, MyFunc(v))

func Wrap

func Wrap(err error) error

Wrap wraps the given error into an error object with a stack trace. It returns nil if the given error is nil. If it is not nil, the result is guaranteed to be of type *Error.

Types

type Error

type Error struct {
	Base  error
	Stack []runtime.Frame
}

Error is the main type of grr and represents an error with a base error and a stack trace.

func (*Error) Error

func (e *Error) Error() string

Error returns the error as a string, wrapping the string of the base error with the stack trace.

func (*Error) String

func (e *Error) String() string

String returns the error as a string, wrapping the string of the base error with the stack trace.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying base error of the Error.

type TestingT

type TestingT interface {
	Error(args ...any)
	Fatal(args ...any)

	// Helper marks the calling function as a test helper function.
	Helper()
}

TestingT is an interface wrapper around *testing.T