Interrupt the execution of an expression and allow the inspection of the environment where
browser was called from.
browser(text = "", condition = NULL, expr = TRUE, skipCalls = 0L)
- a text string that can be retrieved once the browser is invoked.
- a condition that can be retrieved once the browser is invoked.
- An expression, which if it evaluates to
TRUEthe debugger will invoked, otherwise control is returned directly.
- how many previous calls to skip when reporting the calling context.
A call to
browser can be included in the body of a function. When reached, this causes a pause in the execution of the current expression and allows access to the R interpreter.
The purpose of the
condition arguments are to allow helper programs (e.g. external debuggers) to insert specific values here, so that the specific call to browser (perhaps its location in a source file) can be identified and special processing can be achieved. The values can be retrieved by calling
The purpose of the
expr argument is to allow for the illusion of conditional debugging. It is an illusion, because execution is always paused at the call to browser, but control is only passed to the evaluator described below if
expr evaluates to
TRUE. In most cases it is going to be more efficient to use an
if statement in the calling program, but in some cases using this argument will be simpler.
skipCalls argument should be used when the
browser() call is nested within another debugging function: it will look further up the call stack to report its location.
At the browser prompt the user can enter commands or R expressions, followed by a newline. The commands are
- (or just an empty line, by default) exit the browser and continue execution at the next statement.
- synonym for
- enter the step-through debugger if the function is interpreted. This changes the meaning of
c: see the documentation for
debug. For byte compiled functions
nis equivalent to
- print a stack trace of all active function calls.
- exit the browser and the current evaluation and return to the top-level prompt.
(Leading and trailing whitespace is ignored, except for an empty line).
Anything else entered at the browser prompt is interpreted as an R expression to be evaluated in the calling environment: in particular typing an object name will cause the object to be printed, and
ls() lists the objects in the calling frame. (If you want to look at an object with a name such as
n, print it explicitly.)
The number of lines printed for the deparsed call can be limited by setting
TRUE disables the use of an empty line as a synonym for
c. If this is done, the user will be re-prompted for input until a valid command or an expression is entered.
This is a primitive function but does argument matching in the standard way.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer.
Documentation reproduced from R 2.15.3. License: GPL-2.