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 any) 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 Squash
func Squash(err error, targets ...error) error
Squash returns an error that contains at most one instance of targets per level in the error tree. If err is nil, it returns nil. If err is an *M, it calls Squash on that instance. Otherwise, it returns the original error.
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 any) 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(targets ...error) error
Squash returns an error.M with at most one instance of each of the targets per level in the error tree.
func (m *M) Unwrap() []error
Unwrap implements errors.Unwrap() []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 any) bool
- func Caller(depth, nameLen int) string
- func Is(err, target error) bool
- func New(m string) error
- func NewM(errs ...error) error
- func Squash(err error, targets ...error) error
- func Unwrap(err error) error
- func WithCaller(err error) error
- func WithCallerAll(err ...error) []error
- type M
- func (m *M) Append(errs ...error)
- func (m *M) As(target any) bool
- func (m *M) Clone() *M
- func (m *M) Err() error
- func (m *M) Error() string
- func (m *M) Format(f fmt.State, c rune)
- func (m *M) Is(target error) bool
- func (m *M) MarshalJSON() ([]byte, error)
- func (m *M) Squash(targets ...error) error
- func (m *M) Unwrap() []error
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 Squash ¶ added in v0.0.11
Squash returns an error that contains at most one instance of targets per level in the error tree. If err is nil, it returns nil. If err is an *M, it calls Squash on that instance. Otherwise, it returns the original error.
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