Documentation ¶
Overview ¶
Package errors provides utility routines for working with errors that are compatible with go 1.13+ and for annotating errors. It provides errors.M which can be used to collect and work with multiple errors in a thread safe manner. It also provides convenience routines for annotating existing errors with caller and other information.
errs := errors.M{} errs.Append(fn(a)) errs.Append(fn(b)) err := errs.Err()
The location of a function's immediate caller (depth of 1) in form of the directory/filename:<line> (name len of 2) can be obtained as follows:
errors.Caller(1, 2)
Annotations, can be added as follows:
err := errors.WithCaller(os.ErrNotExist)
Where:
fmt.Printf("%v\n", err) fmt.Printf("%v\n", errors.Unwrap(err))
Would produce:
errors/caller_test.go:17: file does not exist file does not exist
Annotated errors can be passed to errors.M:
errs := errors.M{} errs.Append(errors.WithCaller(fn(a))) errs.Append(errors.WithCaller(fn(b))) err := errs.Err()
Index ¶
- func Annotate(annotation string, err error) error
- func AnnotateAll(annotation string, errs ...error) []error
- func As(err error, target interface{}) bool
- func Caller(depth, nameLen int) string
- func Is(err, target error) bool
- func New(m string) error
- func NewM(errs ...error) error
- func Unwrap(err error) error
- func WithCaller(err error) error
- func WithCallerAll(err ...error) []error
- type M
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Annotate ¶ added in v0.0.3
Annotate returns an error representing the original error and the supplied annotation.
func AnnotateAll ¶ added in v0.0.3
AnnotateAll returns a slice of errors representing the original errors and the supplied annotation.
func Caller ¶ added in v0.0.3
Caller returns the caller's location as a filepath and line number. Depth follows the convention for runtime.Caller. The filepath is the trailing nameLen components of the filename returned by runtime.Caller. A nameLen of 2 is generally the best compromise between brevity and precision since it includes the enclosing directory component as well as the filename.
Example ¶
package main import ( "fmt" "cloudeng.io/errors" ) func main() { fmt.Println(errors.Caller(1, 1)) fmt.Println(errors.Caller(1, 2)) }
Output: caller_test.go:38 errors/caller_test.go:39
func NewM ¶ added in v0.0.8
NewM is equivalent to:
errs := errors.M{} ... errs.Append(err) ... return errs.Err()
func WithCaller ¶ added in v0.0.5
WithCaller returns an error annotated with the location of its immediate caller.
Example ¶
package main import ( "fmt" "os" "cloudeng.io/errors" ) func main() { err := errors.WithCaller(os.ErrNotExist) fmt.Printf("%v\n", err) fmt.Printf("%v\n", errors.Unwrap(err)) }
Output: errors/caller_test.go:17: file does not exist file does not exist
func WithCallerAll ¶ added in v0.0.5
WithCallerAll returns a slice conntaing annotated versions of all of the supplied errors.
Types ¶
type M ¶
type M struct {
// contains filtered or unexported fields
}
M represents multiple errors. It is thread safe. Typical usage is:
errs := errors.M{} ... errs.Append(err) ... return errs.Err()
Example ¶
package main import ( "fmt" "os" "cloudeng.io/errors" ) func main() { m := &errors.M{} fmt.Println(m.Err()) m.Append(os.ErrExist) m.Append(os.ErrInvalid) fmt.Println(m.Err()) }
Output: <nil> --- 1 of 2 errors file already exists --- 2 of 2 errors invalid argument
Example (Caller) ¶
package main import ( "fmt" "os" "cloudeng.io/errors" ) func main() { m := &errors.M{} m.Append(errors.WithCaller(os.ErrExist)) m.Append(errors.WithCaller(os.ErrInvalid)) fmt.Println(m.Err()) }
Output: --- 1 of 2 errors errors/caller_test.go:27: file already exists --- 2 of 2 errors errors/caller_test.go:28: invalid argument