errors

README

errors

errors provides utility routines for working with errors that are compatible with go 1.13+.

It currently provides:

1. errors.M which can be used to store multiple error values. errors.M is thread safe.

errs := errors.M{}
...
errs.Append(fn(a))
...
errs.Append(fn(b))
...
err := errs.Err()

Documentation

Index

• func Annotate(annotation string, err error) error
• func AnnotateAll(annotation string, errs ...error) []error
• func As(err error, target interface{}) bool
• func Caller(err error) error
• func FileLocation(depth, nameLen int) string
• func Is(err, target error) bool
• func New(m string) error
• func Unwrap(err error) error
• type M
  • func (m *M) Append(errs ...error)
  • func (m *M) As(target interface{}) 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) Unwrap() error

Examples

• Caller
• FileLocation

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(err error) error

Caller returns an error annotated with the location of its immediate caller.

Example

package main

import (
	"fmt"
	"os"

	"cloudeng.io/errors"
)

func main() {
	err := errors.Caller(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 FileLocation

func FileLocation(depth, nameLen int) string

FileLocation returns the callers 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.FileLocation(1, 1))
	fmt.Println(errors.FileLocation(1, 2))
}

Output:

caller_test.go:75
errors/caller_test.go:76

func Is

func Is(err, target error) bool

Is calls errors.Is.

func New

func New(m string) error

New calls errors.New.

func Unwrap

func Unwrap(err error) error

Unwrap calls errors.Unwrap.

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()

func (*M) Append

func (m *M) Append(errs ...error)

Append appends the specified errors excluding nil values.

func (*M) As

func (m *M) As(target interface{}) bool

As supports errors.As.

func (*M) Clone

func (m *M) Clone() *M

Clone returns a new errors.M that contains the same errors as itself.

func (*M) Err

func (m *M) Err() error

Err returns nil if m contains no errors, or itself otherwise.

func (*M) Error

func (m *M) Error() string

Error implements error.error

func (*M) Format

func (m *M) Format(f fmt.State, c rune)

Format implements fmt.Formatter.Format.

func (*M) Is

func (m *M) Is(target error) bool

Is supports errors.Is.

func (*M) Unwrap

func (m *M) Unwrap() error

Unwrap implements errors.Unwrap. It returns the first stored error and then removes that error.