← Back to branch summary

~juju-qa/ubuntu/trusty/juju/juju-1.25.8

« back to all changes in this revision

Viewing changes to src/gopkg.in/errgo.v1/README.md

  • Committer: Nicholas Skaggs
  • Date: 2016-12-02 18:01:10 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161202180110-dl1helep8qfebmhx
Import upstream 1.25.6

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gopkg.in/errgo.v1/README.md
 
1
# errgo
 
2
--
 
3
    import "gopkg.in/errgo.v1"
 
4
 
 
5
The errgo package provides a way to create and diagnose errors. It is compatible
 
6
with the usual Go error idioms but adds a way to wrap errors so that they record
 
7
source location information while retaining a consistent way for code to inspect
 
8
errors to find out particular problems.
 
9
 
 
10
## Usage
 
11
 
 
12
#### func  Any
 
13
 
 
14
```go
 
15
func Any(error) bool
 
16
```
 
17
Any returns true. It can be used as an argument to Mask to allow any diagnosis
 
18
to pass through to the wrapped error.
 
19
 
 
20
#### func  Cause
 
21
 
 
22
```go
 
23
func Cause(err error) error
 
24
```
 
25
Cause returns the cause of the given error. If err does not implement Causer or
 
26
its Cause method returns nil, it returns err itself.
 
27
 
 
28
Cause is the usual way to diagnose errors that may have been wrapped by Mask or
 
29
NoteMask.
 
30
 
 
31
#### func  Details
 
32
 
 
33
```go
 
34
func Details(err error) string
 
35
```
 
36
Details returns information about the stack of underlying errors wrapped by err,
 
37
in the format:
 
38
 
 
39
    [{filename:99: error one} {otherfile:55: cause of error one}]
 
40
 
 
41
The details are found by type-asserting the error to the Locationer, Causer and
 
42
Wrapper interfaces. Details of the underlying stack are found by recursively
 
43
calling Underlying when the underlying error implements Wrapper.
 
44
 
 
45
#### func  Is
 
46
 
 
47
```go
 
48
func Is(err error) func(error) bool
 
49
```
 
50
Is returns a function that returns whether the an error is equal to the given
 
51
error. It is intended to be used as a "pass" argument to Mask and friends; for
 
52
example:
 
53
 
 
54
    return errors.Mask(err, errors.Is(http.ErrNoCookie))
 
55
 
 
56
would return an error with an http.ErrNoCookie cause only if that was err's
 
57
diagnosis; otherwise the diagnosis would be itself.
 
58
 
 
59
#### func  Mask
 
60
 
 
61
```go
 
62
func Mask(underlying error, pass ...func(error) bool) error
 
63
```
 
64
Mask returns an Err that wraps the given underyling error. The error message is
 
65
unchanged, but the error location records the caller of Mask.
 
66
 
 
67
If err is nil, Mask returns nil.
 
68
 
 
69
By default Mask conceals the cause of the wrapped error, but if pass(Cause(err))
 
70
returns true for any of the provided pass functions, the cause of the returned
 
71
error will be Cause(err).
 
72
 
 
73
For example, the following code will return an error whose cause is the error
 
74
from the os.Open call when (and only when) the file does not exist.
 
75
 
 
76
    f, err := os.Open("non-existent-file")
 
77
    if err != nil {
 
78
        return errors.Mask(err, os.IsNotExist)
 
79
    }
 
80
 
 
81
In order to add context to returned errors, it is conventional to call Mask when
 
82
returning any error received from elsewhere.
 
83
 
 
84
#### func  MaskFunc
 
85
 
 
86
```go
 
87
func MaskFunc(allow ...func(error) bool) func(error, ...func(error) bool) error
 
88
```
 
89
MaskFunc returns an equivalent of Mask that always allows the specified causes
 
90
in addition to any causes specified when the returned function is called.
 
91
 
 
92
It is defined for convenience, for example when all calls to Mask in a given
 
93
package wish to allow the same set of causes to be returned.
 
94
 
 
95
#### func  New
 
96
 
 
97
```go
 
98
func New(s string) error
 
99
```
 
100
New returns a new error with the given error message and no cause. It is a
 
101
drop-in replacement for errors.New from the standard library.
 
102
 
 
103
#### func  Newf
 
104
 
 
105
```go
 
106
func Newf(f string, a ...interface{}) error
 
107
```
 
108
Newf returns a new error with the given printf-formatted error message and no
 
109
cause.
 
110
 
 
111
#### func  NoteMask
 
112
 
 
113
```go
 
114
func NoteMask(underlying error, msg string, pass ...func(error) bool) error
 
115
```
 
116
NoteMask returns an Err that has the given underlying error, with the given
 
117
message added as context, and allowing the cause of the underlying error to pass
 
118
through into the result if allowed by the specific pass functions (see Mask for
 
119
an explanation of the pass parameter).
 
120
 
 
121
#### func  Notef
 
122
 
 
123
```go
 
124
func Notef(underlying error, f string, a ...interface{}) error
 
125
```
 
126
Notef returns an Error that wraps the given underlying error and adds the given
 
127
formatted context message. The returned error has no cause (use NoteMask or
 
128
WithCausef to add a message while retaining a cause).
 
129
 
 
130
#### func  WithCausef
 
131
 
 
132
```go
 
133
func WithCausef(underlying, cause error, f string, a ...interface{}) error
 
134
```
 
135
WithCausef returns a new Error that wraps the given (possibly nil) underlying
 
136
error and associates it with the given cause. The given formatted message
 
137
context will also be added.
 
138
 
 
139
#### type Causer
 
140
 
 
141
```go
 
142
type Causer interface {
 
143
        Cause() error
 
144
}
 
145
```
 
146
 
 
147
Causer is the type of an error that may provide an error cause for error
 
148
diagnosis. Cause may return nil if there is no cause (for example because the
 
149
cause has been masked).
 
150
 
 
151
#### type Err
 
152
 
 
153
```go
 
154
type Err struct {
 
155
        // Message_ holds the text of the error message. It may be empty
 
156
        // if Underlying is set.
 
157
        Message_ string
 
158
 
 
159
        // Cause_ holds the cause of the error as returned
 
160
        // by the Cause method.
 
161
        Cause_ error
 
162
 
 
163
        // Underlying holds the underlying error, if any.
 
164
        Underlying_ error
 
165
 
 
166
        // File and Line identify the source code location where the error was
 
167
        // created.
 
168
        File string
 
169
        Line int
 
170
}
 
171
```
 
172
 
 
173
Err holds a description of an error along with information about where the error
 
174
was created.
 
175
 
 
176
It may be embedded in custom error types to add extra information that this
 
177
errors package can understand.
 
178
 
 
179
#### func (*Err) Cause
 
180
 
 
181
```go
 
182
func (e *Err) Cause() error
 
183
```
 
184
Cause implements Causer.
 
185
 
 
186
#### func (*Err) Error
 
187
 
 
188
```go
 
189
func (e *Err) Error() string
 
190
```
 
191
Error implements error.Error.
 
192
 
 
193
#### func (*Err) GoString
 
194
 
 
195
```go
 
196
func (e *Err) GoString() string
 
197
```
 
198
GoString returns the details of the receiving error message, so that printing an
 
199
error with %#v will produce useful information.
 
200
 
 
201
#### func (*Err) Location
 
202
 
 
203
```go
 
204
func (e *Err) Location() (file string, line int)
 
205
```
 
206
Location implements Locationer.
 
207
 
 
208
#### func (*Err) Message
 
209
 
 
210
```go
 
211
func (e *Err) Message() string
 
212
```
 
213
Message returns the top level error message.
 
214
 
 
215
#### func (*Err) SetLocation
 
216
 
 
217
```go
 
218
func (e *Err) SetLocation(callDepth int)
 
219
```
 
220
Locate records the source location of the error by setting e.Location, at
 
221
callDepth stack frames above the call.
 
222
 
 
223
#### func (*Err) Underlying
 
224
 
 
225
```go
 
226
func (e *Err) Underlying() error
 
227
```
 
228
Underlying returns the underlying error if any.
 
229
 
 
230
#### type Locationer
 
231
 
 
232
```go
 
233
type Locationer interface {
 
234
        // Location returns the name of the file and the line
 
235
        // number associated with an error.
 
236
        Location() (file string, line int)
 
237
}
 
238
```
 
239
 
 
240
Locationer can be implemented by any error type that wants to expose the source
 
241
location of an error.
 
242
 
 
243
#### type Wrapper
 
244
 
 
245
```go
 
246
type Wrapper interface {
 
247
        // Message returns the top level error message,
 
248
        // not including the message from the underlying
 
249
        // error.
 
250
        Message() string
 
251
 
 
252
        // Underlying returns the underlying error, or nil
 
253
        // if there is none.
 
254
        Underlying() error
 
255
}
 
256
```
 
257
 
 
258
Wrapper is the type of an error that wraps another error. It is exposed so that
 
259
external types may implement it, but should in general not be used otherwise.