diff options
Diffstat (limited to 'src/errors')
-rw-r--r-- | src/errors/errors.go | 69 | ||||
-rw-r--r-- | src/errors/errors_test.go | 53 | ||||
-rw-r--r-- | src/errors/example_test.go | 34 | ||||
-rw-r--r-- | src/errors/wrap.go | 103 | ||||
-rw-r--r-- | src/errors/wrap_test.go | 267 |
5 files changed, 526 insertions, 0 deletions
diff --git a/src/errors/errors.go b/src/errors/errors.go new file mode 100644 index 0000000..f2fabac --- /dev/null +++ b/src/errors/errors.go @@ -0,0 +1,69 @@ +// Copyright 2011 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +// Package errors implements functions to manipulate errors. +// +// The New function creates errors whose only content is a text message. +// +// The Unwrap, Is and As functions work on errors that may wrap other errors. +// An error wraps another error if its type has the method +// +// Unwrap() error +// +// If e.Unwrap() returns a non-nil error w, then we say that e wraps w. +// +// Unwrap unpacks wrapped errors. If its argument's type has an +// Unwrap method, it calls the method once. Otherwise, it returns nil. +// +// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb +// to the error argument: +// +// errors.Unwrap(fmt.Errorf("... %w ...", ..., err, ...)) +// +// returns err. +// +// Is unwraps its first argument sequentially looking for an error that matches the +// second. It reports whether it finds a match. It should be used in preference to +// simple equality checks: +// +// if errors.Is(err, fs.ErrExist) +// +// is preferable to +// +// if err == fs.ErrExist +// +// because the former will succeed if err wraps fs.ErrExist. +// +// As unwraps its first argument sequentially looking for an error that can be +// assigned to its second argument, which must be a pointer. If it succeeds, it +// performs the assignment and returns true. Otherwise, it returns false. The form +// +// var perr *fs.PathError +// if errors.As(err, &perr) { +// fmt.Println(perr.Path) +// } +// +// is preferable to +// +// if perr, ok := err.(*fs.PathError); ok { +// fmt.Println(perr.Path) +// } +// +// because the former will succeed if err wraps an *fs.PathError. +package errors + +// New returns an error that formats as the given text. +// Each call to New returns a distinct error value even if the text is identical. +func New(text string) error { + return &errorString{text} +} + +// errorString is a trivial implementation of error. +type errorString struct { + s string +} + +func (e *errorString) Error() string { + return e.s +} diff --git a/src/errors/errors_test.go b/src/errors/errors_test.go new file mode 100644 index 0000000..cf4df90 --- /dev/null +++ b/src/errors/errors_test.go @@ -0,0 +1,53 @@ +// Copyright 2011 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package errors_test + +import ( + "errors" + "fmt" + "testing" +) + +func TestNewEqual(t *testing.T) { + // Different allocations should not be equal. + if errors.New("abc") == errors.New("abc") { + t.Errorf(`New("abc") == New("abc")`) + } + if errors.New("abc") == errors.New("xyz") { + t.Errorf(`New("abc") == New("xyz")`) + } + + // Same allocation should be equal to itself (not crash). + err := errors.New("jkl") + if err != err { + t.Errorf(`err != err`) + } +} + +func TestErrorMethod(t *testing.T) { + err := errors.New("abc") + if err.Error() != "abc" { + t.Errorf(`New("abc").Error() = %q, want %q`, err.Error(), "abc") + } +} + +func ExampleNew() { + err := errors.New("emit macho dwarf: elf header corrupted") + if err != nil { + fmt.Print(err) + } + // Output: emit macho dwarf: elf header corrupted +} + +// The fmt package's Errorf function lets us use the package's formatting +// features to create descriptive error messages. +func ExampleNew_errorf() { + const name, id = "bimmler", 17 + err := fmt.Errorf("user %q (id %d) not found", name, id) + if err != nil { + fmt.Print(err) + } + // Output: user "bimmler" (id 17) not found +} diff --git a/src/errors/example_test.go b/src/errors/example_test.go new file mode 100644 index 0000000..5dc8841 --- /dev/null +++ b/src/errors/example_test.go @@ -0,0 +1,34 @@ +// Copyright 2012 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package errors_test + +import ( + "fmt" + "time" +) + +// MyError is an error implementation that includes a time and message. +type MyError struct { + When time.Time + What string +} + +func (e MyError) Error() string { + return fmt.Sprintf("%v: %v", e.When, e.What) +} + +func oops() error { + return MyError{ + time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC), + "the file system has gone away", + } +} + +func Example() { + if err := oops(); err != nil { + fmt.Println(err) + } + // Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away +} diff --git a/src/errors/wrap.go b/src/errors/wrap.go new file mode 100644 index 0000000..7928fe6 --- /dev/null +++ b/src/errors/wrap.go @@ -0,0 +1,103 @@ +// Copyright 2018 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package errors + +import ( + "internal/reflectlite" +) + +// Unwrap returns the result of calling the Unwrap method on err, if err's +// type contains an Unwrap method returning error. +// Otherwise, Unwrap returns nil. +func Unwrap(err error) error { + u, ok := err.(interface { + Unwrap() error + }) + if !ok { + return nil + } + return u.Unwrap() +} + +// Is reports whether any error in err's chain matches target. +// +// The chain consists of err itself followed by the sequence of errors obtained by +// repeatedly calling Unwrap. +// +// An error is considered to match a target if it is equal to that target or if +// it implements a method Is(error) bool such that Is(target) returns true. +// +// An error type might provide an Is method so it can be treated as equivalent +// to an existing error. For example, if MyError defines +// +// func (m MyError) Is(target error) bool { return target == fs.ErrExist } +// +// then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for +// an example in the standard library. +func Is(err, target error) bool { + if target == nil { + return err == target + } + + isComparable := reflectlite.TypeOf(target).Comparable() + for { + if isComparable && err == target { + return true + } + if x, ok := err.(interface{ Is(error) bool }); ok && x.Is(target) { + return true + } + // TODO: consider supporting target.Is(err). This would allow + // user-definable predicates, but also may allow for coping with sloppy + // APIs, thereby making it easier to get away with them. + if err = Unwrap(err); err == nil { + return false + } + } +} + +// As finds the first error in err's chain that matches target, and if so, sets +// target to that error value and returns true. Otherwise, it returns false. +// +// The chain consists of err itself followed by the sequence of errors obtained by +// repeatedly calling Unwrap. +// +// An error matches target if the error's concrete value is assignable to the value +// pointed to by target, or if the error has a method As(interface{}) bool such that +// As(target) returns true. In the latter case, the As method is responsible for +// setting target. +// +// An error type might provide an As method so it can be treated as if it were a +// different error type. +// +// As panics if target is not a non-nil pointer to either a type that implements +// error, or to any interface type. +func As(err error, target interface{}) bool { + if target == nil { + panic("errors: target cannot be nil") + } + val := reflectlite.ValueOf(target) + typ := val.Type() + if typ.Kind() != reflectlite.Ptr || val.IsNil() { + panic("errors: target must be a non-nil pointer") + } + if e := typ.Elem(); e.Kind() != reflectlite.Interface && !e.Implements(errorType) { + panic("errors: *target must be interface or implement error") + } + targetType := typ.Elem() + for err != nil { + if reflectlite.TypeOf(err).AssignableTo(targetType) { + val.Elem().Set(reflectlite.ValueOf(err)) + return true + } + if x, ok := err.(interface{ As(interface{}) bool }); ok && x.As(target) { + return true + } + err = Unwrap(err) + } + return false +} + +var errorType = reflectlite.TypeOf((*error)(nil)).Elem() diff --git a/src/errors/wrap_test.go b/src/errors/wrap_test.go new file mode 100644 index 0000000..6f66e99 --- /dev/null +++ b/src/errors/wrap_test.go @@ -0,0 +1,267 @@ +// Copyright 2018 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package errors_test + +import ( + "errors" + "fmt" + "io/fs" + "os" + "reflect" + "testing" +) + +func TestIs(t *testing.T) { + err1 := errors.New("1") + erra := wrapped{"wrap 2", err1} + errb := wrapped{"wrap 3", erra} + + err3 := errors.New("3") + + poser := &poser{"either 1 or 3", func(err error) bool { + return err == err1 || err == err3 + }} + + testCases := []struct { + err error + target error + match bool + }{ + {nil, nil, true}, + {err1, nil, false}, + {err1, err1, true}, + {erra, err1, true}, + {errb, err1, true}, + {err1, err3, false}, + {erra, err3, false}, + {errb, err3, false}, + {poser, err1, true}, + {poser, err3, true}, + {poser, erra, false}, + {poser, errb, false}, + {errorUncomparable{}, errorUncomparable{}, true}, + {errorUncomparable{}, &errorUncomparable{}, false}, + {&errorUncomparable{}, errorUncomparable{}, true}, + {&errorUncomparable{}, &errorUncomparable{}, false}, + {errorUncomparable{}, err1, false}, + {&errorUncomparable{}, err1, false}, + } + for _, tc := range testCases { + t.Run("", func(t *testing.T) { + if got := errors.Is(tc.err, tc.target); got != tc.match { + t.Errorf("Is(%v, %v) = %v, want %v", tc.err, tc.target, got, tc.match) + } + }) + } +} + +type poser struct { + msg string + f func(error) bool +} + +var poserPathErr = &fs.PathError{Op: "poser"} + +func (p *poser) Error() string { return p.msg } +func (p *poser) Is(err error) bool { return p.f(err) } +func (p *poser) As(err interface{}) bool { + switch x := err.(type) { + case **poser: + *x = p + case *errorT: + *x = errorT{"poser"} + case **fs.PathError: + *x = poserPathErr + default: + return false + } + return true +} + +func TestAs(t *testing.T) { + var errT errorT + var errP *fs.PathError + var timeout interface{ Timeout() bool } + var p *poser + _, errF := os.Open("non-existing") + poserErr := &poser{"oh no", nil} + + testCases := []struct { + err error + target interface{} + match bool + want interface{} // value of target on match + }{{ + nil, + &errP, + false, + nil, + }, { + wrapped{"pitied the fool", errorT{"T"}}, + &errT, + true, + errorT{"T"}, + }, { + errF, + &errP, + true, + errF, + }, { + errorT{}, + &errP, + false, + nil, + }, { + wrapped{"wrapped", nil}, + &errT, + false, + nil, + }, { + &poser{"error", nil}, + &errT, + true, + errorT{"poser"}, + }, { + &poser{"path", nil}, + &errP, + true, + poserPathErr, + }, { + poserErr, + &p, + true, + poserErr, + }, { + errors.New("err"), + &timeout, + false, + nil, + }, { + errF, + &timeout, + true, + errF, + }, { + wrapped{"path error", errF}, + &timeout, + true, + errF, + }} + for i, tc := range testCases { + name := fmt.Sprintf("%d:As(Errorf(..., %v), %v)", i, tc.err, tc.target) + // Clear the target pointer, in case it was set in a previous test. + rtarget := reflect.ValueOf(tc.target) + rtarget.Elem().Set(reflect.Zero(reflect.TypeOf(tc.target).Elem())) + t.Run(name, func(t *testing.T) { + match := errors.As(tc.err, tc.target) + if match != tc.match { + t.Fatalf("match: got %v; want %v", match, tc.match) + } + if !match { + return + } + if got := rtarget.Elem().Interface(); got != tc.want { + t.Fatalf("got %#v, want %#v", got, tc.want) + } + }) + } +} + +func TestAsValidation(t *testing.T) { + var s string + testCases := []interface{}{ + nil, + (*int)(nil), + "error", + &s, + } + err := errors.New("error") + for _, tc := range testCases { + t.Run(fmt.Sprintf("%T(%v)", tc, tc), func(t *testing.T) { + defer func() { + recover() + }() + if errors.As(err, tc) { + t.Errorf("As(err, %T(%v)) = true, want false", tc, tc) + return + } + t.Errorf("As(err, %T(%v)) did not panic", tc, tc) + }) + } +} + +func TestUnwrap(t *testing.T) { + err1 := errors.New("1") + erra := wrapped{"wrap 2", err1} + + testCases := []struct { + err error + want error + }{ + {nil, nil}, + {wrapped{"wrapped", nil}, nil}, + {err1, nil}, + {erra, err1}, + {wrapped{"wrap 3", erra}, erra}, + } + for _, tc := range testCases { + if got := errors.Unwrap(tc.err); got != tc.want { + t.Errorf("Unwrap(%v) = %v, want %v", tc.err, got, tc.want) + } + } +} + +type errorT struct{ s string } + +func (e errorT) Error() string { return fmt.Sprintf("errorT(%s)", e.s) } + +type wrapped struct { + msg string + err error +} + +func (e wrapped) Error() string { return e.msg } + +func (e wrapped) Unwrap() error { return e.err } + +type errorUncomparable struct { + f []string +} + +func (errorUncomparable) Error() string { + return "uncomparable error" +} + +func (errorUncomparable) Is(target error) bool { + _, ok := target.(errorUncomparable) + return ok +} + +func ExampleIs() { + if _, err := os.Open("non-existing"); err != nil { + if errors.Is(err, fs.ErrNotExist) { + fmt.Println("file does not exist") + } else { + fmt.Println(err) + } + } + + // Output: + // file does not exist +} + +func ExampleAs() { + if _, err := os.Open("non-existing"); err != nil { + var pathError *fs.PathError + if errors.As(err, &pathError) { + fmt.Println("Failed at path:", pathError.Path) + } else { + fmt.Println(err) + } + } + + // Output: + // Failed at path: non-existing +} |