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