README
¶
Package cloudeng.io/errors
import cloudeng.io/errors
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: (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()
Functions
Func Annotate
func Annotate(annotation string, err error) error
Annotate returns an error representing the original error and the supplied annotation.
Func AnnotateAll
func AnnotateAll(annotation string, errs ...error) []error
AnnotateAll returns a slice of errors representing the original errors and the supplied annotation.
Func As
func As(err error, target interface{}) bool
As calls errors.As.
Func Caller
func Caller(depth, nameLen int) string
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.
Func Is
func Is(err, target error) bool
Is calls errors.Is.
Func New
func New(m string) error
New calls errors.New.
Func NewM
func NewM(errs ...error) error
NewM is equivalent to:
errs := errors.M{}
...
errs.Append(err)
...
return errs.Err()
Func Unwrap
func Unwrap(err error) error
Unwrap calls errors.Unwrap.
Func WithCaller
func WithCaller(err error) error
WithCaller returns an error annotated with the location of its immediate caller.
Func WithCallerAll
func WithCallerAll(err ...error) []error
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()
Methods
func (m *M) Append(errs ...error)
Append appends the specified errors excluding nil values.
func (m *M) As(target interface{}) bool
As supports errors.As.
func (m *M) Clone() *M
Clone returns a new errors.M that contains the same errors as itself.
func (m *M) Err() error
Err returns nil if m contains no errors, or itself otherwise.
func (m *M) Error() string
Error implements error.error
func (m *M) Format(f fmt.State, c rune)
Format implements fmt.Formatter.Format.
func (m *M) Is(target error) bool
Is supports errors.Is.
func (m *M) Squash(target error) error
Squash returns an error.M with at most one instance of target per level in the error tree.
func (m *M) Unwrap() error
Unwrap implements errors.Unwrap. It returns the first stored error and then removes that error.
Examples
ExampleCaller
ExampleWithCaller
ExampleM
ExampleM_caller
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
Source Files