.BG
.FN browser
.TL
Browse Interactively in a Function's Frame
.CS
browser(frame, catch=TRUE, message)
.AG frame
the frame in which the browser will look for information and will evaluate
user expressions.
By default this is the frame of the function calling `browser'.
Therefore in its usual use, adding the expression
.Co browser()
to a function allows you to see what the function has done so far.
.AG catch
logical; should errors and interrupts be caught in the browser?
If `TRUE', then the browser will be restarted after such errors,
but see the quit signal comment below.
If `FALSE', any errors will return to the S prompt level.
.AG message
optional text to be printed instead of the standard browser message.
.RT
the value returned in a `return' expression
typed by the user; if you return by giving a response `0' to the prompt,
the value is `NULL'.
.PP
When the browser is invoked, you will be prompted for input.
The input can be any
expression;
this will be evaluated in the `frame'.
Three kinds of expressions are special.
The response `?' will get you a list of menu-selectable items (the elements
of the frame).
A numeric response is taken to be such a selection.
A `return' expression returns
from the browser with this value.
The expression `substitute(x)' is useful to see the actual argument
that was given, corresponding to the formal argument `x'.
.PP
Assignment expressions are worth considering, also.  If `browser'
is called without an explicit frame argument, as in the example,
assignments will take place in the calling function's frame.
Thus, `browser' can be used to try out revisions in real time,
without editing the function.
A similar use can be made of the case of an explicit frame;
assignments will change the frame, as it appears inside `browser',
so that modifications in the situation as captured in `frame' (for
example, through `dump.frames' and `debugger') can be tried out
interactively.
Both these versions can be helpful in software design and debugging.
.PP
The quit signal (usually the character control-backslash) will
exit from the browser, and from the whole expression that generated the
call to the browser, returning to the S prompt level.
(Don't type two control-backslash characters, or one if
.Co catch=FALSE ; 
either action will terminate
your session with S!)
.SA
`restart', `debugger'.
.EX
myfun <- function(x,y) {
	# lots of computing
	browser() #now check things just before the moment of truth
	.C("myroutine",x,y,w)
}
.KW error
.WR
