errors: github.com/go-errors/errors Index | Examples | Files

package errors

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

Package errors provides errors that have stack-traces.

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.

For 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)
        }
    }
}

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

Index

Examples

Package Files

error.go parse_panic.go stackframe.go

Variables

var MaxStackDepth = 50

The maximum number of stackframes on any error.

func Is Uses

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 the same object, or if they both contain the same error inside an errors.Error.

Code:

_, err := reader.Read(buff)
if Is(err, io.EOF) {
    return
}

type Error Uses

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 Errorf Uses

func Errorf(format string, a ...interface{}) *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.

Code:

if x%2 == 1 {
    return 0, Errorf("can only halve even numbers, got %d", x)
}
return x / 2, nil

func New Uses

func New(e interface{}) *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.

Code:

// calling New attaches the current stacktrace to the existing UnexpectedEOF error
return New(UnexpectedEOF)

func ParsePanic Uses

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 Wrap Uses

func Wrap(e interface{}, skip int) *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.

Code:


if err := recover(); err != nil {
    return Wrap(err, 1)
}

return a()

func WrapPrefix Uses

func WrapPrefix(e interface{}, prefix string, skip int) *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) Callers Uses

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

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

func (*Error) Error Uses

func (err *Error) Error() string

Error returns the underlying error's message.

Code:

fmt.Println(err.Error())

func (*Error) ErrorStack Uses

func (err *Error) ErrorStack() string

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

Code:

fmt.Println(err.(*Error).ErrorStack())

func (*Error) Stack Uses

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

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

Code:

fmt.Println(err.Stack())

func (*Error) StackFrames Uses

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

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

Code:

for _, frame := range err.StackFrames() {
    fmt.Println(frame.File, frame.LineNumber, frame.Package, frame.Name)
}

func (*Error) TypeName Uses

func (err *Error) TypeName() string

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

Code:

fmt.Println(err.TypeName(), err.Error())

type StackFrame Uses

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 NewStackFrame Uses

func NewStackFrame(pc uintptr) (frame StackFrame)

NewStackFrame popoulates a stack frame object from the program counter.

func (*StackFrame) Func Uses

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

Func returns the function that contained this frame.

func (*StackFrame) SourceLine Uses

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 Uses

func (frame *StackFrame) String() string

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

Package errors imports 7 packages (graph) and is imported by 483 packages. Updated 2018-08-13. Refresh now. Tools for package owners.