Documentation
¶
Overview ¶
Example (ErrbagWrap) ¶
// This example demonstrates how to embed an ErrorBag into a type that
// implements a custom ErrorWrapper that will be called by the Wrap method.
package main
import (
"errors"
"fmt"
"toolman.org/base/errors/errbag"
)
// A custom error type that will wrap errors passed to the Wrap method.
type customError struct{ error }
// GoString implements fmt.GoStringer for the %#v format directive.
// It is employed here to ensure consistent example output.
func (c *customError) GoString() string {
return "&" + fmt.Sprintf("%T{error:%#v}", c, c.error)[1:]
}
// A custom ErrorWrapper
type wrapper struct{}
// WrapError implements errbag.ErrorWrapper
func (w *wrapper) WrapError(err error) error {
if _, ok := err.(*customError); ok {
return err
}
return &customError{err}
}
func main() {
eb := errbag.WithWrapper(&wrapper{})
err := errors.New("plain error")
ce := &customError{errors.New("custom error")}
eb.Wrap(err)
eb.Wrap(ce)
eb.Visit(func(err error) { fmt.Printf("%#v\n", err) })
}
Output: &errbag_test.customError{error:&errors.errorString{s:"plain error"}} &errbag_test.customError{error:&errors.errorString{s:"custom error"}}
Index ¶
- func Visit(err error, v Visitor)
- type ErrorBag
- func (eb *ErrorBag) Add(err error, errors ...interface{}) error
- func (eb *ErrorBag) AsError() error
- func (eb *ErrorBag) Defer(ef ErrorFunc)
- func (eb *ErrorBag) Error() string
- func (eb *ErrorBag) ErrorOrNil() error
- func (eb *ErrorBag) ErrorWrapper(wrapper ErrorWrapper)
- func (eb *ErrorBag) Errorf(msg string, a ...interface{}) error
- func (eb *ErrorBag) Errors() []error
- func (eb *ErrorBag) HasErrors() bool
- func (eb *ErrorBag) Merge(oeb *ErrorBag) error
- func (eb *ErrorBag) Return(errors ...interface{}) error
- func (eb *ErrorBag) Size() int
- func (eb *ErrorBag) Sorted() []error
- func (eb *ErrorBag) Update(errs []error) error
- func (eb *ErrorBag) Visit(v Visitor)
- func (eb *ErrorBag) Wrap(err error) error
- type ErrorFunc
- type ErrorWrapper
- type Visitor
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ErrorBag ¶
type ErrorBag struct {
// contains filtered or unexported fields
}
ErrorBag is a collector for multiple errors implemented in a fluent style (i.e. many of the methods return the ErrorBag instance upon which they were called). ErrorBag also implements Error so it is itself an error.
ErrorBag takes extra care to not add itself as one of its errors but it cannot catch all cases; e.g. a call to its Errorf method with the current ErrorBag instance as one of the interface parameters is not easily detected.
func AsErrorBag ¶
AsErrorBag attempts to reduce err to its base ErrorBag and, if so, return it. If err cannot be reduced to an ErrorBag, AsErrorBag returns nil.
func New ¶
New returns an ErrorBag. If err is nil, nil is returned. If err is already an ErrorBag, then it will be returned (as an ErrorBag). Otherwise, a new (non-wrapping) ErrorBag will be created and returned. If any values are passed as others, then each must either be an error or an ErrorFunc -- otherwize, New will panic (so, don't do that). In the former case, the error is added to the new ErrorBag while in the latter, the ErrorFunc is executed and its result (if non-nil) will be added to the returning ErrorBag. Note that ErrorFuncs passed in others will not be executed if err is nil; this makes them good targets for an io.Closer's Close method (which just happens to be an ErrorFunc (imagine that?)).
func WithWrapper ¶
func WithWrapper(wrapper ErrorWrapper) *ErrorBag
WithWrapper returns a new *ErrorBag that will use wrapper for calls to its Wrap method.
func (*ErrorBag) Add ¶
Add is used to add err to the ErrorBag eb. If err is nil, nothing is added. If err is equal to eb (or, is a type which has embedded eb) then err will not be added. However, if err is a separate and distinct instance of ErrorBag, then each of its errors will be added in turn to eb. In all cases, eb is returned, modified or not.
func (*ErrorBag) Error ¶
Error implements the error interface for the ErrorBag eb. If eb contains only 1 error, the the results of that error's Error method are returned. If eb contains more then 1 error, then a message is returned indicating how many errors it encounted; the caller should use Errors or Visit to access the contained errors. When eb contains no errors an empty string is returned.
func (*ErrorBag) ErrorOrNil ¶
ErrorOrNil returns eb if it contains any errors whatsoever, otherwise it returns nil.
func (*ErrorBag) ErrorWrapper ¶
func (eb *ErrorBag) ErrorWrapper(wrapper ErrorWrapper)
The ErrorWrapper method installs wrapper into an existing ErrorBag. Subsequent calls to its Wrap method will use the newly installed ErroWrapper. To disable future wrapping, pass a nil value to this method.
func (*ErrorBag) Errorf ¶
Errorf is a convenience function that is the same as:
eb.Add(fmt.Errorf(msgs, a...))
func (*ErrorBag) Errors ¶
Errors returns the slice of errors currently contained in the ErrorBag eb.
func (*ErrorBag) HasErrors ¶
HasErrors returns true if eb contains any errors. Otherwise it returns false.
func (*ErrorBag) Update ¶
Update calls Add for each error in errs then returns eb. Deprecated: Add now takes multiple arguments
func (*ErrorBag) Visit ¶
Visit executes the given Visitor for each error currently in the ErrorBag eb.
func (*ErrorBag) Wrap ¶
Wrap passes err to the contained ErrorWrapper's WrapError func and then adds its return value to eb in the same manner as Add. Wrap then returns eb (modified or not).
If err is nil, nothing is added and eb is returned.
As with Add, if err equals eb (or is a type that embeds eb) then err will not be added to eb. However, if err is an instance of ErrorBag but is not eb, then each of its contained errors will, in turn, be wrapped using WrapError and then added to eb.
Note that, by default, ErrorBag has no implementation of ErrorWrapper so its default behavior is equivalient to Add; to leverage Wrap, you must create an ErrorBag using the WithWrapper constructor or, if ErrorBag is embedded in aother type, you may call the ErrorWrapper method to assign a new ErrorWrapper interface to your type.
type ErrorFunc ¶
type ErrorFunc = func() error
ErrorFunc is a function that takes no arguments and returns an error. It is one of the two valid types accepted by New's others parameter.
type ErrorWrapper ¶
type ErrorWrapper interface {
// WrapError returns err optionally wrapped with a different error type.
WrapError(err error) error
}
ErrorWrapper provides WrapError for wrapping errors
Source Files