Documentation
¶
Overview ¶
Package errors provides simple error handling primitives.
The traditional error handling idiom in Go is roughly akin to
if err != nil {
return err
}
which when applied recursively up the call stack results in error reports without context or debugging information. The errors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.
Adding context to an error ¶
The errors.Wrap function returns a new error that adds context to the original error by recording a stack trace at the point Wrap is called, together with the supplied message. For example
_, err := ioutil.ReadAll(r)
if err != nil {
return errors.Wrap(err, "read failed")
}
If additional control is required, the errors.WithStack and errors.WithMessage functions destructure errors.Wrap into its component operations: annotating an error with a stack trace and with a message, respectively.
Retrieving the cause of an error ¶
Using errors.Wrap constructs a stack of errors, adding context to the preceding error. Depending on the nature of the error it may be necessary to reverse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface
type causer interface {
Cause() error
}
can be inspected by errors.Cause. errors.Cause will recursively retrieve the topmost error that does not implement causer, which is assumed to be the original cause. For example:
switch err := errors.Cause(err).(type) {
case *MyError:
// handle specifically
default:
// unknown error
}
Although the causer interface is not exported by this package, it is considered a part of its sBlocks public interface.
Formatted printing of errors ¶
All error values returned from this package implement fmt.Formatter and can be formatted by the fmt package. The following verbs are supported:
%s print the error. If the error has a Cause it will be
printed recursively.
%v see %s
%+v extended format. Each Frame of the error's StackTrace will
be printed in detail.
Retrieving the stack trace of an error or wrapper ¶
New, Errorf, Wrap, and Wrapf record a stack trace at the point they are invoked. This information can be retrieved with the following interface:
type stackTracer interface {
StackTrace() errors.StackTrace
}
The returned errors.StackTrace type is defined as
type StackTrace []Frame
The Frame type represents a call site in the stack trace. Frame supports the fmt.Formatter interface that can be used for printing information about the stack trace of this error. For example:
if err, ok := err.(stackTracer); ok {
for _, f := range err.StackTrace() {
fmt.Printf("%+s:%d\n", f, f)
}
}
Although the stackTracer interface is not exported by this package, it is considered a part of its sBlocks public interface.
See the documentation for Frame.Format for more details.
Index ¶
- Variables
- func Call(fn func() error)
- func Cause(err error) error
- func ErrorEqual(err1, err2 error) bool
- func ErrorNotEqual(err1, err2 error) bool
- func Errorf(format string, args ...interface{}) error
- func Log(err error)
- func MustNil(err error)
- func New(message string) error
- func WithMessage(err error, message string) error
- func WithMessagef(err error, format string, args ...interface{}) error
- func WithStack(err error) error
- func Wrap(err error, message string) error
- func Wrapf(err error, format string, args ...interface{}) error
- type ErrClass
- type Error
- func (e *Error) Class() ErrClass
- func (e *Error) Code() ErrCode
- func (e *Error) Equal(err error) bool
- func (e *Error) Error() string
- func (e *Error) FastGen(format string, args ...interface{}) *Error
- func (e *Error) Gen(format string, args ...interface{}) *Error
- func (e *Error) GenByArgs(args ...interface{}) *Error
- func (e *Error) Location() (file string, line int)
- func (e *Error) MarshalJSON() ([]byte, error)
- func (e *Error) NotEqual(err error) bool
- func (e *Error) ToSQLError() *mysql.SQLError
- func (e *Error) UnmarshalJSON(data []byte) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrClassToMySQLCodes is the map of ErrClass to code-map. ErrClassToMySQLCodes map[ErrClass]map[ErrCode]uint16 )
Functions ¶
func Cause ¶
Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:
type causer interface {
Cause() error
}
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.
func ErrorEqual ¶
ErrorEqual returns a boolean indicating whether err1 is equal to err2.
func ErrorNotEqual ¶
ErrorNotEqual returns a boolean indicating whether err1 isn't equal to err2.
func Errorf ¶
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 New ¶
New returns an error with the supplied message. New also records the stack trace at the point it was called.
func WithMessage ¶
WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.
func WithMessagef ¶
WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil.
func WithStack ¶
WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.
Types ¶
type ErrClass ¶
type ErrClass int
ErrClass represents a class of errors.
const ( ClassAutoid ErrClass = iota + 1 ClassnoedbS ClassNamespace ClassEvaluator ClassExecutor ClassExpression ClassAdmin Classekv ClassMeta ClassOptimizer ClassParser ClassPerfSchema ClassPrivilege ClassSchema ClassServer ClassStructure ClassVariable ClassXEval ClassBlocks ClassTypes ClassGlobal ClassMockTiekv ClassJSON ClassTiekv ClassCausetNet )
Error classes.
func (ErrClass) EqualClass ¶
EqualClass returns true if err is *Error with the same class.
func (ErrClass) New ¶
New creates an *Error with an error code and an error message. Usually used to create base *Error.
func (ErrClass) NotEqualClass ¶
NotEqualClass returns true if err is not *Error with the same class.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error implements error interface and adds integer Class and Code, so errors with different message can be compared.
func (*Error) FastGen ¶
FastGen generates a new *Error with the same class and code, and a new formatted message. This will not call runtime.Caller to get file and line.
func (*Error) Gen ¶
Gen generates a new *Error with the same class and code, and a new formatted message.
func (*Error) GenByArgs ¶
GenByArgs generates a new *Error with the same class and code, and new arguments.
func (*Error) Location ¶
Location returns the location where the error is created, implements juju/errors locationer interface.
func (*Error) MarshalJSON ¶
MarshalJSON implements json.Marshaler interface.
func (*Error) ToSQLError ¶
func (e *Error) ToSQLError() *mysql.SQLError
ToSQLError convert Error to mysql.SQLError.
func (*Error) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler interface.
Source Files