]>
Commit | Line | Data |
---|---|---|
bae9f6d2 JC |
1 | # go-multierror |
2 | ||
107c1cdb ND |
3 | [![Build Status](http://img.shields.io/travis/hashicorp/go-multierror.svg?style=flat-square)][travis] |
4 | [![Go Documentation](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)][godocs] | |
5 | ||
6 | [travis]: https://travis-ci.org/hashicorp/go-multierror | |
7 | [godocs]: https://godoc.org/github.com/hashicorp/go-multierror | |
8 | ||
bae9f6d2 JC |
9 | `go-multierror` is a package for Go that provides a mechanism for |
10 | representing a list of `error` values as a single `error`. | |
11 | ||
12 | This allows a function in Go to return an `error` that might actually | |
13 | be a list of errors. If the caller knows this, they can unwrap the | |
14 | list and access the errors. If the caller doesn't know, the error | |
15 | formats to a nice human-readable format. | |
16 | ||
17 | `go-multierror` implements the | |
18 | [errwrap](https://github.com/hashicorp/errwrap) interface so that it can | |
19 | be used with that library, as well. | |
20 | ||
21 | ## Installation and Docs | |
22 | ||
23 | Install using `go get github.com/hashicorp/go-multierror`. | |
24 | ||
25 | Full documentation is available at | |
26 | http://godoc.org/github.com/hashicorp/go-multierror | |
27 | ||
28 | ## Usage | |
29 | ||
30 | go-multierror is easy to use and purposely built to be unobtrusive in | |
31 | existing Go applications/libraries that may not be aware of it. | |
32 | ||
33 | **Building a list of errors** | |
34 | ||
35 | The `Append` function is used to create a list of errors. This function | |
36 | behaves a lot like the Go built-in `append` function: it doesn't matter | |
37 | if the first argument is nil, a `multierror.Error`, or any other `error`, | |
38 | the function behaves as you would expect. | |
39 | ||
40 | ```go | |
41 | var result error | |
42 | ||
43 | if err := step1(); err != nil { | |
44 | result = multierror.Append(result, err) | |
45 | } | |
46 | if err := step2(); err != nil { | |
47 | result = multierror.Append(result, err) | |
48 | } | |
49 | ||
50 | return result | |
51 | ``` | |
52 | ||
53 | **Customizing the formatting of the errors** | |
54 | ||
55 | By specifying a custom `ErrorFormat`, you can customize the format | |
56 | of the `Error() string` function: | |
57 | ||
58 | ```go | |
59 | var result *multierror.Error | |
60 | ||
61 | // ... accumulate errors here, maybe using Append | |
62 | ||
63 | if result != nil { | |
64 | result.ErrorFormat = func([]error) string { | |
65 | return "errors!" | |
66 | } | |
67 | } | |
68 | ``` | |
69 | ||
70 | **Accessing the list of errors** | |
71 | ||
72 | `multierror.Error` implements `error` so if the caller doesn't know about | |
73 | multierror, it will work just fine. But if you're aware a multierror might | |
74 | be returned, you can use type switches to access the list of errors: | |
75 | ||
76 | ```go | |
77 | if err := something(); err != nil { | |
78 | if merr, ok := err.(*multierror.Error); ok { | |
79 | // Use merr.Errors | |
80 | } | |
81 | } | |
82 | ``` | |
83 | ||
84 | **Returning a multierror only if there are errors** | |
85 | ||
86 | If you build a `multierror.Error`, you can use the `ErrorOrNil` function | |
87 | to return an `error` implementation only if there are errors to return: | |
88 | ||
89 | ```go | |
90 | var result *multierror.Error | |
91 | ||
92 | // ... accumulate errors here | |
93 | ||
94 | // Return the `error` only if errors were added to the multierror, otherwise | |
95 | // return nil since there are no errors. | |
96 | return result.ErrorOrNil() | |
97 | ``` |