eris

Documentation

Index

• func Cause(err error) error
• func Errorf(format string, args ...interface{}) error
• func Is(err, target error) bool
• func New(msg string) error
• func StackFrames(err error) []uintptr
• func ToCustomJSON(err error, format JSONFormat) map[string]interface{}
• func ToCustomString(err error, format StringFormat) string
• func ToJSON(err error, withTrace bool) map[string]interface{}
• func ToString(err error, withTrace bool) string
• func Unwrap(err error) error
• func Wrap(err error, msg string) error
• func Wrapf(err error, format string, args ...interface{}) error
• type ErrLink
• type ErrRoot
• type FormatOptions
• type JSONFormat
  • func NewDefaultJSONFormat(options FormatOptions) JSONFormat
• type Stack
• type StackFrame
• type StringFormat
  • func NewDefaultStringFormat(options FormatOptions) StringFormat
• type UnpackedError
  • func Unpack(err error) UnpackedError

Functions

func Cause

func Cause(err error) error

Cause returns the root cause of the error, which is defined as the first error in the chain. The original error is returned if it does not implement `Unwrap() error` and nil is returned if the error is nil.

func Errorf

func Errorf(format string, args ...interface{}) error

Errorf creates a new root error with a formatted message.

func Is

func Is(err, target error) bool

Is reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.

An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.

func New

func New(msg string) error

New creates a new root error with a static message.

func StackFrames

func StackFrames(err error) []uintptr

StackFrames returns the trace of an error in the form of a program counter slice. Use this method if you want to pass the eris stack trace to some other error tracing library.

func ToCustomJSON

func ToCustomJSON(err error, format JSONFormat) map[string]interface{}

ToCustomJSON returns a JSON formatted map for a given error.

To declare custom format, the Format object has to be passed as an argument. An error without trace will be formatted as following:

{
  "root": {
    "message": "Root error msg",
  },
  "wrap": [
    {
      "message": "Wrap error msg'",
    }
  ]
}

An error with trace will be formatted as following:

{
  "root": {
    "message": "Root error msg",
    "stack": [
      "<Method2>[Format.StackElemSep]<File2>[Format.StackElemSep]<Line2>",
      "<Method1>[Format.StackElemSep]<File1>[Format.StackElemSep]<Line1>"
    ]
  }
  "wrap": [
    {
      "message": "Wrap error msg",
      "stack": "<Method2>[Format.StackElemSep]<File2>[Format.StackElemSep]<Line2>"
    }
  ]
}

func ToCustomString

func ToCustomString(err error, format StringFormat) string

ToCustomString returns a custom formatted string for a given error.

To declare custom format, the Format object has to be passed as an argument. An error without trace will be formatted as following:

<Wrap error msg>[Format.ErrorSep]<Root error msg>

An error with trace will be formatted as following:

<Wrap error msg>[Format.MsgStackSep]
[Format.PreStackSep]<Method2>[Format.StackElemSep]<File2>[Format.StackElemSep]<Line2>[Format.ErrorSep]
<Root error msg>[Format.MsgStackSep]
[Format.PreStackSep]<Method2>[Format.StackElemSep]<File2>[Format.StackElemSep]<Line2>[Format.ErrorSep]
[Format.PreStackSep]<Method1>[Format.StackElemSep]<File1>[Format.StackElemSep]<Line1>[Format.ErrorSep]

func ToJSON

func ToJSON(err error, withTrace bool) map[string]interface{}

ToJSON returns a JSON formatted map for a given error.

An error without trace will be formatted as following:

{
  "root": [
    {
      "message": "Root error msg"
    }
  ],
  "wrap": {
    "message": "Wrap error msg"
  }
}

An error with trace will be formatted as following:

{
  "root": [
    {
      "message": "Root error msg",
      "stack": [
        "<Method2>:<File2>:<Line2>",
        "<Method1>:<File1>:<Line1>"
      ]
    }
  ],
  "wrap": {
    "message": "Wrap error msg",
    "stack": "<Method2>:<File2>:<Line2>"
  }
}

func ToString

func ToString(err error, withTrace bool) string

ToString returns a default formatted string for a given error.

An error without trace will be formatted as following:

<Wrap error msg>: <Root error msg>

An error with trace will be formatted as following:

<Wrap error msg>
  <Method2>:<File2>:<Line2>
<Root error msg>
  <Method2>:<File2>:<Line2>
  <Method1>:<File1>:<Line1>

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

func Wrap

func Wrap(err error, msg string) error

Wrap adds additional context to all error types while maintaining the type of the original error.

This method behaves differently for each error type. For root errors, the stack trace is reset to the current callers which ensures traces are correct when using global/sentinel error values. Wrapped error types are simply wrapped with the new context. For external types (i.e. something other than root or wrap errors), this method attempts to unwrap them while building a new error chain. If an external type does not implement the unwrap interface, it flattens the error and creates a new root error from it before wrapping with the additional context.

func Wrapf

func Wrapf(err error, format string, args ...interface{}) error

Wrapf adds additional context to all error types while maintaining the type of the original error.

This is a convenience method for wrapping errors with formatted messages and is otherwise the same as Wrap.

Types

type ErrLink

type ErrLink struct {
	Msg   string
	Frame StackFrame
}

ErrLink represents a single error frame and the accompanying message.

type ErrRoot

type ErrRoot struct {
	Msg   string
	Stack Stack
}

ErrRoot represents an error stack and the accompanying message.

type FormatOptions

type FormatOptions struct {
	InvertOutput bool // Flag that inverts the error output (wrap errors shown first).
	WithTrace    bool // Flag that enables stack trace output.
	InvertTrace  bool // Flag that inverts the stack trace output (top of call stack shown first).

}

FormatOptions defines output options like omitting stack traces and inverting the error or stack order.

type JSONFormat

type JSONFormat struct {
	Options FormatOptions // Format options (e.g. omitting stack trace or inverting the output order).
	// todo: maybe allow setting of wrap/root keys in the output map as well
	StackElemSep string // Separator between elements of each stack frame.
}

JSONFormat defines a JSON error format.

func NewDefaultJSONFormat

func NewDefaultJSONFormat(options FormatOptions) JSONFormat

NewDefaultJSONFormat returns a default JSON output format.

type Stack

type Stack []StackFrame

Stack is an array of stack frames stored in a human readable format.

type StackFrame

type StackFrame struct {
	Name string
	File string
	Line int
}

StackFrame stores a frame's runtime information in a human readable format.

type StringFormat

type StringFormat struct {
	Options      FormatOptions // Format options (e.g. omitting stack trace or inverting the output order).
	MsgStackSep  string        // Separator between error messages and stack frame data.
	PreStackSep  string        // Separator at the beginning of each stack frame.
	StackElemSep string        // Separator between elements of each stack frame.
	ErrorSep     string        // Separator between each error in the chain.
}

StringFormat defines a string error format.

func NewDefaultStringFormat

func NewDefaultStringFormat(options FormatOptions) StringFormat

NewDefaultStringFormat returns a default string output format.

type UnpackedError

type UnpackedError struct {
	ErrRoot     ErrRoot
	ErrChain    []ErrLink
	ExternalErr string
}

UnpackedError represents complete information about an error.

This type can be used for custom error logging and parsing. Use `eris.Unpack` to build an UnpackedError from any error type. The ErrChain and ErrRoot fields correspond to `wrapError` and `rootError` types, respectively. If any other error type is unpacked, it will appear in the ExternalErr field.

func Unpack

func Unpack(err error) UnpackedError

Unpack returns a human-readable UnpackedError type for a given error.