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