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

• Constants
• Variables
• func Errorf(format string, a ...any) error
• 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 Log4[T1, T2, T3, T4 any](v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)
• 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 Must4[T1, T2, T3, T4 any](v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)
• func New(text string) error
• func Stack() []runtime.Frame
• func Test(t TestingT, err error) error
• func Test1[T any](t TestingT, v T, err error) T
• func Test2[T1, T2 any](t TestingT, v1 T1, v2 T2, err error) (T1, T2)
• func Test3[T1, T2, T3 any](t TestingT, v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)
• func Test4[T1, T2, T3, T4 any](t TestingT, v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)
• func Wrap(err error) error
• type Error
  • func (e *Error) Error() string
  • func (e *Error) String() string
  • func (e *Error) Unwrap() error
• type TestingT

Constants

const (
	// Version is the version of this package being used
	Version = "v0.0.12"
	// GitCommit is the commit just before the latest version commit
	GitCommit = "150d9c2"
	// VersionDate is the date-time of the latest version commit in UTC (in the format 'YYYY-MM-DD HH:MM', which is the Go format '2006-01-02 15:04')
	VersionDate = "2023-12-26 23:20"
)

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

func Log4[T1, T2, T3, T4 any](v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)

Log4 takes the given four 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, d := grr.Log4(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 Must4

func Must4[T1, T2, T3, T4 any](v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)

Must4 takes the given four 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, d := grr.Must4(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 Test1

func Test1[T any](t TestingT, v T, err error) T

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

a := grr.Test1(t, MyFunc(v))

func Test2

func Test2[T1, T2 any](t TestingT, v1 T1, v2 T2, err error) (T1, T2)

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

a, b := grr.Test2(t, MyFunc(v))

func Test3

func Test3[T1, T2, T3 any](t TestingT, v1 T1, v2 T2, v3 T3, err error) (T1, T2, T3)

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

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

func Test4

func Test4[T1, T2, T3, T4 any](t TestingT, v1 T1, v2 T2, v3 T3, v4 T4, err error) (T1, T2, T3, T4)

Test4 takes the given four values and error and returns the values if the error is nil, and errors the test and returns zero values if the error is non-nil. The intended usage is:

a, b, c, d := grr.Test4(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)
}

TestingT is an interface wrapper around *testing.T