calmly

README

A Go package for handling of runtime panics

 

Package calmly implements convenient runtime panic recovery and handling in Go.

Project Status

v1.0.1 Stable: Guaranteed no breaking changes to the API in future v1.x releases. Probably safe to use in production, though provided on "AS IS" basis.

This package is being actively maintained. If you encounter any problems or have any suggestions for improvement, please open an issue. Pull requests are welcome.

Overview

When a panic condition needs to be handled by the program (rather than crashing it), wrap the code that can trigger such condition in a Try, which allows you to Catch the panic for further processing.

The Outcome of a Tryed code also offers convenience methods to:

• KeepCalm downgrading a panic to an error condition;
• Escalate upgrading a panic to a fatal error;
• Log the error, panic or fatal condition, using the appropriate logger method - presumably triggering a new panic or exiting the program.

Installation

go get github.com/agext/calmly

License

Package calmly is released under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Overview

Package calmly implements convenient runtime panic recovery and handling

When a panic condition needs to be handled by the program (rather than crashing it), wrap the code that can trigger such condition in a `Try`, which allows you to `Catch` the panic for further processing.

The `Outcome` of a `Try`ed code also offers convenience methods to: - `KeepCalm` downgrading a panic to an error condition; - `Escalate` upgrading a panic to a fatal error; - `Log` the error, panic or fatal condition, using the appropriate logger method - presumably triggering a new panic or exiting the program.

Index

• Constants
• type Logger
• type Outcome
  • func Try(f interface{}) (o *Outcome)
  • func (o *Outcome) AddInfo(s ...string) *Outcome
  • func (o *Outcome) Catch(f func(*Outcome)) *Outcome
  • func (o *Outcome) Code() int
  • func (o *Outcome) Err() error
  • func (o *Outcome) Error() string
  • func (o *Outcome) Escalate() *Outcome
  • func (o *Outcome) Info() []string
  • func (o *Outcome) KeepCalm() *Outcome
  • func (o *Outcome) Level() int8
  • func (o *Outcome) Log(log Logger) *Outcome
  • func (o *Outcome) Result() (interface{}, error)
  • func (o *Outcome) SetCode(c int) *Outcome
  • func (o *Outcome) SetLevel(l int8) *Outcome
  • func (o *Outcome) SetText(t string) *Outcome
  • func (o *Outcome) Text() string
  • func (o *Outcome) Value() interface{}

Constants

const (
	OK int8 = 0

	ERROR int8 = iota + 3
	PANIC
	FATAL
)

Outcome levels match logging levels in agext/log

const (
	ERR_TRY_ARG int = iota
	ERR_TRY_PANIC
)

Predefined error codes

Types

type Logger

type Logger interface {
	Fatal(...interface{})
	Panic(...interface{})
	Print(...interface{})
}

Logger defines the interface expected by the Log method of Outcome

type Outcome

type Outcome struct {
	// contains filtered or unexported fields
}

Outcome represents the state of a `Try`ed call, including information about any panic it may have triggered, as well as the returned value and error, if applicable.

func Try

func Try(f interface{}) (o *Outcome)

Try calls the function it receives as argument, recovering from any panic it may cause

func (*Outcome) AddInfo

func (o *Outcome) AddInfo(s ...string) *Outcome

AddInfo adds (more) error info to the receiver.

func (*Outcome) Catch

func (o *Outcome) Catch(f func(*Outcome)) *Outcome

Catch calls the provided function passing the receiver Outcome as argument, only if the Outcome is at PANIC level.

func (*Outcome) Code

func (o *Outcome) Code() int

Code returns the error code stored by the receiver.

func (*Outcome) Err

func (o *Outcome) Err() error

Err provides the error returned by the Try-ed function, if any.

func (*Outcome) Error

func (o *Outcome) Error() string

Error returns a string representation of the Outcome if it is in an error condition, or an empty string if no error or panic occurred. Note that the Try-ed function returning a non-nil error does not constitute an error condition for the Outcome. That error value can be retrieved via Err or Result. This is also useful for satisfying the `error` interface.

func (*Outcome) Escalate

func (o *Outcome) Escalate() *Outcome

Escalate converts a PANIC into a FATAL condition, to trigger program termination upon logging the outcome.

func (*Outcome) Info

func (o *Outcome) Info() []string

Info returns the error info stored by the receiver.

func (*Outcome) KeepCalm

func (o *Outcome) KeepCalm() *Outcome

KeepCalm downgrades a PANIC to ERROR level, to avoid triggering a panic upon logging the outcome.

func (*Outcome) Level

func (o *Outcome) Level() int8

Level returns the error level stored by the receiver.

func (*Outcome) Log

func (o *Outcome) Log(log Logger) *Outcome

Log sends the error-condition Outcome to the provided log, using the appropriate logging function: FATAL conditions are logged using Fatal(), PANIC using Panic(), and ERROR using Print(). Non-error conditions are not logged because there is no information stored in the Outcome, beside what the Try-ed function returned (and is better suited to log itself).

func (*Outcome) Result

func (o *Outcome) Result() (interface{}, error)

Result provides the value and error returned by the Try-ed function, if any.

func (*Outcome) SetCode

func (o *Outcome) SetCode(c int) *Outcome

SetCode sets the error code stored by the receiver.

func (*Outcome) SetLevel

func (o *Outcome) SetLevel(l int8) *Outcome

SetLevel sets the error level stored by the receiver.

func (*Outcome) SetText

func (o *Outcome) SetText(t string) *Outcome

SetText sets the error text stored by the receiver.

func (*Outcome) Text

func (o *Outcome) Text() string

Text returns the error text stored by the receiver.

func (*Outcome) Value

func (o *Outcome) Value() interface{}

Value provides the value returned by the Try-ed function, if any.