README
¶
errors
This is a replacement package for the stdlib errors package.
It provides the same interface (which is really just the New() function) as
well as a number of functions and types for adding context to errors and
extracting that context information.
Types
Here
The Here() function wraps an error with information about the current code
location as the file:line. This allows later tools that print out the error
to show where the error bubbled up from.
Cause
The Cause() function wraps 2 errors. The idea here is that when a lowlevel
error is detected, you wrap a highlevel error attached the lowlevel error, like
Cause(New("something bad happened"), networkErr). This allows code
that prints things out to see what these highlevel errors were derived.
Trace
The "Big Kahuna" of context types. Wraps an error with the stacktrace about the current goroutine.
Context
Allows for an error to be decorated with a string describing the context
of the error. This is intented to be used instead of using
fmt.Errorf("while running wild: %s", err) because it preserves the ability
check the original error.
Subject
Allows a subject to be attached to an error. An example of this would be the
ability to indicate an error with a specific file path:
given err = ErrNotFound, Subject(err, path). Similar to context, the idea
is the ability to attach additional information to the error without destroying
the ability to compare against it later.
Functions
Equal
Compares 2 errors smartly. It removes any wrappers defined in this package, allowing for comparison against true base errors without the wrappers changing the ability to detect them.
For instance, given a function that does return Here(ErrNotExist), it's possible
to detect this specific error by doing Equal(f(), ErrNotExist).
Use Print() to convert an error into a byte stream to be shown to the user. This
function understands the above types and shows their context information.
Show
A convience for using Print() on os.Stderr
Details
Creates a map[string]string with information about the error. This understands
the above types and adds the context information. This is very useful for sending
errors as structured text, such as json.
For example: json.NewEncoder(rw).Encode(errors.Details(err)) to send an
errors as nicely formatted json over a net.ResponseWritter.
EOF
This function seems a little out of place, but it fills an important niche. The
go stdlib does not collapse errors that represent a closed network connection
into io.EOF. As a result, detecting that a connection was closed requires
odd code at best. EOF() attempts to wrap this checking with platform specific
code to be able to detect lowlevel syscall.Errno type errors that represent
closure and indicate that they are in fact EOFs.
This function returns a boolean rather than collapsing to io.EOF to make it's
usage simple: if errors.EOF(networkErr) { .... }
Documentation
¶
Index ¶
- func Cause(err error, cause error) error
- func Context(err error, ctx string) error
- func Details(err error) map[string]string
- func EOF(err error) bool
- func Equal(err1, err2 error) bool
- func Format(f string, val ...interface{}) error
- func Here(orig error) error
- func Print(err error, out io.Writer)
- func Show(err error)
- func Subject(err error, sub interface{}) error
- func Trace(err error) error
- func Unwrap(err error) error
- type CauseError
- type ContextError
- type ErrorString
- type HereError
- type SubjectError
- type TraceError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Details ¶
Derive a map of detailed information about an error. For HereErrors, map includes a "location" key For CauseErrors, map includes one or more "cause" keys For TraceErrors, map includes a "trace" key For ContextErrors, map includes a "context" key For SubjectErrors, map includes a "subject" key
func Print ¶
Print out the information within err to out. This understands errors that use Here, Cause, and Trace.
Types ¶
type CauseError ¶
type CauseError struct {
// contains filtered or unexported fields
}
Contains 2 errors, an updated error and a causing error
type ContextError ¶
type ContextError struct {
// contains filtered or unexported fields
}
Adds a string describing the context of this error without changing the underlying error itself.
func (*ContextError) Context ¶
func (c *ContextError) Context() string
func (*ContextError) Error ¶
func (c *ContextError) Error() string
Return a string containing the context as well as the underlying error
type ErrorString ¶
type ErrorString struct {
// contains filtered or unexported fields
}
ErrorString is a trivial implementation of error.
func (*ErrorString) Error ¶
func (e *ErrorString) Error() string
type HereError ¶
type HereError struct {
// contains filtered or unexported fields
}
HereError wraps another error with location information
func (*HereError) FullLocation ¶
Return the full path and line information for the location
type SubjectError ¶
type SubjectError struct {
// contains filtered or unexported fields
}
Attaches a subject to an error. An example would be failing to open a file, the path of the file could be added as the subject to be shown or retrieved later.
func (*SubjectError) Error ¶
func (c *SubjectError) Error() string
Return a string containing the context as well as the underlying error This uses fmt.Sprintf's %s to convert the subject to a string.
func (*SubjectError) Subject ¶
func (c *SubjectError) Subject() interface{}
Return the subject of the error
type TraceError ¶
type TraceError struct {
// contains filtered or unexported fields
}
Contains an error and a stacktrace
Source Files