Categorygithub.com/go-pogo/errors
modulepackage
0.11.1
Repository: https://github.com/go-pogo/errors.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
10
Dependents
33
Files
842 SLOC

# README

errors

Latest release Build status Go Report Card Documentation

Package errors contains additional functions, interfaces and structs for recording stack frames, applying basic formatting, working with goroutines, multiple errors and custom error types.

It is inspired by package golang.org/x/xerrors and is designed to be a drop-in replacement for it, as well as the standard library's errors package.

The errors.New and errors.Errorf functions create errors whose content is a text message and whom can trace stack frames. errors.Wrap and errors.Wrapf create errors by wrapping an existing error with a similar error like errors.New and errors.Errorf.

go get github.com/go-pogo/errors

import "github.com/go-pogo/errors"

Msg

Instead of defining error messages as global variables, it is possible to define them as constants using errors.Msg.

const ErrSomethingWentWrong errors.Msg = "something went wrong"

Formatting

Wrap an existing error with errors.WithFormatter to upgrade the error to include basic formatting. Formatting is done using xerrors.FormatError and thus the same verbs are supported. Any error created with this package implements the fmt.Formatter and xerrors.Formatter interfaces.

fmt.Printf("%+v", errors.WithFormatter(err))

Stack tracing

Every error can track stack trace information. Just wrap it with errors.WithStack and a complete stack trace is captured.

err = errors.WithStack(err)

An errors.StackTrace can be retrieved using errors.GetStackTrace. Printing the error results in a trace similar to:

invalid character 'i' looking for beginning of value:
	github.com/go-pogo/errors.ExampleWithStack
		/path/to/errors/examples_trace_test.go:43
	github.com/go-pogo/errors.ExampleWithStack.func1
		/path/to/errors/examples_trace_test.go:40

Disable stack tracing

Stack tracing comes with a performance cost. For production environments this cost can be undesirable. To disable stack tracing, compile your Go program with the "notrace" tag.

go build -tags=notrace

Catching panics

A convenient function is available to catch panics and store them as an error.

var err error
defer errors.CatchPanic(&err)

Backwards compatibility

Unwrap, Is and As are backwards compatible with the standard library's errors package and act the same.

Documentation

Additional detailed documentation is available at pkg.go.dev

Created with

License

Copyright © 2019-2024 Roel Schut. All rights reserved.

This project is governed by a BSD-style license that can be found in the LICENSE file.

# Packages

No description provided by the author
No description provided by the author

# Functions

Append creates a multi error from two non-nil errors.
AppendFunc appends the non-nil error result of fn to dest using AppendInto.
AppendInto appends multiple non-nil errors to a single multi error dest.
As is an alias of errors.As.
CatchPanic recovers from a panic and wraps it in an error.
Cause walks through all wrapped errors and returns the last error in the chain.
Errorf formats an error message according to a format specifier and provided arguments with fmt.Errorf, and creates a new error similar to New.
FatalOnErr prints the error to stderr and exits the program with an exit code that is not 0.
Filter returns a slice of errors without nil values in between them.
FormatError calls the FormatError method of err with a Printer configured according to state and verb, and writes the result to state.
GetExitCode returns an exit status code if the error implements the ExitCoder interface.
GetExitCodeOr returns the exit status code from the first found ExitCoder in err's error chain.
GetStackTrace returns a *StackTrace if err is a StackTracer or nil otherwise.
GetStatusCode returns the status code if the error implements the StatusCoder interface.
GetStatusCodeOr returns the status code from the first found StatusCoder in err's error chain.
GetTime returns the time.Time of the last found Timer in err's error chain.
Is reports whether any error in err's chain matches target.
IsCause indicates if error is the root cause of a possible error chain.
Join returns a MultiError when more than one non-nil errors are provided.
Must panics when any of the given args is a non-nil error.
New creates a new error which implements the StackTracer, Wrapper and Formatter interfaces.
Newf formats an error message according to a format specifier and provided arguments.
Opaque is an alias of xerrors.Opaque.
PanicOnErr panics when err is not nil.
PrintError prints the error err with the provided Printer and formats and prints the error's stack frames.
PrintFrames prints a complete stack of *runtime.Frames using Printer p.
Unembed recursively unwraps all Embedder errors and returns the (original) error that was wrapped with extra context.
Unwrap is an alias of errors.Unwrap.
UnwrapAll returns the complete chain of errors, starting with the supplied error and ending with the root cause error.
WithExitCode adds an exit status code to the error which may indicate a fatal error.
WithFormatter wraps the error with a Formatter that is capable of basic error formatting.
WithStack gets a stack trace at the point WithStack was called and adds it to the error.
WithStatusCode adds a (http) status code to the error which can be retrieved using GetStatusCode and may be set to a http.ResponseWriter.
WithTime adds time information to the error.
Wrap creates a new error, which implements the StackTracer, Wrapper and Formatter interfaces, that wraps around the causing error.
Wrapf formats an error message according to a format specifier and provided arguments with fmt.Errorf, and creates a new error similar to Wrap.
WrapPanic wraps a panicking sequence with the given prefix.

# Structs

No description provided by the author

# Interfaces

An Embedder unwraps an embedded error.
ExitCoder interfaces provide access to an exit code.
ExitCoderSetter interfaces provide access to an exit code which can be changed.
MultiError is an error which unwraps into multiple underlying errors.
StackTracer interfaces provide access to a stack of traced StackTrace.
StatusCoder interfaces provide access to a (http) status code.
No description provided by the author
Timer interfaces provide access to a time.Time indicating when the error occurred.
No description provided by the author
A Wrapper provides context around another error, which can be retrieved with Unwrap.

# Type aliases

A Formatter formats error messages and prints them to a Printer.
No description provided by the author
Msg is a string alias which can also be used as a basic error.
A Printer prints a formatted error.