multierr

package module
Version: v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 4, 2021 License: MIT Imports: 3 Imported by: 0

README

multierr

Go Reference

Provides an idiomatic Append function for errors, allowing to combine multiple errors into one.

Basically the whole API is:

err = multierr.Append(err, someFuncThatFails())
err = multierr.Append(err, anotherFuncThatFails())

Printing the error results in something like:

2 errors occurred:
(1) some failure
(2) another failure

Among other cases, this is especially useful in failable deferred funcs to avoid silently ignoring cleanup errors:

func sprinkleMagicDust() (err error) {
    d := &Dummy{}
    defer func() {
        err = multierr.Append(err, d.Close())
    }()

return d.DoSomeMagic()
}

Unlike other overly complicated multierror packages, this one does not even expose its multierror type, and will only use it when you actually end up with more than a single error to return.

The returned multierror type supports errors.Is and errors.As by delegating to each of the suberrors it contains.

License

© 2020-2021, Andrey Tarantsov. Published under the MIT License.

Documentation

Overview

Package multierr provides an idiomatic Append function for errors, allowing to combine multiple errors into one.

Basically the whole API is:

err = multierr.Append(err, someFuncThatFails())

Among other use cases, this is especially useful in failable deferred funcs to avoid silently ignoring cleanup errors:

func sprinkleMagicDust() (err error) {
	d := &Dummy{}
	defer func() {
		err = multierr.Append(err, d.Close())
	}()

	return d.DoSomeMagic()
}

Unlike many other multierror packages, this one does not even expose its multierror type, and will only use it when you actually end up with more than a single error to return.

The returned multierror type supports errors.Is and errors.As by delegating to each of the suberrors it contains.

Example
package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

func main() {
	fmt.Println(sprinkleMagicDust())

}

func sprinkleMagicDust() (err error) {
	d := &Dummy{}
	defer func() {
		err = multierr.Append(err, d.Close())
	}()

	return d.DoSomeMagic()
}

type Dummy struct{}

func (d Dummy) DoSomeMagic() error {
	return errors.New("magic not available")
}
func (d Dummy) Close() error {
	return errors.New("close: whoopsie")
}
Output:

2 errors occurred:
(1) magic not available
(2) close: whoopsie
Example (Is)
package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var (
	oops     = errors.New("oops")
	whoops   = errors.New("whoops")
	whoopsie = errors.New("whoopsie")
)

func main() {
	var err error
	err = multierr.Append(err, oops)
	err = multierr.Append(err, whoopsie)

	fmt.Println(errors.Is(err, oops))
	fmt.Println(errors.Is(err, whoops))
	fmt.Println(errors.Is(err, whoopsie))

}
Output:

true
false
true
Example (MultipleErrors)
package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var (
	oops     = errors.New("oops")
	whoops   = errors.New("whoops")
	whoopsie = errors.New("whoopsie")
)

func main() {
	var err error
	err = multierr.Append(err, oops)
	err = multierr.Append(err, whoops)
	err = multierr.Append(err, whoopsie)

	fmt.Println(err)
}
Output:

3 errors occurred:
(1) oops
(2) whoops
(3) whoopsie
Example (NilError)
package main

import (
	"fmt"

	"github.com/andreyvit/multierr"
)

func main() {
	var err error
	fmt.Println(len(multierr.All(err)))
}
Output:

0
Example (SingleError)
package main

import (
	"errors"
	"fmt"

	"github.com/andreyvit/multierr"
)

var oops = errors.New("oops")

func main() {
	var err error
	err = multierr.Append(err, oops)

	fmt.Println(err)
	fmt.Println(err == oops)
	fmt.Println(len(multierr.All(err)))
}
Output:

oops
true
1

Index

Examples

Constants

This section is empty.

Variables

View Source
var FormatMessage func(errs []error) string = DefaultFormatMessage

FormatMessage is a function used to format a string with multiple error messages. You can replace it if your project calls for a different format. Note that this is a global setting and should be left to the end user to decide.

Functions

func All

func All(err error) []error

Returns all suberrors within err. If err is not a multierror type, returns []error{err}. If err is nil, returns nil.

func Append

func Append(dest error, err error) error

Append joins the given error values into a single error. If both are non-nil, wraps them into a multierror type (which is a typed []error slice), otherwise returns one of the arguments.

Append(nil, nil) == nil
Append(nil, someErr) == someErr
Append(someErr, nil) == someErr
Append(someErr, anotherErr) == []error{someErr, anotherErr}

Either (or both) of the arguments can be multierror types, which are properly joined together. In this case, Append assumes that it's fine to modify either of the arguments.

func DefaultFormatMessage

func DefaultFormatMessage(errs []error) string

DefaultFormatMessage performs the default formatting of multiple error messages.

func ForEach

func ForEach(err error, f func(err error))

ForEach calls f with each suberror in the given error. If err is not a multierror type, calls f(err). If err is nil, does not call f.

func Len

func Len(err error) int

Returns the number of suberrors within err. If err is not a multierror type, returns 1. If err is nil, returns 0.

Types

This section is empty.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL