errslice

README

errslice

errslice is a Go package for handling multiple errors and returning them to callers that may not be aware they're dealing with more than one.

Usage

go get sethwklein.net/errslice

import "sethwklein.net/errslice"

https://godoc.org/sethwklein.net/errslice

Rationale

When writing a file, either Write or Close may return an error. While Unix files don't, technically nothing stops some weird io.WriteCloser from returning interesting and unique errors from both. This library makes it trivial to just return however many errors you get. It also comes in handy in a surprising number of situations where you want to return all the errors, not just the first. Your callers need not be aware that they may be receiving more than one error, although they can be.

History

This is the fourth iteration of this concept.

The first was an experiment in an unreleased project. I liked it enough to release the second.

The second was a drop in replacement for the standard errors package. This was unpopular with the community, confusing, and an extra maintenance burden so I dropped it to get the third.

The third hid the implementation in an opaque type. Experience using it revealed few advantages and the occasional case where I had to reimplement it using a plain old slice.

Hence this, fourth, version that just uses a good old fashioned slice.

Documentation

Overview

Package errslice is for working with multiple errors, especially for returning them to callers that may be expecting only one.

See the AppendCall example for typical usage.

Index

• func Append(errs ...error) error
• func AppendCall(errp *error, f func() error)
• type Slice
  • func From(err error) Slice
  • func FromFast(err error) Slice
  • func (errs Slice) Error() string
• Bugs

Examples

• AppendCall

Functions

func Append

func Append(errs ...error) error

Append concatenates errors and Slices, dropping nils. It flattens Slices, but not recursively. If not passed at least one non-nil argument, it will return nil, and if passed only one non-nil argument, it will return that one, unchanged.

func AppendCall

func AppendCall(errp *error, f func() error)

AppendCall calls appends the result of calling f to errp. AppendCall is useful when deferring calls that return an error.

Example

package main

import (
	"errors"
	"fmt"
	"io"
	"os"

	"sethwklein.net/errslice"
)

type angryWriteCloser struct{}

func (_ angryWriteCloser) Write(b []byte) (int, error) {
	return 0, errors.New("no writing!")
}
func (_ angryWriteCloser) Close() error {
	return errors.New("no closing!")
}

// BE CAREFUL! The return value must be named. Else the error returned from the
// deferred call will be silently discarded with no compiler error.

func exampleWrite(w io.WriteCloser) (err error) {
	defer errslice.AppendCall(&err, w.Close)

	for c := byte('a'); c <= 'z'; c++ {
		_, err = w.Write([]byte{c})
		if err != nil {
			return err
		}
	}
	return nil
}

func main() {
	err := exampleWrite(angryWriteCloser{})
	for _, e := range errslice.From(err) {
		// In real code, use os.Stderr, but that's broken in examples.
		fmt.Fprintln(os.Stdout, "Error:", e)
	}
}

Output:

Error: no writing!
Error: no closing!

Types

type Slice

type Slice []error

Slice is a []error that implements error.

func From

func From(err error) Slice

From wraps err in a Slice unless it already is a Slice or []error by another name, in which case it returns it unaltered or uses reflection to convert it to a Slice, respectively. If err is nil, From returns nil.

From is useful for iterating over errors, such as when printing them. See AppendCall's example for typical usage.

func FromFast

func FromFast(err error) Slice

FromFast is a like From but trades away detection of []errors named something other than Slice to gain performance.

func (Slice) Error

func (errs Slice) Error() string

Error implements error. Better results are generally achieved by using From and a loop.

Notes

Bugs

• should I expose fromByReflection? I used it for higher performance in Append.