Documentation
¶
Overview ¶
A concise error handling package that provides the mechanisms for creating a "root" error that is a basic instance of String/Uint/Int, and the ability to add stacktrace and context to the root error. Existing "root" errors already present in the Go standard library can be used equally well.
Ideally, following properties are desired:
- uniquely-identifying error instances
- constant/read-only instances, i.e. can be addressed but not changed
- composable/extendable into dedicated error type/series for specific use cases (without overhead)
TODO above three properties cannot be satisfied yet. TODO do we need predefined errors? Errors such as `os.ErrInvalid` are defined specifically for the filesystem use-case. However, we need generic errors representing the various classes of incorrectness.
Index ¶
- Variables
- func Aggregate(cause error, message string, errs ...error) error
- func As(err error, target any) bool
- func Context(cause error, message string) error
- func Is(err error, target error) bool
- func IsAny(err error, targets []error) bool
- func JoinMessages(errs []error, sep string) string
- func Stack(err error) []byte
- func Stacktrace(cause error) error
- func Unwrap(err error) error
- type IntError
- type StringError
- type UintError
Constants ¶
This section is empty.
Variables ¶
var ErrBug = NewStringError("BUG: this error should not have happened")
ErrBug indicates that an error occurred that should not have happened, for example if an unreachable state is reached.
var ErrFailure = NewStringError("failure during processing")
ErrFailure indicates that there was a processing failure.
var ErrIllegal = NewStringError("illegal value")
ErrIllegal indicates an illegal/bad value(s) for provided parameter(s).
var ErrInternalState = NewStringError("illegal state")
ErrInternalState indicates a problem with internal state, or use while in incorrect state.
var ErrOverflow = NewStringError("overflowing")
ErrOverflow indicates that the operation causes an overflow of some kind.
var ErrUnderflow = NewStringError("underflowing")
ErrUnderflow indicates that stack is empty, either at present or after the operation.
var ErrUnsupported = NewStringError("unsupported")
ErrUnsupported indicates that an error occurred because of an unsupported operation or value.
Functions ¶
func Aggregate ¶
Aggregate creates a context for a root cause, based on any number of errors. TODO consider if we need to embed the actual errors. This touches on a tangential consideration: how to handle errors crossing abstraction boundaries. Do we want to make them available, i.e. leak the abstraction?
func As ¶
As offers `errors.As` functionality for when applicable. This function is a direct pass-through for convenience.
func Context ¶
Context wraps an error to provide additional context information. TODO consider defining different variations of context: with-message, with-key-values-pairs, ... We can consider this basic context type as key-value pair with key 'message'. Then as we extract key-value pairs, we can include base contexts.
func Is ¶
Is repeatedly unwraps an error and compares to target on each unwrapping. Is uses the implementation from std/errors.
func JoinMessages ¶
JoinMessages joins the error messages of each error, using the provided separator.
func Stack ¶
Stack extracts the first stacktrace encountered in a wrapped error, or nil if no stack is present/found. It is assumed that, generally, at most one stacktrace is present.
func Stacktrace ¶
Types ¶
type IntError ¶
type IntError struct {
// contains filtered or unexported fields
}
IntError as a base type for const errors.
Similar to StringError, this type can be used to declare const errors. This type is based on int, therefore most suitable for errors that are signaled through a numeric code, such as with HTTP-like protocols.
func NewIntError ¶
NewIntError creates a new int-based error instance. If used as-is, the pointer that is returned is uniquely-identifying and therefore immediately useable. In case the IntError is a basis for a custom error type, the pointer can be dereferenced to include the value itself in the newly defined struct-type, for efficiency.
type StringError ¶
type StringError struct {
// contains filtered or unexported fields
}
StringError as a base type for const errors.
This type is intended to be used as replacement for errors.New(..) from std, such that you can define an error as const (constant). The idea being that the "root" error type is just the type and the circumstances within which the error occurs are dictated by any number of contexts wrapped around the root error.
func NewStringError ¶
func NewStringError(msg string) *StringError
NewStringError creates a new string-based error instance. If used as-is, the pointer that is returned is uniquely-identifying and therefore immediately useable. In case the StringError is a basis for a custom error type, the pointer can be dereferenced to include the value itself in the newly defined struct-type, for efficiency.
func (*StringError) Error ¶
func (e *StringError) Error() string
type UintError ¶
type UintError struct {
// contains filtered or unexported fields
}
UintError as a base type for const errors.
Similar to StringError, this type can be used to declare const errors. This type is based on uint therefore is most suitable for errors that are signaled through a numeric code, such as with HTTP-like protocols.
func NewUintError ¶
NewUintError creates a new uint-based error instance. If used as-is, the pointer that is returned is uniquely-identifying and therefore immediately useable. In case UintError is a basis for a custom error type, the pointer can be dereferenced as to include the value itself in the newly defined struct-type, for efficiency.
Source Files