R conditions 状况处理和恢复

说明

这些函数提供了处理异常情况(包括错误和警告)的机制。

用法

tryCatch(expr, ..., finally)
withCallingHandlers(expr, ...)
globalCallingHandlers(...)

signalCondition(cond)

simpleCondition(message, call = NULL)
simpleError    (message, call = NULL)
simpleWarning  (message, call = NULL)
simpleMessage  (message, call = NULL)

errorCondition(message, ..., class = NULL, call = NULL)
warningCondition(message, ..., class = NULL, 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, ...)
tryInvokeRestart(r, ...)
invokeRestartInteractively(r)

isRestart(x)
restartDescription(r)
restartFormals(r)

suspendInterrupts(expr)
allowInterrupts(expr)

.signalSimpleWarning(msg, call)
.handleSimpleError(h, msg, call)
.tryResumeInterrupt()

参数

c	一个条件对象。
call	调用表达式。
cond	一个条件对象。
expr	要评估的表达式。
finally	返回或退出之前要计算的表达式。
h	函数。
message	字符串。
msg	字符串。
name	命名重启的字符串。
r	重新启动对象。
x	对象。
class	命名条件类的字符串。
...	附加参数；请参阅下面的详细信息。

细节

条件系统提供了一种用于发出信号和处理异常情况(包括错误和警告)的机制。条件表示为包含有关所发生条件的信息的对象，例如消息和发生条件的调用。目前的条件是 S3 风格的对象，尽管这最终可能会改变。

条件是从抽象类 condition 继承的对象。错误和警告是从抽象子类 error 和 warning 继承的对象。类simpleError 是stop 和所有内部错误信号使用的类。同样，simpleWarning 由 warning 使用，simpleMessage 由 message 使用。同名的构造函数采用一个说明条件的字符串作为参数和一个可选的调用。函数conditionMessage 和conditionCall 是返回消息和条件调用的通用函数。

函数 errorCondition 可用于构造特定类的错误条件，并将附加字段指定为 ... 参数。 warningCondition 与警告类似。

条件由 signalCondition 发出信号。此外，stop 和 warning 函数已修改为也接受条件参数。

函数 tryCatch 在 ... 参数中提供的处理程序可用的上下文中计算其表达式参数。然后在调用 tryCatch 的上下文中计算 finally 表达式；也就是说，在计算 finally 表达式时，提供给当前 tryCatch 调用的处理程序不处于活动状态。

tryCatch 的 ... 参数中提供的处理程序是在 expr 评估期间建立的。如果在计算 expr 时未发出任何条件信号，则 tryCatch 返回表达式的值。

如果在评估 expr 时发出条件信号，则将从最近建立的处理程序开始检查已建立的处理程序，以查找与条件类别匹配的处理程序。当在单个 tryCatch 中提供多个处理程序时，第一个处理程序被认为比第二个处理程序更新。如果找到处理程序，则控制权将转移到建立处理程序的 tryCatch 调用，找到处理程序并取消所有最近的处理程序，以条件作为参数调用处理程序，处理程序返回的结果为作为 tryCatch 调用的值返回。

调用处理程序由 withCallingHandlers 建立。如果发出了条件信号且适用的处理程序是调用处理程序，则 signalCondition 在发出条件信号的上下文中调用该处理程序，但可用处理程序仅限于处理程序堆栈中调用的处理程序下方的处理程序。如果处理程序返回，则尝试下一个处理程序；一旦尝试了最后一个处理程序，signalCondition 将返回 NULL 。

globalCallingHandlers 建立全局调用处理程序。仅在调用使用 withCallingHandlers 动态注册的其他处理程序后，才调用这些处理程序作为最后的手段。它们在 error 全局选项(这是用于全局处理错误的旧接口)之前调用。多次注册相同的处理程序会将该处理程序移动到堆栈顶部，这可确保首先调用它。全局处理程序是定义通用记录器(例如在全局工作区中保存最后一个错误对象)或通用恢复策略(例如通过 retry_loadNamespace 重新启动安装丢失的包)的好地方。

与 withCallingHandlers 和 tryCatch 一样，globalCallingHandlers 采用命名处理程序。与这些函数不同，它还有一个类似 options 的接口：您可以通过传递单个命名处理程序列表来建立处理程序。要注销所有全局处理程序，请提供单个'NULL'。已删除处理程序的列表会以不可见的方式返回。最后，不带参数调用 globalCallingHandlers 会明显返回当前建立的处理程序列表。

在执行默认中断操作之前，用户中断会发出直接从类 condition 继承的类 interrupt 的条件信号。

重新启动用于建立恢复协议。它们可以使用 withRestarts 建立。一种预先建立的重新启动是 abort 重新启动，它表示跳转到顶层。

findRestart 和 computeRestarts 查找可用的重新启动。 findRestart 返回指定名称的最近建立的重新启动。 computeRestarts 返回所有重新启动的列表。两者都可以被赋予一个条件参数，然后将忽略不适用于该条件的重新启动。

invokeRestart 将控制转移到建立指定重新启动的点，并使用参数(如果有)调用重新启动的处理程序，这些参数作为 invokeRestart 的附加参数给出。 invokeRestart 的重启参数可以是字符串，在这种情况下，findRestart 用于查找重启。如果没有发现重新启动，则会抛出错误。

tryInvokeRestart 是 invokeRestart 的变体，当使用 findRestart 找不到重新启动时，它会静默返回。由于给定类的条件可能会使用任意协议(错误、警告等)发出信号，因此建议在处理从外部上下文发出的条件时使用此许可变体。例如，"muffleWarning" 重新启动的调用应该是可选的，因为警告可能是由用户或来自具有 stop 或 message 协议的不同包发出的信号。仅当您可以控制信令上下文时，或者当重新启动不可用时出现逻辑错误时，才使用invokeRestart。

可以通过多种方式指定 withRestarts 的新重新启动。最简单的是 name = function 形式，其中该函数是调用重新启动时要调用的处理程序。另一个简单的变体是 name = string，其中字符串存储在 findRestart 返回的重新启动对象的 description 字段中；在这种情况下，处理程序忽略其参数并返回 NULL 。重新启动规范最灵活的形式是作为可以包含多个字段的列表，包括 handler 、 description 和 test 。 test 字段应包含一个只有一个参数的函数，即一个条件，如果重新启动适用于该条件，则返回 TRUE，如果不适用，则返回 FALSE；对于所有条件，默认函数都会返回TRUE。

可以为重新启动指定的另一个字段是 interactive 。这应该是一个没有参数的函数，它返回一个参数列表以传递给重新启动处理程序。如果需要，可以通过与用户交互来获取该列表。函数 invokeRestartInteractively 调用此函数来获取调用重新启动时要使用的参数。默认的 interactive 方法向用户查询处理函数的形式参数的值。

使用 suspendInterrupts 计算表达式时可以暂停中断。可以使用 allowInterrupts 启用中断来计算子表达式。这些函数可用于确保清理处理程序不会被中断。

.signalSimpleWarning 、 .handleSimpleError 和 .tryResumeInterrupt 在内部使用，不应直接调用。

例子

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)

参考

The tryCatch 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.

也可以看看

stop 和 warning 信号条件，而 try 本质上是 tryCatch 的简化版本。 tools 包中的 assertCondition 测试条件是否已发出信号并可与上述多个处理程序配合使用。