finally

Obsluha podmínky a obnova

Popis

Soubor těchto funkcí poskytuje možnost obsluhy neobvyklých podmínek, včetně chyb a varování.

Použití

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

signalCondition(cond)

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

errorCondition(msg, ..., class = NULL, call = NULL)
warningCondition(msg, ..., class = NULL, call = NULL)

## S3 metoda pro třídu 'condition'
as.character(x, ...)
## S3 metoda pro třídu 'error'
as.character(x, ...)
## S3 metoda pro třídu 'condition'
print(x, ...)
## S3 metoda pro třídu 'restart'
print(x, ...)

conditionCall(c)
## S3 metoda pro třídu 'condition'
conditionCall(c)
conditionMessage(c)
## S3 metoda pro třídu 'condition'
conditionMessage(c)

withRestarts(expr, ...)

computeRestarts(cond = NULL)
findRestart(name, cond = NULL)
invokeRestart(r, ...)
invokeRestartInteractively(r)

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

suspendInterrupts(expr)
allowInterrupts(expr)

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

Argumenty

Detaily

Systém podmínek poskytuje možnost signalizace a obsluhy neobvyklých podmínek, včetně chyb a varování. Podmínky jsou prezentovány jako objekty obsahující dvě části: hlášení a volání. Současné podmínky jsou objekty stylu S3, což se může eventuálně změnit.

Podmínky jsou objekty děděny z abstraktní třídy condition. Chyby a varování jsou zase objekty, které se dědí z abstraktních podtříd error a warning. Třída simpleError je třídou používanou funkcí stop a všemi signalizacemi vnitřních chyb. Obdobně je i třída simpleWarning používána warning, a message používá třídu simpleMessage. Konstruktory berou řetězec, který popisuje podmínku, za stejný název jak pro argument, tak pro volitelné volání. Funkce conditionMessage a conditionCall jsou generické funkce, které navrátí hlášení a volají podmínku.

Funkce errorCondition a warningCondition mohou být použity pro vytvoření podmínky typu chyba náležící určité třídě s dodatečnými položkami specifikovanými jako argument .... Analogicky lze pohlížet na warningCondition pro varování.

Podmínky jsou signalizovány přes signalCondition. Navíc funkce stop a warning byly modifikovány, aby také přijímaly argumenty podmínky.

Funkce tryCatch vyhodnocuje své argumenty výrazu v kontextu, kde je k dispozici obsluha uvedená v argumentu .... Výraz finally je pak vyhodnocen v kontextu, kde byla volána funkce tryCatch; to znamená, že obsluha uvedená u volání tryCatch není aktivní v momentě, kdy je vyhodnocován výraz finally.

Obsluha uvedená v argumentu ... k tryCatch je ustavená po dobu vyhodnocování expr. V případě, že není po dobu vyhodnocování expr signalizována žádná podmínka, pak tryCatch vrátí hodnotu výrazu.

Je-li během vyhodnocování expr signalizována podmínka, dojde nejprve k prozkoumání, která z ustavených obsluh náleží třídě podmínky (začíná se u posledně ustavené obsluhy). Když je v jednom tryCatch uvedeno více obsluh, považuje se první za nejvíce recentní. Pokud se podaří nalézt obsluhu, je kontrola nejdříve předána volání v tryCatch, které ustanovilo nalezenou obsluhu, a následně samotné obsluze. Všechny recentnější obsluhy jsou odloučeny. Obsluha je volána podmínkou jako její argument. Výsledek, který vrátí obsluha, je vrácen jako hodnota volání tryCatch.

Obsluhy, které jsou tzv. volající (calling), mohou být ustaveny prostřednictvím withCallingHandlers. Pokud je signalizována podmínka a použitelná obsluha je volající obsluhou, dojde k jejímu volání přes signalCondition v kontextu, kde byla podmínka signalizována. Za dostupné obsluhy jsou považovány pouze ty, které se v zásobníku obsluh nacházejí pod volanou obsluhou. Pokud dojde k navrácení první vybrané obsluhy, vyzkouší se další v pořadí; v případě, že se navrátí i poslední obsluha, vrátí signalCondition hodnotu NULL.

Přerušení uživatelem signalizuje podmínku třídy interrupt, která se dědí přímo z třídy condition před vykonáním přerušení podle výchozího nastavení.

Restarty se používají k ustavení protokolu obnovy. Mohou být zřízeny skrze withRestarts. Restart abort je předen ustaveným restartem, který znamená přeskočení na nejvyšší úroveň.

findRestart a computeRestarts vyhledávají dostupné restarty. findRestart vrátí všechny nově ustavené restarty požadovaného názvu. computeRestarts navrátí seznam všech restartů. Do obou funkcí může být zadán i argument podmínky, čímž budou ignorovány ostatní restarty, které s danou podmínkou nesouvisí.

invokeRestart převádí kontrolu do místa, kde došlo k ustavení restartu a volá obsluhu restartu prostřednictvím dodatečných argumentů funkce invokeRestart. Argument restartu u invokeRestart může být řetězec znaků. V takovém případě je použitá funkce findRestart pro nalezení restartu.

Nové restarty mohou být pod withRestarts přidány několika způsoby. Nejjednodušším formátem je name = function, kde se funkcí rozumí obsluha, která se volá, když se má uplatnit restart. Další jednoduchou variantou je name = string, kde je řetězec uložen v položce description, která náleží objektu restartu navráceném funkcí findRestart; v takové případě obsluha ignoruje své argumenty a vrátí hodnotu NULL. Nejvíce flexibilním formátem, jak restart specifikovat, je seznam zahrnující mnohé položky jako handler, description, a test. Položka test by měla obsahovat funkci s jedním argumentem, a to podmínkou. Funkce pak vrátí hodnotu TRUE, pokud se restart vztahuje k uvedené podmínce, a hodnotu FALSE, pokud ne; výchozí funkce navrací TRUE pro všechny podmínky.

Další položkou, která může být pro restart specifikována, je interactive. Mělo by se jednat o funkcí bez argumentu, která navrací seznam všech argumentů vkládajících se do obsluhy restartu. Seznam může být, pokud je to nezbytné, získán ve spolupráci s uživatelem. invokeRestartInteractively volá uvedenou funkci pro zisk argumentů, které se používají při uplatňování restartu. Výchozí interactive metoda se táže uživatele na hodnoty formálních argumentů funkce obsluhy.

Přerušení může být pozastaveno, když se při vyhodnocování výrazu použije suspendInterrupts. Podvýraz je vyhodnocen s přerušením, pokud je tak umožněno přes allowInterrupts. Tyto funkce se uplatňují především tehdy, chceme-li zaručit, aby obsluha určená k úklidu nebyla přerušena.

.signalSimpleWarning, .handleSimpleError, a .tryResumeInterrupt jsou používány vnitřně a neměly by být volány přímo.

Reference

Mechanismus tryCatch je podobný obsluze chyb v Java. Tzv. volající obsluha je založená na Common Lisp a Dylan. Restarty jsou rovněž založeny na mechanismu restarů Common Lisp.

Viz také

stop a warning signalizuje podmínku a try je v podstatě zjednodušenou verzí tryCatch. assertCondition v balíku tools testuje, zda je podmínka signalizována a pracuje s mnoha výše popsanými obsluhami.

Příklady

tryCatch(1, finally = print("Hello"))
e <- simpleError("test error")
## Nespouštět:
stop(e)
tryCatch(stop(e), finally = print("Hello"))
tryCatch(stop("fred"), finally = print("Hello"))

## Konec(Nespouštět)
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) {})
## Nespouštět:
{ withRestarts(stop("A"), abort = function() {}); 1 }

## Konec(Nespouštět)
withRestarts(invokeRestart("foo", 1, 2), foo = function(x, y) {x + y})

##--> Více příkladů je součástí
##--> demo(error.catching)