errors

README

Errors

Errors handling utilities.

• Error wrapping.
• Detailed error printing.
• zerolog integration.

Documentation

Index

• func As(err error, target interface{}) bool
• func ErrorMarshalFunc(err error) interface{}
• func Errorf(format string, args ...interface{}) error
• func FormatErrFieldValue(i interface{}) string
• func Is(err, target error) bool
• func New(message string) error
• func PrintErrorDetails(err error) []string
• func Unwrap(err error) error
• func WithStack(err error) error
• func Wrap(err error, message string) error
• func Wrapf(err error, format string, args ...interface{}) error
• type Frame
  • func (f Frame) Format(s fmt.State, verb rune)
  • func (f Frame) MarshalText() ([]byte, error)
• type Stack
  • func Callers(additionalSkip int) *Stack
  • func (s *Stack) Format(st fmt.State, verb rune)
  • func (s *Stack) StackTrace() StackTrace
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)

Functions

func As

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

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

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.

As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.

func ErrorMarshalFunc

func ErrorMarshalFunc(err error) interface{}

ErrorMarshalFunc returns an errorFormat struct containing detailed error data.

func Errorf

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

Errorf formats according to a format specifier and returns the string as a value that satisfies error. Errorf also records the stack trace at the point it was called.

func FormatErrFieldValue

func FormatErrFieldValue(i interface{}) string

FormatErrFieldValue is a custom error formatter for the zerolog console writer. If the error is a custom interface we suppose it's of type errorFormat generated by ErrorMarshalFunc. In this case the zerolog console writer will json.Marshal the error and pass it to this function. So we unmarshal it and format it.

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(message string) error

New returns an error with the supplied message. New also records the stack trace at the point it was called.

func PrintErrorDetails

func PrintErrorDetails(err error) []string

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 WithStack

func WithStack(err error) error

WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.

func Wrap

func Wrap(err error, message string) error

Wrap returns an error annotating err with a stack trace at the point Wrap is called, and the supplied message. If err is nil, Wrap returns nil.

func Wrapf

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

Wrapf returns an error annotating err with a stack trace at the point Wrapf is called, and the format specifier. If err is nil, Wrapf returns nil.

Types

type Frame

type Frame uintptr

Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.

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   function name and path of source file relative to the compile time
      GOPATH separated by \n\t (<funcname>\n\t<path>)
%+v   equivalent to %+s:%d

func (Frame) MarshalText

func (f Frame) MarshalText() ([]byte, error)

MarshalText formats a stacktrace Frame as a text string. The output is the same as that of fmt.Sprintf("%+v", f), but without newlines or tabs.

type Stack

type Stack []uintptr

Stack represents a Stack of program counters.

func Callers

func Callers(additionalSkip int) *Stack

func (*Stack) Format

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

func (*Stack) StackTrace

func (s *Stack) StackTrace() StackTrace

type StackTrace

type StackTrace []Frame

StackTrace is stack of Frames from innermost (newest) to outermost (oldest).

func (StackTrace) Format

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

Format formats the stack of Frames according to the fmt.Formatter interface.

%s	lists source files for each Frame in the stack
%v	lists the source file and line number for each Frame in the stack

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

%+v   Prints filename, function, and line number for each Frame in the stack.