1// Package errwrap implements methods to formalize error wrapping in Go.
2//
3// All of the top-level functions that take an `error` are built to be able
4// to take any error, not just wrapped errors. This allows you to use errwrap
5// without having to type-check and type-cast everywhere.
6package errwrap
7
8import (
9	"errors"
10	"reflect"
11	"strings"
12)
13
14// WalkFunc is the callback called for Walk.
15type WalkFunc func(error)
16
17// Wrapper is an interface that can be implemented by custom types to
18// have all the Contains, Get, etc. functions in errwrap work.
19//
20// When Walk reaches a Wrapper, it will call the callback for every
21// wrapped error in addition to the wrapper itself. Since all the top-level
22// functions in errwrap use Walk, this means that all those functions work
23// with your custom type.
24type Wrapper interface {
25	WrappedErrors() []error
26}
27
28// Wrap defines that outer wraps inner, returning an error type that
29// can be cleanly used with the other methods in this package, such as
30// Contains, GetAll, etc.
31//
32// This function won't modify the error message at all (the outer message
33// will be used).
34func Wrap(outer, inner error) error {
35	return &wrappedError{
36		Outer: outer,
37		Inner: inner,
38	}
39}
40
41// Wrapf wraps an error with a formatting message. This is similar to using
42// `fmt.Errorf` to wrap an error. If you're using `fmt.Errorf` to wrap
43// errors, you should replace it with this.
44//
45// format is the format of the error message. The string '{{err}}' will
46// be replaced with the original error message.
47func Wrapf(format string, err error) error {
48	outerMsg := "<nil>"
49	if err != nil {
50		outerMsg = err.Error()
51	}
52
53	outer := errors.New(strings.Replace(
54		format, "{{err}}", outerMsg, -1))
55
56	return Wrap(outer, err)
57}
58
59// Contains checks if the given error contains an error with the
60// message msg. If err is not a wrapped error, this will always return
61// false unless the error itself happens to match this msg.
62func Contains(err error, msg string) bool {
63	return len(GetAll(err, msg)) > 0
64}
65
66// ContainsType checks if the given error contains an error with
67// the same concrete type as v. If err is not a wrapped error, this will
68// check the err itself.
69func ContainsType(err error, v interface{}) bool {
70	return len(GetAllType(err, v)) > 0
71}
72
73// Get is the same as GetAll but returns the deepest matching error.
74func Get(err error, msg string) error {
75	es := GetAll(err, msg)
76	if len(es) > 0 {
77		return es[len(es)-1]
78	}
79
80	return nil
81}
82
83// GetType is the same as GetAllType but returns the deepest matching error.
84func GetType(err error, v interface{}) error {
85	es := GetAllType(err, v)
86	if len(es) > 0 {
87		return es[len(es)-1]
88	}
89
90	return nil
91}
92
93// GetAll gets all the errors that might be wrapped in err with the
94// given message. The order of the errors is such that the outermost
95// matching error (the most recent wrap) is index zero, and so on.
96func GetAll(err error, msg string) []error {
97	var result []error
98
99	Walk(err, func(err error) {
100		if err.Error() == msg {
101			result = append(result, err)
102		}
103	})
104
105	return result
106}
107
108// GetAllType gets all the errors that are the same type as v.
109//
110// The order of the return value is the same as described in GetAll.
111func GetAllType(err error, v interface{}) []error {
112	var result []error
113
114	var search string
115	if v != nil {
116		search = reflect.TypeOf(v).String()
117	}
118	Walk(err, func(err error) {
119		var needle string
120		if err != nil {
121			needle = reflect.TypeOf(err).String()
122		}
123
124		if needle == search {
125			result = append(result, err)
126		}
127	})
128
129	return result
130}
131
132// Walk walks all the wrapped errors in err and calls the callback. If
133// err isn't a wrapped error, this will be called once for err. If err
134// is a wrapped error, the callback will be called for both the wrapper
135// that implements error as well as the wrapped error itself.
136func Walk(err error, cb WalkFunc) {
137	if err == nil {
138		return
139	}
140
141	switch e := err.(type) {
142	case *wrappedError:
143		cb(e.Outer)
144		Walk(e.Inner, cb)
145	case Wrapper:
146		cb(err)
147
148		for _, err := range e.WrappedErrors() {
149			Walk(err, cb)
150		}
151	default:
152		cb(err)
153	}
154}
155
156// wrappedError is an implementation of error that has both the
157// outer and inner errors.
158type wrappedError struct {
159	Outer error
160	Inner error
161}
162
163func (w *wrappedError) Error() string {
164	return w.Outer.Error()
165}
166
167func (w *wrappedError) WrappedErrors() []error {
168	return []error{w.Outer, w.Inner}
169}
170