Add new util/errors pkg

pkg/util/errors/doc.go

@@ -0,0 +1,18 @@
+/*
+Copyright 2015 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package errors implements various utility functions and types around errors.
+package errors

pkg/util/errors/errors.go

@@ -0,0 +1,133 @@
+/*
+Copyright 2015 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package errors
+
+import "fmt"
+
+// Aggregate represents an object that contains multiple errors, but does not
+// necessarily have singular semantic meaning.
+type Aggregate interface {
+	error
+	Errors() []error
+}
+
+// NewAggregate converts a slice of errors into an Aggregate interface, which
+// is itself an implementation of the error interface.  If the slice is empty,
+// this returs nil.
+func NewAggregate(errlist []error) Aggregate {
+	if len(errlist) == 0 {
+		return nil
+	}
+	return aggregate(errlist)
+}
+
+// This helper implements the error and Errors interfaces.  Keeping it private
+// prevents people from making an aggregate of 0 errors, which is not
+// an error, but does satisfy the error interface.
+type aggregate []error
+
+// Error is part of the error interface.
+func (agg aggregate) Error() string {
+	if len(agg) == 0 {
+		// This should never happen, really.
+		return ""
+	}
+	if len(agg) == 1 {
+		return agg[0].Error()
+	}
+	result := fmt.Sprintf("[%s", agg[0].Error())
+	for i := 1; i < len(agg); i++ {
+		result += fmt.Sprintf(", %s", agg[i].Error())
+	}
+	result += "]"
+	return result
+}
+
+// Errors is part of the Aggregate interface.
+func (agg aggregate) Errors() []error {
+	return []error(agg)
+}
+
+// Matcher is used to match errors.  Returns true if the error matches.
+type Matcher func(error) bool
+
+// FilterOut removes all errors that match any of the matchers from the input
+// error.  If the input is a singular error, only that error is tested.  If the
+// input implements the Aggregate interface, the list of errors will be
+// processed recursively.
+//
+// This can be used, for example, to remove known-OK errors (such as io.EOF or
+// os.PathNotFound) from a list of errors.
+func FilterOut(err error, fns ...Matcher) error {
+	if err == nil {
+		return nil
+	}
+	if agg, ok := err.(Aggregate); ok {
+		return NewAggregate(filterErrors(agg.Errors(), fns...))
+	}
+	if !matchesError(err, fns...) {
+		return err
+	}
+	return nil
+}
+
+// matchesError returns true if any Matcher returns true
+func matchesError(err error, fns ...Matcher) bool {
+	for _, fn := range fns {
+		if fn(err) {
+			return true
+		}
+	}
+	return false
+}
+
+// filterErrors returns any errors (or nested errors, if the list contains
+// nested Errors) for which all fns return false. If no errors
+// remain a nil list is returned. The resulting silec will have all
+// nested slices flattened as a side effect.
+func filterErrors(list []error, fns ...Matcher) []error {
+	result := []error{}
+	for _, err := range list {
+		r := FilterOut(err, fns...)
+		if r != nil {
+			result = append(result, r)
+		}
+	}
+	return result
+}
+
+// Flatten takes an Aggregate, which may hold other Aggregates in arbitrary
+// nesting, and flattens them all into a single Aggregate, recursively.
+func Flatten(agg Aggregate) Aggregate {
+	result := []error{}
+	if agg == nil {
+		return nil
+	}
+	for _, err := range agg.Errors() {
+		if a, ok := err.(Aggregate); ok {
+			r := Flatten(a)
+			if r != nil {
+				result = append(result, r.Errors()...)
+			}
+		} else {
+			if err != nil {
+				result = append(result, err)
+			}
+		}
+	}
+	return NewAggregate(result)
+}

pkg/util/errors/errors_test.go

@@ -0,0 +1,223 @@
+/*
+Copyright 2015 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package errors
+
+import (
+	"fmt"
+	"reflect"
+	"testing"
+)
+
+func TestEmptyAggregate(t *testing.T) {
+	var slice []error
+	var agg Aggregate
+	var err error
+
+	agg = NewAggregate(slice)
+	if agg != nil {
+		t.Errorf("expected nil, got %#v", agg)
+	}
+	err = NewAggregate(slice)
+	if err != nil {
+		t.Errorf("expected nil, got %#v", err)
+	}
+
+	// This is not normally possible, but pedantry demands I test it.
+	agg = aggregate(slice) // empty aggregate
+	if s := agg.Error(); s != "" {
+		t.Errorf("expected empty string, got %q", s)
+	}
+	if s := agg.Errors(); len(s) != 0 {
+		t.Errorf("expected empty slice, got %#v", s)
+	}
+	err = agg.(error)
+	if s := err.Error(); s != "" {
+		t.Errorf("expected empty string, got %q", s)
+	}
+}
+
+func TestSingularAggregate(t *testing.T) {
+	var slice []error = []error{fmt.Errorf("err")}
+	var agg Aggregate
+	var err error
+
+	agg = NewAggregate(slice)
+	if agg == nil {
+		t.Errorf("expected non-nil")
+	}
+	if s := agg.Error(); s != "err" {
+		t.Errorf("expected 'err', got %q", s)
+	}
+	if s := agg.Errors(); len(s) != 1 {
+		t.Errorf("expected one-element slice, got %#v", s)
+	}
+	if s := agg.Errors()[0].Error(); s != "err" {
+		t.Errorf("expected 'err', got %q", s)
+	}
+
+	err = agg.(error)
+	if err == nil {
+		t.Errorf("expected non-nil")
+	}
+	if s := err.Error(); s != "err" {
+		t.Errorf("expected 'err', got %q", s)
+	}
+}
+
+func TestPluralAggregate(t *testing.T) {
+	var slice []error = []error{fmt.Errorf("abc"), fmt.Errorf("123")}
+	var agg Aggregate
+	var err error
+
+	agg = NewAggregate(slice)
+	if agg == nil {
+		t.Errorf("expected non-nil")
+	}
+	if s := agg.Error(); s != "[abc, 123]" {
+		t.Errorf("expected '[abc, 123]', got %q", s)
+	}
+	if s := agg.Errors(); len(s) != 2 {
+		t.Errorf("expected one-element slice, got %#v", s)
+	}
+	if s := agg.Errors()[0].Error(); s != "abc" {
+		t.Errorf("expected '[abc, 123]', got %q", s)
+	}
+
+	err = agg.(error)
+	if err == nil {
+		t.Errorf("expected non-nil")
+	}
+	if s := err.Error(); s != "[abc, 123]" {
+		t.Errorf("expected '[abc, 123]', got %q", s)
+	}
+}
+
+func TestFilterOut(t *testing.T) {
+	testCases := []struct {
+		err      error
+		filter   []Matcher
+		expected error
+	}{
+		{
+			nil,
+			[]Matcher{},
+			nil,
+		},
+		{
+			aggregate{},
+			[]Matcher{},
+			nil,
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			[]Matcher{},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			[]Matcher{func(err error) bool { return false }},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			[]Matcher{func(err error) bool { return true }},
+			nil,
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			[]Matcher{func(err error) bool { return false }, func(err error) bool { return false }},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			[]Matcher{func(err error) bool { return false }, func(err error) bool { return true }},
+			nil,
+		},
+		{
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("def"), fmt.Errorf("ghi")},
+			[]Matcher{func(err error) bool { return err.Error() == "def" }},
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("ghi")},
+		},
+		{
+			aggregate{aggregate{fmt.Errorf("abc")}},
+			[]Matcher{},
+			aggregate{aggregate{fmt.Errorf("abc")}},
+		},
+		{
+			aggregate{aggregate{fmt.Errorf("abc"), aggregate{fmt.Errorf("def")}}},
+			[]Matcher{},
+			aggregate{aggregate{fmt.Errorf("abc"), aggregate{fmt.Errorf("def")}}},
+		},
+		{
+			aggregate{aggregate{fmt.Errorf("abc"), aggregate{fmt.Errorf("def")}}},
+			[]Matcher{func(err error) bool { return err.Error() == "def" }},
+			aggregate{aggregate{fmt.Errorf("abc")}},
+		},
+	}
+	for i, testCase := range testCases {
+		err := FilterOut(testCase.err, testCase.filter...)
+		if !reflect.DeepEqual(testCase.expected, err) {
+			t.Errorf("%d: expected %v, got %v", i, testCase.expected, err)
+		}
+	}
+}
+
+func TestFlatten(t *testing.T) {
+	testCases := []struct {
+		agg      Aggregate
+		expected Aggregate
+	}{
+		{
+			nil,
+			nil,
+		},
+		{
+			aggregate{},
+			nil,
+		},
+		{
+			aggregate{fmt.Errorf("abc")},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("def"), fmt.Errorf("ghi")},
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("def"), fmt.Errorf("ghi")},
+		},
+		{
+			aggregate{aggregate{fmt.Errorf("abc")}},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{aggregate{aggregate{fmt.Errorf("abc")}}},
+			aggregate{fmt.Errorf("abc")},
+		},
+		{
+			aggregate{aggregate{fmt.Errorf("abc"), aggregate{fmt.Errorf("def")}}},
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("def")},
+		},
+		{
+			aggregate{aggregate{aggregate{fmt.Errorf("abc")}, fmt.Errorf("def"), aggregate{fmt.Errorf("ghi")}}},
+			aggregate{fmt.Errorf("abc"), fmt.Errorf("def"), fmt.Errorf("ghi")},
+		},
+	}
+	for i, testCase := range testCases {
+		agg := Flatten(testCase.agg)
+		if !reflect.DeepEqual(testCase.expected, agg) {
+			t.Errorf("%d: expected %v, got %v", i, testCase.expected, agg)
+		}
+	}
+}