Back to godoc.org
github.com/go-errors/errors

Package errors

v1.0.0
Latest Go to latest

The latest major version is .

Published: Nov 1, 2017 | License: MIT | Module: github.com/go-errors/errors

Overview

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

Variables

var MaxStackDepth = 50

The maximum number of stackframes on any error.

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

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 Errorf

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.

func New

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.

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 Wrap

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.

Example

Code:

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

return a()

func WrapPrefix

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

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) Stack

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

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

func (*Error) StackFrames

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

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

func (*Error) TypeName

func (err *Error) TypeName() string

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

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 NewStackFrame

func NewStackFrame(pc uintptr) (frame StackFrame)

NewStackFrame popoulates a stack frame object from the program counter.

func (*StackFrame) Func

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

Func returns the function that contained this frame.

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()

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier