browser
Environment Browser
Interrupt the execution of an expression and allow the inspection of
the environment where browser
was called from.
- Keywords
- programming, environment
Usage
browser(text = "", condition = NULL, expr = TRUE, skipCalls = 0L)
Arguments
- text
a text string that can be retrieved once the browser is invoked.
- condition
a condition that can be retrieved once the browser is invoked.
- expr
An expression, which if it evaluates to
TRUE
the debugger will invoked, otherwise control is returned directly.- skipCalls
how many previous calls to skip when reporting the calling context.
Details
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 text
and 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 browserText
and browserCondition
.
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.
The 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
c
exit the browser and continue execution at the next statement.
cont
synonym for
c
.f
finish execution of the current loop or function
help
print this list of commands
n
evaluate the next statement, stepping over function calls. For byte compiled functions interrupted by
browser
calls,n
is equivalent toc
.s
evaluate the next statement, stepping into function calls. Again, byte compiled functions make
s
equivalent toc
.where
print a stack trace of all active function calls.
r
invoke a
"resume"
restart if one is available; interpreted as an R expression otherwise. Typically"resume"
restarts are established for continuing from user interrupts.Q
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.
Handling of empty lines depends on the "browserNLdisabled"
option; if it is TRUE
, empty lines are ignored.
If not, an empty line is the same as n
(or s
, if it was used
most recently).
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, or use autoprint via (n)
.
The number of lines printed for the deparsed call can be limited by
setting options(deparse.max.lines)
.
The browser prompt is of the form Browse[n]>
: here
var{n}
indicates the ‘browser level’. The browser can
be called when browsing (and often is when debug
is in
use), and each recursive call increases the number. (The actual
number is the number of ‘contexts’ on the context stack: this
is usually 2
for the outer level of browsing and 1
when
examining dumps in debugger
.)
This is a primitive function but does argument matching in the standard way.
References
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.
See Also
debug
, and
traceback
for the stack on error.
browserText
for how to retrieve the text and condition.
Community examples
[Exercise files for LinkedIn Learning](https://linkedin-learning.pxf.io/rweekly_browser) ```r printMyNumber <- function (aNumber) { print(aNumber) } thisisafunction <- function(someNumber) { keepRunning <- TRUE browser() while(isTRUE(keepRunning)) { printMyNumber(someNumber) } } thisisafunction(4) ```
Here's a not-very optimal function for calculating the total string length of a list of character vectors. ```{r} total_string_length <- function(x) { n_chars <- sapply(x, nchar) sum(n_chars) } baudrillard <- list( "Like", "dreams", ",", "statistics", "are", "a", "form", "of", "wish", "fulfillment." ) total_string_length(baudrillard) ``` It fails in the call to sum when you pass it an empty list. ```{r} total_string_length <- function(x) { n_chars <- sapply(x, nchar) sum(n_chars) } tryCatch( total_string_length(list()), error = function(e) { print(e) } ) ``` To see what is going wrong, add a call to `browser()` inside the function before the line where the error occurs. ```{r} total_string_length <- function(x) { n_chars <- sapply(x, nchar) browser() sum(n_chars) } ``` Now re-run the problem code. Execution halts inside the function. (Though note that `browser()` is not currently supported by DataCamp Light. Try it on your own machine.) ```{r} total_string_length <- function(x) { n_chars <- sapply(x, nchar) browser() sum(n_chars) } total_string_length(list()) ``` Try typing ls.str() to inspect the variables inside total_string_length. Notice that n_chars is a list, not the integer vector that we expected. You can fix the function by returning 0 when x has length zero, or by changing sapply to vapply. Press `'Q'` to quit browsing, and remember to remove the call to browser when you are finished debugging.