exceptions

README

exceptions

Simple exceptions support for Go, using panic() and recover().

Go's panic(any) will unwind the stack one frame at a time until there is a matching call to recover(). This library calls the parameter passed to panic an exception, and provides simplified methods to catch those exceptions.

Examples

Catching any exception with Try

An exception in Go is what goes into the panic() call. The returned value (exception in the example) is of type any.

import . "github.com/gomlx/exceptions"

...
	exception := Try(func() { panic("cookies") })
	if exception != nil {
		fmt.Printf("Caught: %v\n", exception)
	}

It will print: Caught: cookies.

Throwing an exception with Panicf

We keep the Go word term for it, panic: one can simply use panic as usual, or use the provided Panicf, which converts the given text into an error+stack:

import . "github.com/gomlx/exceptions"

func MyRatio(myThing, total float64) float64 {
	if total == 0 {
		Panicf("MyRatio(%f, %f) has no things (0) to calculate a ratio from", myThing, total)
	}
	return myThing/total
}

Catching Typed Exceptions with TryCatch

Go panic() supports any value to be passed -- the value is what we interpret as an exception.

The generic TryCatch[E any] API allows a function to be called and an exception of the given type E to be caught. Any other exception types are not handled and continues to propagate up the stack as usual.

import . "github.com/gomlx/exceptions"

	var x ResultType
	err := TryCatch[error](func() { x = DoSomething() })
	if err != nil {
		// Handle error ...
	}

Documentation

Overview

Package exceptions provides helper functions to leverage Go's `panic`, `recover` and `defer` as an "exceptions" system.

The `panic`, `recover` and the added runtime type checking is slow when compared to simply returning errors. So it should be used where a little latency in case of errors is not an issue.

It defines `Try` and `TryCatch[E any]`.

Index

• func Panicf(format string, args ...any)
• func Try(fn func()) (exception any)
• func TryCatch[E any](fn func()) (exception E)

Functions

func Panicf

func Panicf(format string, args ...any)

Panicf is a shortcut to `panic(errors.Errorf(format, args...))`. It throws an error with a stack-trace and the formatted message.

func Try

func Try(fn func()) (exception any)

Try calls `fn` and return any exception (`panic`) that may occur.

Runtime panics are converted to an error with a stack-trace, to facilitate debugging.

Example:

var x ResultType
e := Try(func() { x = DoSomething() })
if e != nil {
	if eInt, ok := e.(int); ok {
		errorInt = e
	} else if err, ok := e.(err); ok {
		klog.Errorf("%v", e)
	} else {
		panic(e)
	}
}

func TryCatch

func TryCatch[E any](fn func()) (exception E)

TryCatch executes `fn` and in case of `panic`, it recovers if of the type `E`. For a `panic` of any other type, it simply re-throws the `panic`.

Runtime panics are converted to errors.Error, with a stack trace.

Example:

var x ResultType
err := TryCatch[error](func() { x = DoSomething() })
if err != nil {
	// Handle error ...
}