sherlock

README

sherlock

A simple package to tidy up Go's troublesome error handling.

Documentation

Overview

Package sherlock helps tidy up go code by reducing the substantial number of "if err != nil" checks that are usually performed on code even in cases where errors are unexpected. Instead of propagating error return values all the way up the stack, sherlock can unwind the stack by using panic. An appropriately placed Catch can be used to manage thrown errors higher up in the stack.

A typical use for sherlock will have exported package functions return errors as is convention, but they will also contain a CatchAll, allowing unexported functions to do away with this practice.

func MyFunction() error {
	var err error
	func() {
		defer sherlock.CatchAll(&err)
		// function logic
	}()
	return err
}

Written by Alan Murtagh

Index

• func Assert(condition bool, err error)
• func Catch(err error, fn func())
• func CatchAll(err *error)
• func Check(args ...interface{})
• func Throw(err error)

Functions

func Assert

func Assert(condition bool, err error)

Assert is used as a quick way to enforce contracts and to return custom errors when a situation is possible but not intended to be recoverable. If the condition is false, the provided error is thrown.

func Catch

func Catch(err error, fn func())

Catch halts a sherlock panic and checks if the thrown error is the same error provided as an argument. If the errors match then the provided function is executed and the panic is recovered. If the errors do not match then the error is rethrown. Errors are equal only if they have the same address.

func CatchAll

func CatchAll(err *error)

CatchAll halts a sherlock panic and fills the provided error pointer with the error that was thrown.

Sherlock can only catch sherlock thrown panics, and will rethrow a non-sherlock panic. This behaviour can result in final stack traces being difficult to use, but it is assumed that any non-sherlock panic is a bug, and so sherlock will dump a stacktrace into stderr.

Sherlock can also only catch panics thrown within the same package. It is good practice to not let panics unwind beyond the boundaries of a package, and so this is considered a bug by sherlock.

func Check

func Check(args ...interface{})

Check takes an arbitrary number of arguments and checks only the final one. If the final argument is of type error and is non nil, it is thrown as a sherlock panic.

func Throw

func Throw(err error)

Throw simply throws the provided error as a sherlock panic.