merr

package
Version: v0.0.0-...-c20f884 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 30, 2019 License: MIT Imports: 9 Imported by: 2

Documentation

Overview

Package merr extends the errors package with features like key-value attributes for errors, embedded stacktraces, and multi-errors.

merr functions takes in generic errors of the built-in type. The returned errors are wrapped by a type internal to merr, and appear to also be of the generic error type. This means that equality checking will not work, unless the Base function is used. If any functions are given nil they will also return nil.

Index

Constants

This section is empty.

Variables

View Source
var MaxStackSize = 50

MaxStackSize indicates the maximum number of stack frames which will be stored when embedding stack traces in errors.

Functions

func Base

func Base(e error) error

Base takes in an error and checks if it is merr's internal error type. If it is then the underlying error which is being wrapped is returned. If it's not then the passed in error is returned as-is.

func Context

func Context(e error) context.Context

Context returns the Context embedded in this error from the last call to Wrap or New. If none is embedded this uses context.Background().

The returned Context will have annotated on it (see mctx.Annotate) the underlying error's string (as returned by Error()) and the error's stack location. Stack locations are automatically added by New and Wrap via WithStack.

If this error is nil this returns context.Background().

func Equal

func Equal(e1, e2 error) bool

Equal is a shortcut for Base(e1) == Base(e2).

func New

func New(str string, ctxs ...context.Context) error

New is a shortcut for:

merr.Wrap(errors.New(str), ctxs...)

func Value

func Value(e error, k interface{}) interface{}

Value returns the value embedded in the error for the given key, or nil if the error isn't from this package or doesn't have that key embedded.

func WithStack

func WithStack(e error, skip int) error

WithStack returns an error with the current stacktrace embedded in it (as a Stacktrace type). If skip is non-zero it will skip that many frames from the top of the stack. The frame containing the WithStack call itself is always excluded.

This call always overwrites any previously existing stack information on the error, as opposed to Wrap which only does so if the error didn't already have any.

func WithValue

func WithValue(e error, k, v interface{}) error

WithValue returns a copy of the original error, automatically wrapping it if the error is not from merr (see Wrap). The returned error has an attribute value set on it for the given key.

func Wrap

func Wrap(e error, ctx ...context.Context) error

Wrap returns a copy of the given error wrapped in merr's inner type. It will perform an mctx.MergeAnnotations on the given Contexts to create a new Context, and embed that in the returned error. If the given error already has an embedded Context then ctxs will be merged into that.

This function automatically embeds stack information into the error as it's being stored, using WithStack, unless the error already has stack information in it.

Wrapping nil returns nil.

func WrapSkip

func WrapSkip(e error, skip int, ctxs ...context.Context) error

WrapSkip is like Wrap but also allows for skipping extra stack frames when embedding the stack into the error.

Types

type Stacktrace

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

Stacktrace represents a stack trace at a particular point in execution.

func Stack

func Stack(e error) (Stacktrace, bool)

Stack returns the Stacktrace instance which was embedded by Wrap/WrapSkip, or false if none ever was.

func (Stacktrace) Frame

func (s Stacktrace) Frame() runtime.Frame

Frame returns the first frame in the stack.

func (Stacktrace) Frames

func (s Stacktrace) Frames() []runtime.Frame

Frames returns all runtime.Frame instances for this stack.

func (Stacktrace) FullString

func (s Stacktrace) FullString() string

FullString returns the full stack trace.

func (Stacktrace) String

func (s Stacktrace) String() string

String returns a string representing the top-most frame of the stack.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL