/
conditionCall.condition.html
265 lines (227 loc) · 9.56 KB
/
conditionCall.condition.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Condition Handling and Recovery</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="R.css">
</head><body>
<table width="100%" summary="page for conditions"><tr><td>conditions</td><td align="right">R Documentation</td></tr></table>
<h2>Condition Handling and Recovery</h2>
<h3>Description</h3>
<p>These functions provide a mechanism for handling unusual conditions,
including errors and warnings.
</p>
<h3>Usage</h3>
<pre>
tryCatch(expr, ..., finally)
withCallingHandlers(expr, ...)
signalCondition(cond)
simpleCondition(message, call = NULL)
simpleError (message, call = NULL)
simpleWarning (message, call = NULL)
simpleMessage (message, call = NULL)
## S3 method for class 'condition'
as.character(x, ...)
## S3 method for class 'error'
as.character(x, ...)
## S3 method for class 'condition'
print(x, ...)
## S3 method for class 'restart'
print(x, ...)
conditionCall(c)
## S3 method for class 'condition'
conditionCall(c)
conditionMessage(c)
## S3 method for class 'condition'
conditionMessage(c)
withRestarts(expr, ...)
computeRestarts(cond = NULL)
findRestart(name, cond = NULL)
invokeRestart(r, ...)
invokeRestartInteractively(r)
isRestart(x)
restartDescription(r)
restartFormals(r)
.signalSimpleWarning(msg, call)
.handleSimpleError(h, msg, call)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>c</code></td>
<td>
<p>a condition object.</p>
</td></tr>
<tr valign="top"><td><code>call</code></td>
<td>
<p>call expression.</p>
</td></tr>
<tr valign="top"><td><code>cond</code></td>
<td>
<p>a condition object.</p>
</td></tr>
<tr valign="top"><td><code>expr</code></td>
<td>
<p>expression to be evaluated.</p>
</td></tr>
<tr valign="top"><td><code>finally</code></td>
<td>
<p>expression to be evaluated before returning or exiting.</p>
</td></tr>
<tr valign="top"><td><code>h</code></td>
<td>
<p>function.</p>
</td></tr>
<tr valign="top"><td><code>message</code></td>
<td>
<p>character string.</p>
</td></tr>
<tr valign="top"><td><code>msg</code></td>
<td>
<p>character string.</p>
</td></tr>
<tr valign="top"><td><code>name</code></td>
<td>
<p>character string naming a restart.</p>
</td></tr>
<tr valign="top"><td><code>r</code></td>
<td>
<p>restart object.</p>
</td></tr>
<tr valign="top"><td><code>x</code></td>
<td>
<p>object.</p>
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
<p>additional arguments; see details below.</p>
</td></tr>
</table>
<h3>Details</h3>
<p>The condition system provides a mechanism for signaling and
handling unusual conditions, including errors and warnings.
Conditions are represented as objects that contain information
about the condition that occurred, such as a message and the call in
which the condition occurred. Currently conditions are S3-style
objects, though this may eventually change.
</p>
<p>Conditions are objects inheriting from the abstract class
<code>condition</code>. Errors and warnings are objects inheriting
from the abstract subclasses <code>error</code> and <code>warning</code>.
The class <code>simpleError</code> is the class used by <code>stop</code>
and all internal error signals. Similarly, <code>simpleWarning</code>
is used by <code>warning</code>, and <code>simpleMessage</code> is used by
<code>message</code>. The constructors by the same names take a string
describing the condition as argument and an optional call. The
functions <code>conditionMessage</code> and <code>conditionCall</code> are
generic functions that return the message and call of a condition.
</p>
<p>Conditions are signaled by <code>signalCondition</code>. In addition,
the <code>stop</code> and <code>warning</code> functions have been modified to
also accept condition arguments.
</p>
<p>The function <code>tryCatch</code> evaluates its expression argument
in a context where the handlers provided in the <code>...</code>
argument are available. The <code>finally</code> expression is then
evaluated in the context in which <code>tryCatch</code> was called; that
is, the handlers supplied to the current <code>tryCatch</code> call are
not active when the <code>finally</code> expression is evaluated.
</p>
<p>Handlers provided in the <code>...</code> argument to <code>tryCatch</code>
are established for the duration of the evaluation of <code>expr</code>.
If no condition is signaled when evaluating <code>expr</code> then
<code>tryCatch</code> returns the value of the expression.
</p>
<p>If a condition is signaled while evaluating <code>expr</code> then
established handlers are checked, starting with the most recently
established ones, for one matching the class of the condition.
When several handlers are supplied in a single <code>tryCatch</code> then
the first one is considered more recent than the second. If a
handler is found then control is transferred to the
<code>tryCatch</code> call that established the handler, the handler
found and all more recent handlers are disestablished, the handler
is called with the condition as its argument, and the result
returned by the handler is returned as the value of the
<code>tryCatch</code> call.
</p>
<p>Calling handlers are established by <code>withCallingHandlers</code>. If
a condition is signaled and the applicable handler is a calling
handler, then the handler is called by <code>signalCondition</code> in
the context where the condition was signaled but with the available
handlers restricted to those below the handler called in the
handler stack. If the handler returns, then the next handler is
tried; once the last handler has been tried, <code>signalCondition</code>
returns <code>NULL</code>.
</p>
<p>User interrupts signal a condition of class <code>interrupt</code> that
inherits directly from class <code>condition</code> before executing the
default interrupt action.
</p>
<p>Restarts are used for establishing recovery protocols. They can be
established using <code>withRestarts</code>. One pre-established restart is
an <code>abort</code> restart that represents a jump to top level.
</p>
<p><code>findRestart</code> and <code>computeRestarts</code> find the available
restarts. <code>findRestart</code> returns the most recently established
restart of the specified name. <code>computeRestarts</code> returns a
list of all restarts. Both can be given a condition argument and
will then ignore restarts that do not apply to the condition.
</p>
<p><code>invokeRestart</code> transfers control to the point where the
specified restart was established and calls the restart's handler with the
arguments, if any, given as additional arguments to
<code>invokeRestart</code>. The restart argument to <code>invokeRestart</code>
can be a character string, in which case <code>findRestart</code> is used
to find the restart.
</p>
<p>New restarts for <code>withRestarts</code> can be specified in several ways.
The simplest is in <code>name=function</code> form where the function is
the handler to call when the restart is invoked. Another simple
variant is as <code>name=string</code> where the string is stored in the
<code>description</code> field of the restart object returned by
<code>findRestart</code>; in this case the handler ignores its arguments
and returns <code>NULL</code>. The most flexible form of a restart
specification is as a list that can include several fields, including
<code>handler</code>, <code>description</code>, and <code>test</code>. The
<code>test</code> field should contain a function of one argument, a
condition, that returns <code>TRUE</code> if the restart applies to the
condition and <code>FALSE</code> if it does not; the default function
returns <code>TRUE</code> for all conditions.
</p>
<p>One additional field that can be specified for a restart is
<code>interactive</code>. This should be a function of no arguments that
returns a list of arguments to pass to the restart handler. The list
could be obtained by interacting with the user if necessary. The
function <code>invokeRestartInteractively</code> calls this function to
obtain the arguments to use when invoking the restart. The default
<code>interactive</code> method queries the user for values for the
formal arguments of the handler function.
</p>
<p><code>.signalSimpleWarning</code> and <code>.handleSimpleError</code>
are used internally and should not be called directly.
</p>
<h3>References</h3>
<p>The <code>tryCatch</code> mechanism is similar to Java
error handling. Calling handlers are based on Common Lisp and
Dylan. Restarts are based on the Common Lisp restart mechanism.</p>
<h3>See Also</h3>
<p><code>stop</code> and <code>warning</code> signal conditions,
and <code>try</code> is essentially a simplified version of <code>tryCatch</code>.
</p>
<h3>Examples</h3>
<pre>
tryCatch(1, finally=print("Hello"))
e <- simpleError("test error")
## Not run:
stop(e)
tryCatch(stop(e), finally=print("Hello"))
tryCatch(stop("fred"), finally=print("Hello"))
## End(Not run)
tryCatch(stop(e), error = function(e) e, finally=print("Hello"))
tryCatch(stop("fred"), error = function(e) e, finally=print("Hello"))
withCallingHandlers({ warning("A"); 1+2 }, warning = function(w) {})
## Not run:
{ withRestarts(stop("A"), abort = function() {}); 1 }
## End(Not run)
withRestarts(invokeRestart("foo", 1, 2), foo = function(x, y) {x + y})
##--> More examples are part of
##--> demo(error.catching)
</pre>
</body></html>