errors

Documentation

Overview

Package errors extends the errors package in the stdlib.

Despite the implicit nature of interface satisfication in Go this package exports a number of interfaces to avoid defining them over and over again. Although it means coupling between the consumer code and this package, the purpose of this library (being a stdlib extension) justifies that.

Index

• Variables
• func Cause(err error) error
• func New(text string) error
• func NewWithStackTrace(text string) error
• func Recover(r interface{}) (err error)
• func With(err error, keyvals ...interface{}) error
• func WithMessage(err error, message string) error
• func WithPrefix(err error, keyvals ...interface{}) error
• func WithStack(err error) error
• type Causer
• type Contextor
• type ErrorCollection
• type Handler
  • func NewNopHandler() Handler
• type MultiErrorBuilder
  • func NewMultiErrorBuilder() *MultiErrorBuilder
  • func (b *MultiErrorBuilder) Add(err error)
  • func (b *MultiErrorBuilder) ErrOrNil() error
• type SingleWrapMode
• type StackTracer

Variables

var ErrMissingValue = New("(MISSING)")

ErrMissingValue is appended to keyvals slices with odd length to substitute the missing value.

Functions

func Cause

func Cause(err error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the Causer interface.

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

This is an alias to github.com/pkg/errors.Cause function.

func New

func New(text string) error

New returns an error that formats as the given text.

This is an alias to the stdlib errors.New function.

func NewWithStackTrace

func NewWithStackTrace(text string) error

NewWithStackTrace returns an error that formats as the given text and contains stack trace.

This is an alias to github.com/pkg/errors.New function.

func Recover

func Recover(r interface{}) (err error)

Recover accepts a recovered panic (if any) and converts it to an error (if necessary).

func With

func With(err error, keyvals ...interface{}) error

With returns a new error with keyvals context appended to it. If the wrapped error is already a contextual error created by With or WithPrefix keyvals is appended to the existing context, but a new error is returned.

func WithMessage

func WithMessage(err error, message string) error

WithMessage annotates err with a new message.

If err is nil, WithMessage returns nil.

This is an alias to github.com/pkg/errors.WithMessage function.

func WithPrefix

func WithPrefix(err error, keyvals ...interface{}) error

WithPrefix returns a new error with keyvals context appended to it. If the wrapped error is already a contextual error created by With or WithPrefix keyvals is prepended to the existing context, but a new error is returned.

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.

This is an alias to github.com/pkg/errors.WithStack function.

Types

type Causer

type Causer interface {
	Cause() error
}

Causer is the interface defined in github.com/pkg/errors for specifying a parent error.

type Contextor

type Contextor interface {
	Context() []interface{}
}

Contextor represents an error which holds a context.

type ErrorCollection

type ErrorCollection interface {
	Errors() []error
}

ErrorCollection holds a list of errors.

type Handler

type Handler interface {
	// Handle processes an error.
	Handle(err error)
}

Handler is responsible for handling an error.

This interface allows libraries to decouple from logging and error handling solutions.

func NewNopHandler

func NewNopHandler() Handler

NewNopHandler returns an error handler that doesn't do anything.

type MultiErrorBuilder

type MultiErrorBuilder struct {
	Message        string
	SingleWrapMode SingleWrapMode
	// contains filtered or unexported fields
}

MultiErrorBuilder provides an interface for aggregating errors and exposing them as a single value.

func NewMultiErrorBuilder

func NewMultiErrorBuilder() *MultiErrorBuilder

NewMultiErrorBuilder returns a new MultiErrorBuilder.

func (*MultiErrorBuilder) Add

func (b *MultiErrorBuilder) Add(err error)

Add adds an error to the list.

Calling this method concurrently is not safe.

func (*MultiErrorBuilder) ErrOrNil

func (b *MultiErrorBuilder) ErrOrNil() error

ErrOrNil returns a MultiError the builder aggregates a list of errors, or returns nil if the list of errors is empty.

It is useful to avoid checking if there are any errors added to the list.

type SingleWrapMode

type SingleWrapMode int

SingleWrapMode defines how MultiErrorBuilder behaves when there is only one error in the list.

const (
	AlwaysWrap   SingleWrapMode = iota // Always return a MultiError.
	ReturnSingle                       // Return the single error.
)

These constants cause MultiErrorBuilder to behave as described if there is only one error in the list.

type StackTracer

type StackTracer interface {
	StackTrace() errors.StackTrace
}

StackTracer is the interface defined in github.com/pkg/errors for exposing stack trace from an error.