R语言条件处理和恢复conditionCall.condition()函数-中英文对照帮助文档

MicroRBT

        R语言条件处理和恢复conditionCall.condition()函数-中英文对照帮助文档

                                         By MicroRbt Martinez PhD

R语言函数名：conditionCall.condition()
R语言函数功能：条件处理和恢复
来自资源库：基础库（R语言自带）
conditionCall.condition()函数所属R语言包：所在R包具体名称、包功能的中英文双语描述见正文后面'--所在R语言包信息--'部分。

描述-----Description-----

These functions provide a mechanism for handling unusual conditions, including errors and warnings.
这些功能提供了一种用于处理异常情况（包括错误和警告）的机制。


使用方法-----Usage-----

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' S3 method for class 'condition'
as.character(x, ...)
## S3 method for class 'error' S3 method for class 'error'
as.character(x, ...)
## S3 method for class 'condition' S3 method for class 'condition'
print(x, ...)
## S3 method for class 'restart' S3 method for class 'restart'
print(x, ...)
conditionCall(c)
## S3 method for class 'condition' S3 method for class 'condition'
conditionCall(c)
conditionMessage(c)
## S3 method for class 'condition' 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()

参数-----Arguments-----

参数c介绍: a condition object.
条件对象。

参数call介绍: call expression.
调用表达式。

参数cond介绍: a condition object.
条件对象。

参数expr介绍: expression to be evaluated.
要评估的表达式。

参数finally介绍: expression to be evaluated before returning or exiting.
返回或退出之前要计算的表达式。

参数h介绍: function.
功能。

参数message介绍: character string.
字符串。

参数msg介绍: character string.
字符串。

参数name介绍: character string naming a restart.
命名重新启动的字符串。

参数r介绍: restart object.
重新启动对象。

参数x介绍: object.
宾语。

参数class介绍: character string naming a condition class.
命名条件类的字符串。

参数...介绍: additional arguments; see details below.
其他参数；请参阅下面的详细信息。


详情-----Details-----

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.
条件系统提供了一种用于发信号和处理异常情况（包括错误和警告）的机制。条件表示为对象，这些对象包含有关发生的条件的信息，例如消息和发生该条件的呼叫。当前条件是S3样式的对象，尽管最终可能会改变。

Conditions are objects inheriting from the abstract class condition. Errors and warnings are objects inheriting from the abstract subclasses error and warning. The class simpleError is the class used by stop and all internal error signals. Similarly, simpleWarning is used by warning, and simpleMessage is used by message. The constructors by the same names take a string describing the condition as argument and an optional call. The functions conditionMessage and conditionCall are generic functions that return the message and call of a condition.
条件是从抽象类condition继承的对象。错误和警告是从抽象子类error和warning继承的对象。类simpleError是stop和所有内部错误信号使用的类。类似地，warning使用simpleWarning，message使用simpleMessage。具有相同名称的构造函数将描述条件的字符串作为参数和可选调用。函数conditionMessage和conditionCall是返回消息和条件调用的通用函数。

The function errorCondition and warningCondition can be used to construct error conditions of a particular class with additional fields specified as the ... argument. warningCondition is analogous for warnings.
函数errorCondition和warningCondition可以用于构造特定类的错误条件，并指定其他字段作为...参数。 warningCondition与警告类似。

Conditions are signaled by signalCondition. In addition, the stop and warning functions have been modified to also accept condition arguments.
条件通过signalCondition发出信号。此外，已将stop和warning函数修改为也接受条件参数。

The function tryCatch evaluates its expression argument in a context where the handlers provided in the ... argument are available. The finally expression is then evaluated in the context in which tryCatch was called; that is, the handlers supplied to the current tryCatch call are not active when the finally expression is evaluated.
函数tryCatch在可用...参数提供的处理程序的上下文中评估其表达式参数。然后在调用tryCatch的上下文中评估finally表达式；也就是说，当计算finally表达式时，提供给当前tryCatch调用的处理程序不处于活动状态。

Handlers provided in the ... argument to tryCatch are established for the duration of the evaluation of expr. If no condition is signaled when evaluating expr then tryCatch returns the value of the expression.
在expr评估期间，建立了tryCatch的...参数中提供的处理程序。如果在评估expr时未发出任何信号，则tryCatch返回表达式的值。

If a condition is signaled while evaluating expr 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 tryCatch then the first one is considered more recent than the second. If a handler is found then control is transferred to the tryCatch 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 tryCatch call.
如果在评估expr时发出了条件信号，则将从最近建立的处理程序开始检查已建立的处理程序，以查找与条件类别匹配的处理程序。当在单个tryCatch中提供多个处理程序时，第一个处理程序被认为比第二个处理程序更新。如果找到处理程序，则将控制转移到建立该处理程序的tryCatch调用，找到该处理程序，并取消所有最近的处理程序，以该条件作为其参数调用该处理程序，并返回处理程序返回的结果为tryCatch调用的值。

Calling handlers are established by withCallingHandlers. If a condition is signaled and the applicable handler is a calling handler, then the handler is called by signalCondition 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, signalCondition returns NULL.
呼叫处理程序由withCallingHandlers建立。如果发出了条件信号，并且适用的处理程序是调用处理程序，则signalCondition会在发出条件信号的上下文中调用该处理程序，但可用处理程序仅限于在处理程序堆栈中调用的处理程序下方的处理程序。如果处理程序返回，则尝试下一个处理程序；一旦尝试了最后一个处理程序，signalCondition将返回NULL。

globalCallingHandlers establishes calling handlers globally. These handlers are only called as a last resort, after the other handlers dynamically registered with withCallingHandlers have been invoked. They are called before the error global option (which is the legacy interface for global handling of errors). Registering the same handler multiple times moves that handler on top of the stack, which ensures that it is called first. Global handlers are a good place to define a general purpose logger (for instance saving the last error object in the global workspace) or a general recovery strategy (e.g. installing missing packages via the retry_loadNamespace restart).
globalCallingHandlers全局建立调用处理程序。在调用了在withCallingHandlers动态注册的其他处理程序之后，仅将这些处理程序称为万不得已。它们在error全局选项（这是用于全局处理错误的旧界面）之前调用。多次注册同一处理程序会将该处理程序移到堆栈顶部，以确保首先调用该处理程序。全局处理程序是定义通用记录器（例如，将最后一个错误对象保存在全局工作区中）或常规恢复策略（例如，通过retry_loadNamespace重新启动安装缺少的软件包）的好地方。

Like withCallingHandlers and tryCatch, globalCallingHandlers takes named handlers. Unlike these functions, it also has an options-like interface: you can establish handlers by passing a single list of named handlers. To unregister all global handlers, supply a single 'NULL'. The list of deleted handlers is returned invisibly. Finally, calling globalCallingHandlers without arguments returns the list of currently established handlers, visibly.
与withCallingHandlers和tryCatch一样，globalCallingHandlers也采用命名处理程序。与这些功能不同，它还具有类似于optionscc的接口：您可以通过传递命名处理程序的单个列表来建立处理程序。要注销所有全局处理程序，请提供一个“ NULL”。删除的处理程序列表将不可见地返回。最后，不带参数调用globalCallingHandlers会明显返回当前建立的处理程序列表。

User interrupts signal a condition of class interrupt that inherits directly from class condition before executing the default interrupt action.
用户中断会发出信号interrupt，直接从类condition继承，然后再执行默认的中断操作。

Restarts are used for establishing recovery protocols. They can be established using withRestarts. One pre-established restart is an abort restart that represents a jump to top level.
重新启动用于建立恢复协议。可以使用withRestarts建立它们。一种预先建立的重启是abort重启，它代表跳到最高级别。

findRestart and computeRestarts find the available restarts. findRestart returns the most recently established restart of the specified name. computeRestarts 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.
findRestart和computeRestarts查找可用的重启。 findRestart返回指定名称的最近建立的重新启动。 computeRestarts返回所有重新启动的列表。两者都可以被赋予一个条件参数，然后将忽略不适用于该条件的重启。

invokeRestart 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 invokeRestart. The restart argument to invokeRestart can be a character string, in which case findRestart is used to find the restart. If no restart is found, an error is thrown.
invokeRestart会将控制权转移到指定的重新启动已建立的位置，并使用作为invokeRestart附加参数的参数（如果有）调用重新启动的处理程序。 invokeRestart的restart参数可以是字符串，在这种情况下，使用findRestart查找重启。如果找不到重新启动，则会引发错误。

tryInvokeRestart is a variant of invokeRestart that returns silently when the restart cannot be found with findRestart. Because a condition of a given class might be signalled with arbitrary protocols (error, warning, etc), it is recommended to use this permissive variant whenever you are handling conditions signalled from a foreign context. For instance, invokation of a "muffleWarnings" restart should be optional because the warning might have been signalled by the user or from a different package with the stop or message protocols. Only use invokeRestart when you have control of the signalling context, or when it is a logical error if the restart is not available.
tryInvokeRestart是invokeRestart的变体，当使用findRestart无法找到重新启动时，它将以静默方式返回。由于给定类别的条件可能会通过任意协议（错误，警告等）来发出信号，因此，当您处理从外部上下文发出的条件时，建议使用此允许的变体。例如，调用"muffleWarnings"重新启动应该是可选的，因为警告可能已经由用户发出，或者来自具有stop或message协议的其他软件包。仅在您可以控制信令上下文时才使用invokeRestart，或者如果重新启动不可用则是逻辑错误时，请使用invokeRestart。

New restarts for withRestarts can be specified in several ways. The simplest is in name = function form where the function is the handler to call when the restart is invoked. Another simple variant is as name = string where the string is stored in the description field of the restart object returned by findRestart; in this case the handler ignores its arguments and returns NULL. The most flexible form of a restart specification is as a list that can include several fields, including handler, description, and test. The test field should contain a function of one argument, a condition, that returns TRUE if the restart applies to the condition and FALSE if it does not; the default function returns TRUE for all conditions.
可以通过几种方式指定withRestarts的新重启。最简单的是name = function形式，该函数是调用重新启动时要调用的处理程序。另一个简单的变体是name = stringc，其中字符串存储在findRestart返回的重新启动对象的description字段中。在这种情况下，处理程序将忽略其参数，并返回NULL。重新启动规范的最灵活形式是一个列表，其中可以包括多个字段，包括handler，description和test。 test字段应包含一个参数的函数，一个条件，如果重新启动适用于该条件，则返回TRUE；如果不适用，则返回FALSE。在所有情况下，默认函数均返回TRUE。

One additional field that can be specified for a restart is interactive. 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 invokeRestartInteractively calls this function to obtain the arguments to use when invoking the restart. The default interactive method queries the user for values for the formal arguments of the handler function.
可以为重新启动指定的另一个字段是interactive。这应该是没有参数的函数，该函数返回要传递给重新启动处理程序的参数列表。如果需要，可以通过与用户交互来获得该列表。函数invokeRestartInteractively调用此函数以获取调用重新启动时要使用的参数。默认的interactive方法向用户查询处理函数的形式参数的值。

Interrupts can be suspended while evaluating an expression using suspendInterrupts. Subexpression can be evaluated with interrupts enabled using allowInterrupts. These functions can be used to make sure cleanup handlers cannot be interrupted.
使用suspendInterrupts评估表达式时，可以挂起中断。可以通过使用allowInterrupts启用中断来评估子表达式。这些函数可用于确保清除处理程序不会被中断。

.signalSimpleWarning, .handleSimpleError, and .tryResumeInterrupt are used internally and should not be called directly.
.signalSimpleWarning，.handleSimpleError和.tryResumeInterrupt在内部使用，不应直接调用。


参考文献-----References-----

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.

参见-----See Also-----

stop and warning signal conditions, and try is essentially a simplified version of tryCatch. assertCondition in package tools tests that conditions are signalled and works with several of the above handlers.
stop和warning信号条件，而try本质上是tryCatch的简化版本。包tools tests包中的assertCondition会发出信号通知条件，并且可以与上述几个处理程序一起使用。


代码实例-----Examples-----

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)
#->演示（error.catching）

所在R语言包信息-----R package information-----

R语言函数名：conditionCall.condition()
R语言函数功能英文描述：Condition Handling and Recovery
R语言函数功能中文描述：条件处理和恢复
所在R语言包：base
所在R包英文描述：The R Base Package
所在R包中文描述：R基础包

*使用前安装提示*：R包base来自基础库（R语言本身自带，不用下载安装，可直接运行）。

备注：
1：本文档仅供个人R语言学习参考使用，请勿