errors

package
v0.13.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2024 License: AGPL-3.0 Imports: 7 Imported by: 5

Documentation

Overview

Package errors provides functions to handle errors.

For better performance, all functions in this package are unsafe for concurrency unless otherwise specified.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func As 

func As(err error, target any) bool

As calls standard errors.As, but panics if target is of type *error, because As always returns true for that so that the function call is senseless.

func AutoMsg 

func AutoMsg(msg string) string

AutoMsg generates an error message by prepending the full function name (i.e., the package path-qualified function name) of its caller to msg.

If msg is empty, it uses "<no error message>" instead.

func AutoMsgCustom added in v0.4.0 

func AutoMsgCustom(msg string, ms ErrorMessageStrategy, skip int) string

AutoMsgCustom generates an error message using msg. It prepends the function or package name of the caller to msg. Caller can specify its behavior by ms.

skip is the number of stack frames to ascend, with 0 identifying the caller of AutoMsgCustom. For example, if skip is 1, instead of the caller of AutoMsgCustom, the information of that caller's caller is used.

If msg is empty, it uses "<no error message>" instead. If ms is invalid, it uses PrependFullFuncName instead.

func AutoNew 

func AutoNew(msg string) error

AutoNew creates a new error with specified error message msg, and then wraps it by prepending the full function name (i.e., the package path-qualified function name) of its caller to that error message.

If msg is empty, it uses "<no error message>" instead.

func AutoNewCustom added in v0.4.0 

func AutoNewCustom(msg string, ms ErrorMessageStrategy, skip int) error

AutoNewCustom creates a new error with specified error message msg, and then wraps it by prepending the function or package name of the caller to that error message. Caller can specify its behavior by ms.

skip is the number of stack frames to ascend, with 0 identifying the caller of AutoNewCustom. For example, if skip is 1, instead of the caller of AutoNewCustom, the information of that caller's caller is used.

If msg is empty, it uses "<no error message>" instead. If ms is invalid, it uses PrependFullFuncName instead.

func AutoWrap 

func AutoWrap(err error) error

AutoWrap wraps err by prepending the full function name (i.e., the package path-qualified function name) of its caller to the error message of err.

In particular, if err is an AutoWrappedError, AutoWrap finds the first error that is not an AutoWrappedError along the Unwrap error tree and uses its error message instead.

It returns err itself if err is nil or io.EOF (i.e., err == nil || errors.Is(err, io.EOF)).

If the target error message is empty, it uses "<no error message>" instead.

func AutoWrapCustom added in v0.4.0 

func AutoWrapCustom(
	err error,
	ms ErrorMessageStrategy,
	skip int,
	exclusions ErrorReadOnlySet,
) error

AutoWrapCustom wraps err by prepending the function or package name of the caller to the error message of err. Caller can specify its behavior by ms.

In particular, if err is an AutoWrappedError, AutoWrapCustom finds the first error that is not an AutoWrappedError along the Unwrap error tree and uses its error message instead.

skip is the number of stack frames to ascend, with 0 identifying the caller of AutoWrapCustom. For example, if skip is 1, instead of the caller of AutoWrapCustom, the information of that caller's caller is used.

exclusions are a set of errors. If err is nil or in exclusions, AutoWrapCustom returns err itself.

If the target error message is empty, it uses "<no error message>" instead. If ms is invalid, it uses PrependFullFuncName instead.

func AutoWrapSkip 

func AutoWrapSkip(err error, skip int) error

AutoWrapSkip wraps err by prepending the full function name (i.e., the package path-qualified function name) of the caller to the error message of err.

In particular, if err is an AutoWrappedError, AutoWrapSkip finds the first error that is not an AutoWrappedError along the Unwrap error tree and uses its error message instead.

skip is the number of stack frames to ascend, with 0 identifying the caller of AutoWrapSkip. For example, if skip is 1, instead of the caller of AutoWrapSkip, the information of that caller's caller is used.

It returns err itself if err is nil or io.EOF (i.e., err == nil || errors.Is(err, io.EOF)).

If the target error message is empty, it uses "<no error message>" instead.

func Combine 

func Combine(err ...error) error

Combine collects multiple non-nil errors into an error list.

It discards all nil errors.

If there is no non-nil error, it returns nil. If there is only one non-nil error, it returns this error. Otherwise, it returns an ErrorList containing all non-nil errors.

func Is 

func Is(err, target error) bool

Is directly calls standard errors.Is.

func IsAutoWrappedError added in v0.6.0 

func IsAutoWrappedError(err error) bool

IsAutoWrappedError reports whether err is an AutoWrappedError.

func Join added in v0.6.0 

func Join(errs ...error) error

Join directly calls standard errors.Join.

func ListFunctionNamesInAutoWrappedErrors added in v0.7.3 

func ListFunctionNamesInAutoWrappedErrors(err error) (
	names []string, root error)

ListFunctionNamesInAutoWrappedErrors repeatedly lists the full function name recorded in the AutoWrappedError err and unwraps err until the result is not an AutoWrappedError if err is an AutoWrappedError.

It returns the full function names and the final unwrapping result.

If err is not an AutoWrappedError, it returns nil and err itself.

func New 

func New(msg string) error

New directly calls standard errors.New.

func Unwrap 

func Unwrap(err error) error

Unwrap directly calls standard errors.Unwrap.

func UnwrapAllAutoWrappedErrors added in v0.6.0 

func UnwrapAllAutoWrappedErrors(err error) (error, bool)

UnwrapAllAutoWrappedErrors repeatedly unwraps err until the result is not an AutoWrappedError, and then returns the result and true if err is an AutoWrappedError.

If err is not an AutoWrappedError, UnwrapAllAutoWrappedErrors returns err itself and false.

func UnwrapAutoWrappedError added in v0.6.0 

func UnwrapAutoWrappedError(err error) (error, bool)

UnwrapAutoWrappedError unwraps err and returns the result and true if err is an AutoWrappedError.

Otherwise, UnwrapAutoWrappedError returns err itself and false.

Types

type AutoWrappedError added in v0.7.3 

type AutoWrappedError interface {
	ErrorUnwrap

	// Root finds and returns the first error along the Unwrap error tree
	// that is not generated by AutoWrap, AutoWrapSkip, AutoWrapCustom,
	// AutoNew, or AutoNewCustom.
	// The result is always a non-nil error.
	Root() error

	// FullFunction returns the full function name
	// (i.e., the package path-qualified function name)
	// recorded in this error.
	FullFunction() string

	// FullPackage returns the full package name recorded in this error.
	FullPackage() string

	// SimpleFunction returns the simple function name recorded in this error.
	SimpleFunction() string

	// SimplePackage returns the simple package name recorded in this error.
	SimplePackage() string

	// MessageStrategy returns the strategy for auto-generating error messages
	// used by this error.
	MessageStrategy() ErrorMessageStrategy
	// contains filtered or unexported methods
}

AutoWrappedError is the error generated by AutoWrap, AutoWrapSkip, AutoWrapCustom, AutoNew, and AutoNewCustom.

It records the information of the function that reports the error.

Its method Unwrap returns the error wrapped by AutoWrap, AutoWrapSkip, AutoWrapCustom, AutoNew, or AutoNewCustom. It is always a non-nil error.

The client cannot implement this interface.

type ErrorAs 

type ErrorAs interface {
	error

	// As finds the first error in its Unwrap error tree that matches target,
	// and if so, sets target to that error value and returns true.
	// Otherwise, it returns false.
	//
	// See errors.As for detail.
	As(target any) bool
}

ErrorAs is an error with method As, to custom the behavior of errors.As.

For more details, see <https://go.dev/blog/go1.13-errors>.

type ErrorIs 

type ErrorIs interface {
	error

	// Is reports whether any error in its Unwrap error tree matches target.
	//
	// See errors.Is for detail.
	Is(target error) bool
}

ErrorIs is an error with method Is, to custom the behavior of errors.Is.

For more details, see <https://go.dev/blog/go1.13-errors>.

type ErrorList 

type ErrorList interface {
	ErrorUnwrapMultiple

	// Len returns the number of errors in the error list.
	Len() int

	// Erroneous reports whether the error list contains non-nil errors.
	Erroneous() bool

	// ToList returns a copy of the list of errors, as type []error.
	//
	// If there is no errors in the list, it returns nil.
	ToList() []error

	// ToError returns a necessary error.
	//
	// If there is no error, it returns nil.
	// If there is only one item, it returns this item.
	// Otherwise, it returns the error list itself.
	ToError() error

	// Range calls handler on all items in the list one by one.
	//
	// handler has two parameters: i (the index of the error) and
	// err (the error value), and returns an indicator cont to report
	// whether to continue the iteration.
	Range(handler func(i int, err error) (cont bool))

	// Append appends err to the error list.
	Append(err ...error)

	// Deduplicate removes duplicate and nil errors.
	//
	// An error is regarded as duplicate if its method Error returns
	// the same string as that of a previous error.
	Deduplicate()
}

ErrorList is a list of errors, to collect multiple errors in sequence.

If it is empty, it reports "no error". If there is only one item, it performs the same as this item. If there are two or more items, it reports the number of errors, followed by an error array, in which each item is quoted.

It is designed to log errors that occur during a process and report them after exiting the process. Therefore, it only supports append operation, not delete operation.

func NewErrorList added in v0.2.0 

func NewErrorList(ignoreNil bool, err ...error) ErrorList

NewErrorList creates a new ErrorList.

ignoreNil indicates whether the ErrorList ignores nil errors. If ignoreNil is true, the ErrorList discards all nil errors.

err is errors added to the ErrorList initially.

type ErrorMessageStrategy 

type ErrorMessageStrategy int8

ErrorMessageStrategy is a strategy for auto-generating error messages. 

const (
	OriginalMsg           ErrorMessageStrategy = 1 + iota // OriginalMessage
	PrependFullFuncName                                   // PrependFullFunctionName
	PrependFullPkgName                                    // PrependFullPackageName
	PrependSimpleFuncName                                 // PrependSimpleFunctionName
	PrependSimplePkgName                                  // PrependSimplePackageName

)

Enumeration of supported error message strategies.

func (ErrorMessageStrategy) MustValid 

func (i ErrorMessageStrategy) MustValid()

MustValid panics if i is invalid. Otherwise, it does nothing.

func (ErrorMessageStrategy) String 

func (i ErrorMessageStrategy) String() string

func (ErrorMessageStrategy) Valid 

func (i ErrorMessageStrategy) Valid() bool

Valid returns true if the error message strategy is known.

Known error message strategies are shown as follows:

  • OriginalMsg: use the error message itself
  • PrependFullFuncName: add the full function name (i.e., the package path-qualified function name) before the error message
  • PrependFullPkgName: add the full package name before the error message
  • PrependSimpleFuncName: add the simple function name before the error message
  • PrependSimplePkgName: add the simple package name before the error message

type ErrorReadOnlySet added in v0.4.0 

type ErrorReadOnlySet interface {
	// Len returns the number of errors in the error set.
	Len() int

	// Contains reports whether err belongs to this error set.
	//
	// The criterion for "belong to" depends on the specific implementation.
	Contains(err error) bool

	// Range calls handler on all items in the set.
	//
	// handler has one parameter: err (the error value),
	// and returns an indicator cont to report
	// whether to continue the iteration.
	Range(handler func(err error) (cont bool))
}

ErrorReadOnlySet is a read-only set of errors.

It is designed to specify a set of errors and test whether future encountered errors belong to that set.

The criterion for "belong to" depends on the specific implementation.

func NewErrorReadOnlySetEqual added in v0.4.0 

func NewErrorReadOnlySetEqual(err ...error) ErrorReadOnlySet

NewErrorReadOnlySetEqual creates a new ErrorReadOnlySet.

The returned set regards that an error "belongs to" it if the error is equal to any item in this set.

func NewErrorReadOnlySetIs added in v0.4.0 

func NewErrorReadOnlySetIs(err ...error) ErrorReadOnlySet

NewErrorReadOnlySetIs creates a new ErrorReadOnlySet.

The returned set regards that an error err "belongs to" it if there is an item x in this set such that errors.Is(err, x) returns true.

func NewErrorReadOnlySetSameMessage added in v0.4.0 

func NewErrorReadOnlySetSameMessage(err ...error) ErrorReadOnlySet

NewErrorReadOnlySetSameMessage creates a new ErrorReadOnlySet.

The returned set regards that an error "belongs to" it if the error has the same message as any item in this set.

In particular, the message of nil error is considered "<nil>".

type ErrorUnwrap added in v0.4.0 

type ErrorUnwrap interface {
	error

	// Unwrap returns the contained error.
	// It returns nil if it contains no error.
	//
	// See errors.Unwrap for detail.
	Unwrap() error
}

ErrorUnwrap is an error with method Unwrap, to simplify working with errors that contain other errors since Go 1.13.

For more details, see <https://go.dev/blog/go1.13-errors>.

type ErrorUnwrapMultiple added in v0.6.0 

type ErrorUnwrapMultiple interface {
	error

	// Unwrap returns a list of the contained errors.
	// It permits an error to wrap multiple other errors.
	//
	// The []error returned should not contain any nil-value error.
	Unwrap() []error
}

ErrorUnwrapMultiple is an error with method Unwrap that returns multiple errors.

Since Go 1.20, the standard library expands support for error wrapping to permit an error to wrap multiple other errors. For more details, see <https://go.dev/doc/go1.20#errors>.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.