errutil

Documentation

Index

• Constants
• func Append(err error, errs ...error) error
• func AppendFlat(err error, errs ...error) error
• func GetStackTrace() string
• func Is(err interface{}, cause error) bool
• func New(class interface{}, options ...Option) error
• func NewDepth(class interface{}, startDepth int, options ...Option) error
• type Class
  • func (c Class) Error() string
  • func (c Class) MarshalJSON() ([]byte, error)
• type ClassProvider
• type Exception
  • func As(err interface{}) *Exception
  • func (e *Exception) As(target interface{}) bool
  • func (e *Exception) Decompose() map[string]interface{}
  • func (e *Exception) Error() string
  • func (e *Exception) Format(s fmt.State, verb rune)
  • func (e *Exception) Is(target error) bool
  • func (e *Exception) MarshalJSON() ([]byte, error)
  • func (e *Exception) String() string
  • func (e *Exception) UnmarshalJSON(contents []byte) error
  • func (e *Exception) Unwrap() error
• type Frame
  • func (f Frame) File() string
  • func (f Frame) Format(s fmt.State, verb rune)
  • func (f Frame) Func() string
  • func (f Frame) Line() int
  • func (f Frame) PC() uintptr
• type Multi
  • func (m Multi) Error() string
  • func (m Multi) Unwrap() error
  • func (m Multi) WrappedErrors() []error
• type Option
  • func OptInner(inner error) Option
  • func OptInnerClass(inner error) Option
  • func OptMessage(args ...interface{}) Option
  • func OptMessagef(format string, args ...interface{}) Option
  • func OptStackTrace(stack StackTrace) Option
• type StackPointers
  • func Callers(startDepth int) StackPointers
  • func (st StackPointers) Format(s fmt.State, verb rune)
  • func (st StackPointers) MarshalJSON() ([]byte, error)
  • func (st StackPointers) String() string
  • func (st StackPointers) Strings() []string
• type StackStrings
  • func (ss StackStrings) Format(s fmt.State, verb rune)
  • func (ss StackStrings) MarshalJSON() ([]byte, error)
  • func (ss StackStrings) String() string
  • func (ss StackStrings) Strings() []string
• type StackTrace
• type StackTraceProvider

Constants

const (
	DefaultStackTraceStartDepth = 3
	DefaultErrorStartDepth      = 4
)

Defaults for start depth.

Functions

func Append

func Append(err error, errs ...error) error

Append appends errors together, creating a multi-error.

Errors that are already multi-errors will be appended as is, creating a jagged error list.

To have a one-dimensional resulting error list, use `AppendFlat(...)`.

func AppendFlat

func AppendFlat(err error, errs ...error) error

AppendFlat appends errors together, creating a multi-error.

It differs from `Append(...)` in that it will flatten errors in the list that are already `Multi` errors, creating a one dimensional return list instead of a jagged return list.

func GetStackTrace

func GetStackTrace() string

GetStackTrace is a utility method to get the current stack trace at call time.

func Is

func Is(err interface{}, cause error) bool

Is is a helper function that returns if an error is an ex.

It will handle if the err is an exception, a multi-error or a regular error. "Isness" is evaluated by if the class of the exception matches the class of the cause

func New

func New(class interface{}, options ...Option) error

New returns a new error with a call stack.

Pragma: this violates the rule that you should take interfaces and return concrete types intentionally; it is important for the semantics of typed pointers and nil for this to return an interface because (*Ex)(nil) != nil, but (error)(nil) == nil.

func NewDepth

func NewDepth(class interface{}, startDepth int, options ...Option) error

NewDepth creates a new exception with a given start point of the stack.

Types

type Class

type Class string

Class is a string wrapper that implements `error`. Use this to implement constant exception causes.

func (Class) Error

func (c Class) Error() string

Class implements `error`.

func (Class) MarshalJSON

func (c Class) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type ClassProvider

type ClassProvider interface {
	Class() error
}

ClassProvider is a type that can return an exception class.

type Exception

type Exception struct {
	// Class disambiguates between errors, it can be used to identify the type of the error.
	Class error
	// Message adds further detail to the error, and shouldn't be used for disambiguation.
	Message string
	// Inner holds the original error in cases where we're wrapping an error with a stack trace.
	Inner error
	// StackTrace is the call stack frames used to create the stack output.
	StackTrace StackTrace
}

Exception is an error with a stack trace.

It also can have an optional cause, it implements `Exception`

func As

func As(err interface{}) *Exception

As is a helper method that returns an error as an ex.

func (*Exception) As

func (e *Exception) As(target interface{}) bool

As delegates to the errors.As to match on the Ex class.

func (*Exception) Decompose

func (e *Exception) Decompose() map[string]interface{}

Decompose breaks the exception down to be marshaled into an intermediate format.

func (*Exception) Error

func (e *Exception) Error() string

Error implements the `error` interface. It returns the exception class, without any of the other supporting context like the stack trace. To fetch the stack trace, use .String().

func (*Exception) Format

func (e *Exception) Format(s fmt.State, verb rune)

Format allows for conditional expansion in printf statements based on the token and flags used.

%+v : class + message + stack
%v, %c : class
%m : message
%t : stack

func (*Exception) Is

func (e *Exception) Is(target error) bool

Is returns true if the target error matches the Ex. Enables errors.Is on Ex classes when an error is wrapped using Ex.

func (*Exception) MarshalJSON

func (e *Exception) MarshalJSON() ([]byte, error)

MarshalJSON is a custom json marshaler.

func (*Exception) String

func (e *Exception) String() string

String returns a fully formed string representation of the ex. It's equivalent to calling sprintf("%+v", ex).

func (*Exception) UnmarshalJSON

func (e *Exception) UnmarshalJSON(contents []byte) error

UnmarshalJSON is a custom json unmarshaler.

func (*Exception) Unwrap

func (e *Exception) Unwrap() error

Unwrap returns the inner error if it exists. Enables error chaining and calling errors.Is/As to match on inner errors.

type Frame

type Frame uintptr

Frame represents a program counter inside a stack frame.

func (Frame) File

func (f Frame) File() string

File returns the full path to the file that contains the function for this Frame's pc.

func (Frame) Format

func (f Frame) Format(s fmt.State, verb rune)

Format formats the frame according to the fmt.Formatter interface.

%s    source file
%d    source line
%n    function name
%v    equivalent to %s:%d

Format accepts flags that alter the printing of some verbs, as follows:

%+s   path of source file relative to the compile time GOPATH
%+v   equivalent to %+s:%d

func (Frame) Func

func (f Frame) Func() string

Func returns the func name.

func (Frame) Line

func (f Frame) Line() int

Line returns the line number of source code of the function for this Frame's pc.

func (Frame) PC

func (f Frame) PC() uintptr

PC returns the program counter for this frame; multiple frames may have the same PC value.

type Multi

type Multi []error

Multi represents an array of errors.

func (Multi) Error

func (m Multi) Error() string

Error implements error.

func (Multi) Unwrap

func (m Multi) Unwrap() error

Unwrap returns an error from Error (or nil if there are no errors). This error returned will further support Unwrap to get the next error, etc.

The resulting error supports errors.As/Is/Unwrap so you can continue to use the stdlib errors package to introspect further.

This will perform a shallow copy of the errors slice. Any errors appended to this error after calling Unwrap will not be available until a new Unwrap is called on the multierror.Error.

func (Multi) WrappedErrors

func (m Multi) WrappedErrors() []error

WrappedErrors implements something in errors.

type Option

type Option func(*Exception)

Option is an exception option.

func OptInner

func OptInner(inner error) Option

OptInner sets an inner or wrapped ex.

func OptInnerClass

func OptInnerClass(inner error) Option

OptInnerClass sets an inner unwrapped exception. Use this if you don't want to include a strack trace for a cause.

func OptMessage

func OptMessage(args ...interface{}) Option

OptMessage sets the exception message from a given list of arguments with fmt.Sprint(args...).

func OptMessagef

func OptMessagef(format string, args ...interface{}) Option

OptMessagef sets the exception message from a given list of arguments with fmt.Sprintf(format, args...).

func OptStackTrace

func OptStackTrace(stack StackTrace) Option

OptStackTrace sets the exception stack.

type StackPointers

type StackPointers []uintptr

StackPointers is stack of uintptr stack frames from innermost (newest) to outermost (oldest).

func Callers

func Callers(startDepth int) StackPointers

Callers returns stack pointers.

func (StackPointers) Format

func (st StackPointers) Format(s fmt.State, verb rune)

Format formats the stack trace.

func (StackPointers) MarshalJSON

func (st StackPointers) MarshalJSON() ([]byte, error)

MarshalJSON is a custom json marshaler.

func (StackPointers) String

func (st StackPointers) String() string

String returns a single string representation of the stack pointers.

func (StackPointers) Strings

func (st StackPointers) Strings() []string

Strings dereferences the StackTrace as a string slice

type StackStrings

type StackStrings []string

StackStrings represents a stack trace as string literals.

func (StackStrings) Format

func (ss StackStrings) Format(s fmt.State, verb rune)

Format formats the stack trace.

func (StackStrings) MarshalJSON

func (ss StackStrings) MarshalJSON() ([]byte, error)

MarshalJSON is a custom json marshaler.

func (StackStrings) String

func (ss StackStrings) String() string

String returns a single string representation of the stack pointers.

func (StackStrings) Strings

func (ss StackStrings) Strings() []string

Strings returns the stack strings as a string slice.

type StackTrace

type StackTrace interface {
	fmt.Formatter
	Strings() []string
	String() string
}

StackTrace is a stack trace provider.

type StackTraceProvider

type StackTraceProvider interface {
	StackTrace() StackTrace
}

StackTraceProvider is a type that can return an exception class.