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 測試條件是否已發出信號並可與上述多個處理程序配合使用。