errors

README

errors

Custom library to annotate errors.

Based on https://godoc.org/github.com/samsarahq/go/oops and adapted to our function names and needs.

Basic usage

import (
  "libs.altipla.consulting/errors"
)

Avoid manual errors

To reach the maximum help from this library all errors should be annotated. The easiest way to do it is following these rules:

• Ban the import "errors" anywhere in the project.
• Ban the import "github.com/altipla-consulting/errors" anywhere in the project.
• Ban the import "github.com/juju/errors" anywhere in the project.
• Ban the use of fmt.Errorf anywhere in the project.
• Ban the use of errors.New if it is not a global declaration.
• Ban the use of return err and replace it with return errors.Trace(err) everywhere.

Documentation

Overview

Based on https://godoc.org/github.com/samsarahq/go/oops and adapted to our function names and needs.

Index

• func Cause(err error) error
• func Details(err error) string
• func Errorf(format string, a ...interface{}) error
• func Frames(err error) [][]Frame
• func Is(err, target error) bool
• func LogFields(err error) log.Fields
• func New(err string) error
• func Recover(p interface{}) error
• func Stack(err error) string
• func Trace(err error) error
• func Wrapf(err error, format string, a ...interface{}) error
• type Frame

Functions

func Cause

func Cause(err error) error

Cause extracts the cause error of an altipla error. If err is not an altipla error, err itself is returned.

You can use Cause to check if an error is an expected error. For example, if you know than EOF error is fine, you can handle it with Cause.

func Details

func Details(err error) string

func Errorf

func Errorf(format string, a ...interface{}) error

Errorf creates a new error with a reason and a stacktrace.

Use Errorf in places where you would otherwise return an error using fmt.Errorf or errors.New.

Note that the result of Errorf includes a stacktrace. This means that Errorf is not suitable for storing in global variables. For such errors, keep using errors.New.

func Frames

func Frames(err error) [][]Frame

Frames extracts all frames from an altipla error. If err is not an altipla error, nil is returned.

func Is

func Is(err, target error) bool

Is reports whether err or its cause matches target.

func LogFields

func LogFields(err error) log.Fields

func New

func New(err string) error

New creates a new error without stacktrace.

func Recover

func Recover(p interface{}) error

Recover recovers from a panic in a defer. If there is no panic, Recover() returns nil. To use, call error.Recover(recover()) and compare the result to nil.

func Stack

func Stack(err error) string

func Trace

func Trace(err error) error

Trace annotates an error with a stacktrace.

Use Trace in places where you would otherwise return an error directly. If the error passed to Trace is nil, Trace will also return nil. This makes it safe to use in one-line return statements.

To check if a wrapped error is a specific error, such as io.EOF, you can extract the error passed in to Trace using Cause.

func Wrapf

func Wrapf(err error, format string, a ...interface{}) error

Wrapf annotates an error with a reason and a stacktrace. If err is nil, Wrapf returns nil.

Use Wrapf in places where you would otherwise return an error directly. If the error passed to Wrapf is nil, Wrapf will also return nil. This makes it safe to use in one-line return statements.

To check if a wrapped error is a specific error, such as io.EOF, you can extract the error passed in to Wrapf using Cause.

Types

type Frame

type Frame struct {
	File     string
	Function string
	Line     int
	Reason   string
}

A Frame represents a Frame in an altipla callstack. The Reason is the manual annotation passed to altipla.Wrapf.