gerror

README

go-errors/errors

Package errors adds stacktrace support to errors in go.

This is particularly useful when you want to understand the state of execution when an error was returned unexpectedly.

It provides the type *Error which implements the standard golang error interface, so you can use this library interchangably with code that is expecting a normal error return.

Usage

Full documentation is available on godoc, but here's a simple example:

package crashy

import "github.com/go-errors/errors"

var Crashed = errors.Errorf("oh dear")

func Crash() error {
    return errors.New(Crashed)
}

This can be called as follows:

package main

import (
    "crashy"
    "fmt"
    "github.com/go-errors/errors"
)

func main() {
    err := crashy.Crash()
    if err != nil {
        if errors.Is(err, crashy.Crashed) {
            fmt.Println(err.(*errors.Error).ErrorStack())
        } else {
            panic(err)
        }
    }
}

Meta-fu

This package was original written to allow reporting to Bugsnag from bugsnag-go, but after I found similar packages by Facebook and Dropbox, it was moved to one canonical location so everyone can benefit.

This package is licensed under the MIT license, see LICENSE.MIT for details.

Changelog

• v1.1.0 updated to use go1.13's standard-library errors.Is method instead of == in errors.Is

Documentation

Index

• Variables
• func Is(e error, original error) bool
• func New(e ...interface{}) gcore.Error
• func NewStackFrame(pc uintptr) (frameI gcore.StackFrame)
• func ParseRecover(e interface{}) error
• func Recover(f func(err interface{}))
• func RecoverNop()
• func RecoverNopFunc(f func())
• func Stack(e interface{}) string
• func Try(f func()) (e error)
• func TryWithStack(f func()) (e gcore.Error)
• func Wrap(e interface{}) gcore.Error
• type Error
  • func ParsePanic(text string) (*Error, error)
  • func (err *Error) Callers() []uintptr
  • func (err *Error) Error() string
  • func (err *Error) ErrorStack() string
  • func (this *Error) Errorf(format string, a ...interface{}) gcore.Error
  • func (this *Error) New(e interface{}) gcore.Error
  • func (this *Error) Recover(f ...interface{})
  • func (err *Error) Stack() []byte
  • func (this *Error) StackError(e interface{}) string
  • func (err *Error) StackFrames() []gcore.StackFrame
  • func (err *Error) StackStr() string
  • func (err *Error) String() string
  • func (err *Error) TypeName() string
  • func (this *Error) Wrap(e interface{}) gcore.Error
  • func (this *Error) WrapN(e interface{}, skip int) gcore.Error
  • func (this *Error) WrapPrefix(e interface{}, prefix string, skip int) gcore.Error
  • func (this *Error) WrapPrefixN(e interface{}, prefix string, skip int) gcore.Error
• type StackFrame
  • func (frame *StackFrame) Func() *runtime.Func
  • func (frame *StackFrame) GetFile() string
  • func (frame *StackFrame) GetLineNumber() int
  • func (frame *StackFrame) GetName() string
  • func (frame *StackFrame) GetPackage() string
  • func (frame *StackFrame) GetProgramCounter() uintptr
  • func (frame *StackFrame) SourceLine() (string, error)
  • func (frame *StackFrame) String() string

Variables

var MaxStackDepth = 50

MaxStackDepth the maximum number of stack frames on any error.

Functions

func Is

func Is(e error, original error) bool

Is detects whether the error is equal to a given error. Errors are considered equal by this function if they are matched by errors.Is or if their contained errors are matched through errors.Is

func New

func New(e ...interface{}) gcore.Error

func NewStackFrame

func NewStackFrame(pc uintptr) (frameI gcore.StackFrame)

NewStackFrame popoulates a stack frame object from the program counter.

func ParseRecover

func ParseRecover(e interface{}) error

func Recover

func Recover(f func(err interface{}))

func RecoverNop

func RecoverNop()

func RecoverNopFunc

func RecoverNopFunc(f func())

func Stack

func Stack(e interface{}) string

func Try

func Try(f func()) (e error)

func TryWithStack

func TryWithStack(f func()) (e gcore.Error)

func Wrap

func Wrap(e interface{}) gcore.Error

Types

type Error

type Error struct {
	Err error
	// contains filtered or unexported fields
}

Error is an error with an attached stacktrace. It can be used wherever the builtin error interface is expected.

func ParsePanic

func ParsePanic(text string) (*Error, error)

ParsePanic allows you to get an error object from the output of a go program that panicked. This is particularly useful with https://github.com/mitchellh/panicwrap.

func (*Error) Callers

func (err *Error) Callers() []uintptr

Callers satisfies the bugsnag ErrorWithCallerS() interface so that the stack can be read out.

func (*Error) Error

func (err *Error) Error() string

Error returns the underlying error's message.

func (*Error) ErrorStack

func (err *Error) ErrorStack() string

ErrorStack returns a string that contains both the error message and the callstack.

func (*Error) Errorf

func (this *Error) Errorf(format string, a ...interface{}) gcore.Error

Errorf creates a new error with the given message. You can use it as a drop-in replacement for fmt.Errorf() to provide descriptive errors in return values.

func (*Error) New

func (this *Error) New(e interface{}) gcore.Error

New makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The stacktrace will point to the line of code that called New.

func (*Error) Recover

func (this *Error) Recover(f ...interface{})

Recover usage Recover(func(e interface{})) or Recover(func(e interface{}),bool printStack)

func (*Error) Stack

func (err *Error) Stack() []byte

Stack returns the callstack formatted the same way that go does in runtime/debug.Stack()

func (*Error) StackError

func (this *Error) StackError(e interface{}) string

func (*Error) StackFrames

func (err *Error) StackFrames() []gcore.StackFrame

StackFrames returns an array of frames containing information about the stack.

func (*Error) StackStr

func (err *Error) StackStr() string

func (*Error) String

func (err *Error) String() string

func (*Error) TypeName

func (err *Error) TypeName() string

TypeName returns the type this error. e.g. *errors.stringError.

func (*Error) Wrap

func (this *Error) Wrap(e interface{}) gcore.Error

Wrap makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.

func (*Error) WrapN

func (this *Error) WrapN(e interface{}, skip int) gcore.Error

func (*Error) WrapPrefix

func (this *Error) WrapPrefix(e interface{}, prefix string, skip int) gcore.Error

WrapPrefix makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The prefix parameter is used to add a prefix to the error message when calling Error(). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.

func (*Error) WrapPrefixN

func (this *Error) WrapPrefixN(e interface{}, prefix string, skip int) gcore.Error

type StackFrame

type StackFrame struct {
	// The path to the file containing this ProgramCounter
	File string
	// The LineNumber in that file
	LineNumber int
	// The Name of the function that contains this ProgramCounter
	Name string
	// The Package that contains this function
	Package string
	// The underlying ProgramCounter
	ProgramCounter uintptr
}

A StackFrame contains all necessary information about to generate a line in a callstack.

func (*StackFrame) Func

func (frame *StackFrame) Func() *runtime.Func

Func returns the function that contained this frame.

func (*StackFrame) GetFile

func (frame *StackFrame) GetFile() string

func (*StackFrame) GetLineNumber

func (frame *StackFrame) GetLineNumber() int

func (*StackFrame) GetName

func (frame *StackFrame) GetName() string

func (*StackFrame) GetPackage

func (frame *StackFrame) GetPackage() string

func (*StackFrame) GetProgramCounter

func (frame *StackFrame) GetProgramCounter() uintptr

func (*StackFrame) SourceLine

func (frame *StackFrame) SourceLine() (string, error)

SourceLine gets the line of code (from File and Line) of the original source if possible.

func (*StackFrame) String

func (frame *StackFrame) String() string

String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()