.BG
.FN restart
.TL
Take Over Error Handling
.CS
restart(on=TRUE)
.AG on
if `TRUE', cause errors to recall the function from which `restart' was
called.
If `FALSE' error control is returned to S (but see below).
.PP
This is a function to be used only by the adept and strong at heart.
After it is called, and until a return from the function evaluation that
contained the call to `restart', all errors and interrupts, with one
exception, will not get the user back to S prompt level.
Instead, the function that called `restart' will be recalled, but with
its local frame in the state that obtained when the error occurred.
(Restart will have been cancelled at this point, but typically the
restarted function will then call `restart' again.)
.PP
The one exception is that the
quit signal (usually typed as control-backslash) will cancel unconditionally
the restart and return the user to S prompt level.
Keep in mind that a second quit signal will exit S entirely.
(The quit signal has nothing to do with the S function `q'.)
.PP
Use of restart can be dangerous to your health and social standing.
In particular, if the function calling `restart' has an error, an infinite
loop of errors can easily result.
Hence the use of quit as a loop-hole.
.PP
ALWAYS make sure that the calling function is bug-free before installing
a call to `restart'.
.EX
# prompt for expressions & evaluate them
pause <- function() {
	restart(T)
	cat("Enter expressions, q to quit from pause\\n")
	repeat {
		e <- parse(prompt = "<P> ")
		if(is.name(e[[1]]) && e[[1]]=="q")
		   return()
		print(eval(e, local = sys.parent(1)))
	}
}
# look at browser for another example
.KW programming
.WR
