Documentation ¶
Overview ¶
Package emperror provides error handling solutions and tools for libraries and applications.
Index ¶
- func Context(err error) []interface{}
- func ExposeStackTrace(err error) error
- func ForEachCause(err error, fn func(err error) bool)deprecated
- func Handle(handler Handler, err error)
- func HandleRecover(handler Handler)
- func Panic(err error)
- func Recover(r interface{}) (err error)
- func With(err error, keyvals ...interface{}) error
- func Wrap(err error, message string) error
- func WrapWith(err error, message string, keyvals ...interface{}) error
- func Wrapf(err error, format string, args ...interface{}) error
- type ContextAwareHandler
- type ErrorMatcher
- type Errors
- type Handler
- func HandlerWith(handler Handler, keyvals ...interface{}) Handler
- func HandlerWithDetails(handler Handler, details ...interface{}) Handler
- func HandlerWithPrefix(handler Handler, keyvals ...interface{}) Handler
- func NewCompositeHandler(handlers ...Handler) Handler
- func NewNoopHandler() Handler
- func WithDetails(handler Handler, details ...interface{}) Handler
- func WithFilter(handler Handler, matcher ErrorMatcher) Handler
- type HandlerFunc
- type Handlers
- type MultiErrorBuilder
- type SingleWrapMode
- type TestHandler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Context ¶ added in v0.8.0
func Context(err error) []interface{}
Context extracts the context key-value pairs from an error (or error chain). Deprecated: use emperror.dev/errors.GetDetails instead.
func ExposeStackTrace ¶ added in v0.8.0
ExposeStackTrace exposes the stack trace (if any) in the outer error.
func ForEachCause
deprecated
added in
v0.8.0
func HandleRecover ¶ added in v0.1.1
func HandleRecover(handler Handler)
HandleRecover recovers from a panic and handles the error.
defer emperror.HandleRecover(errorHandler)
func Panic ¶ added in v0.15.0
func Panic(err error)
Panic panics if the passed error is not nil. If the error does not contain any stack trace, the function attaches one, starting from the frame of the "Panic" function call.
This function is useful with HandleRecover when panic is used as a flow control tool to stop the application.
func Recover ¶ added in v0.1.1
func Recover(r interface{}) (err error)
Recover accepts a recovered panic (if any) and converts it to an error (if necessary).
func With ¶ added in v0.5.0
With returns a new error with keyvals context appended to it. If the wrapped error is already a contextual error created by With keyvals is appended to the existing context, but a new error is returned. Deprecated: use emperror.dev/errors.WithDetails instead.
func Wrap ¶ added in v0.11.0
Wrap returns an error annotating err with a stack trace at the point Wrap is called (if there is none attached to the error yet), and the supplied message. If err is nil, Wrap returns nil.
Note: do not use this method when passing errors between goroutines. Deprecated: use emperror.dev/errors.WrapIf instead.
func WrapWith ¶ added in v0.12.0
WrapWith returns an error annotating err with a stack trace at the point Wrap is called (if there is none attached to the error yet), the supplied message, and the supplied context. If err is nil, Wrap returns nil.
Note: do not use this method when passing errors between goroutines. Deprecated: use emperror.dev/errors.WrapIfWithDetails instead.
func Wrapf ¶ added in v0.11.0
Wrapf returns an error annotating err with a stack trace at the point Wrapf is call (if there is none attached to the error yet), and the format specifier. If err is nil, Wrapf returns nil.
Note: do not use this method when passing errors between goroutines. Deprecated: use emperror.dev/errors.WrapIff instead.
Types ¶
type ContextAwareHandler ¶ added in v0.21.2
type ContextAwareHandler interface { // Handle handles an error. Handle(ctx context.Context, err error) }
ContextAwareHandler is similar to Handler, except it receives a context as well. It is useful in request terminal error handling situations. An implementation MAY extract information from the context and annotate err with it.
func MakeContextAware ¶ added in v0.21.2
func MakeContextAware(handler Handler) ContextAwareHandler
MakeContextAware wraps an error handler and turns it into a ContextAwareHandler.
type ErrorMatcher ¶ added in v0.22.0
type ErrorMatcher interface { // MatchError checks if err matches a certain condition. MatchError(err error) bool }
ErrorMatcher checks if an error matches a certain condition.
type Errors ¶ added in v0.18.0
type Errors interface { // Errors returns the list of wrapped errors. Errors() []error }
Errors is responsible for listing multiple errors. Deprecated: use multi error tools from emperror.dev/errors instead.
type Handler ¶
type Handler interface { // Handle handles an error. Handle(err error) }
Handler is a generic error handler. It allows applications (and libraries) to handle errors without worrying about the actual error handling strategy (logging, error tracking service, etc).
func HandlerWith ¶ added in v0.7.0
HandlerWith returns a new error handler with keyvals context appended to it. If the wrapped error handler is already a contextual error handler created by HandlerWith or HandlerWithPrefix keyvals is appended to the existing context, but a new error handler is returned.
The created handler will prepend it's own context to the handled errors. Deprecated: use WithDetails instead.
func HandlerWithDetails ¶ added in v0.21.0
HandlerWithDetails returns a new error handler annotated with key-value pairs.
The created handler will add it's own details to the handled errors. Deprecated: use WithDetails instead.
func HandlerWithPrefix ¶ added in v0.7.0
HandlerWithPrefix returns a new error handler with keyvals context prepended to it. If the wrapped error handler is already a contextual error handler created by HandlerWith or HandlerWithPrefix keyvals is prepended to the existing context, but a new error handler is returned.
The created handler will prepend it's own context to the handled errors. Deprecated: no replacement at this time.
func NewCompositeHandler ¶
NewCompositeHandler returns a new compositeHandler. Deprecated: use Handlers instead.
func NewNoopHandler ¶ added in v0.16.0
func NewNoopHandler() Handler
NewNoopHandler creates a no-op error handler that discards all received errors. Useful in examples and as a fallback error handler.
func WithDetails ¶ added in v0.21.1
WithDetails returns a new error handler that annotates every error with a set of key-value pairs.
func WithFilter ¶ added in v0.22.0
func WithFilter(handler Handler, matcher ErrorMatcher) Handler
WithDetails returns a new error handler that discards errors matching any of the specified filters. Otherwise it passes errors to the next handler.
Example ¶
err := errors.New("no more errors") isErr := errors.New("is") type asError struct { error } asErr := asError{errors.New("as")} handler := WithFilter( HandlerFunc(func(err error) { fmt.Println(err) }), match.Any{ match.Is(isErr), match.As(&asError{}), }, ) handler.Handle(err) handler.Handle(isErr) handler.Handle(asErr)
Output: no more errors
type HandlerFunc ¶ added in v0.5.0
type HandlerFunc func(err error)
HandlerFunc wraps a function and turns it into an error handler.
func (HandlerFunc) Handle ¶ added in v0.5.0
func (h HandlerFunc) Handle(err error)
Handle calls the underlying function.
type Handlers ¶ added in v0.20.0
type Handlers []Handler
Handlers collects a number of error handlers into a single one.
type MultiErrorBuilder ¶ added in v0.5.0
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. Deprecated: use multi error tools from emperror.dev/errors instead.
func NewMultiErrorBuilder ¶ added in v0.5.0
func NewMultiErrorBuilder() *MultiErrorBuilder
NewMultiErrorBuilder returns a new MultiErrorBuilder.
func (*MultiErrorBuilder) Add ¶ added in v0.5.0
func (b *MultiErrorBuilder) Add(err error)
Add adds an error to the list.
Calling this method concurrently is not safe.
func (*MultiErrorBuilder) ErrOrNil ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 TestHandler ¶
type TestHandler struct {
// contains filtered or unexported fields
}
TestHandler is a simple stub for the handler interface recording every error.
The TestHandler is safe for concurrent use.
func (*TestHandler) Count ¶ added in v0.16.0
func (h *TestHandler) Count() int
Count returns the number of events recorded in the logger.
func (*TestHandler) Errors ¶
func (h *TestHandler) Errors() []error
Errors returns all handled errors.
func (*TestHandler) LastError ¶ added in v0.16.0
func (h *TestHandler) LastError() error
LastError returns the last handled error (if any).