Browse Interactively in a Function's Frame

DESCRIPTION:

Allows the user to inspect the contents of a function's frame. This is useful when debugging a function.

USAGE:

browser.default(object=<<see below>>, catch=T, parent=<<see below>>,
         message=NULL, prompt="b> ", readonly=F, verbose=F, ...)

OPTIONAL ARGUMENTS:

object
the S-PLUS object 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 browser() to a function allows you to see what the function has done so far.
catch
logical flag: should errors and interrupts be caught in the browser? If TRUE, then the browser will be restarted after such errors. (However, see the quit signal comment below.) If FALSE, any errors will cause a return to the S-PLUS prompt level.
parent
the frame to use as the parent of the evaluation frame. By default it is sys.parent(1) if object is present and sys.parent(2) if it is not.
message
text to be printed instead of the standard "Browser called from: ..." message.
prompt
character string to be used as the prompt within the browser call.
readonly
logical flag: if FALSE and if frame is missing or numeric, assignments will cause changes in the corresponding evaluation frame that persist after the return from browser.default.
verbose
logical flag: if TRUE, the browser prints much more text to the screen in response to browser actions.

VALUE:

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.

SIDE EFFECTS:

the values of objects are printed if requested. Assignments are also made if readonly is FALSE and frame is missing or numeric.

DETAILS:

When the browser is invoked, you will be prompted for input. The input can be any expression; this will be evaluated in frame. Three kinds of expressions are special. The response ? will get you a list of commands available in the browser:

up,down

navigate between frames.

q
exit from the browser and continue.
stop
stop the top-level task.
where
show the current location in the function call stack.

A return expression returns from the browser with this value.

Assignment expressions are worth considering, also. If browser is called without an explicit frame argument, as in the example, assignments 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 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.

This is the default method for the generic function browser .

The commands up, down , stop , where , and q are implemented using the auxiliary functions upBrowser , downBrowser , stopBrowser , whereBrowser , and qBrowser, respectively. If the function you are browsing has arguments matching these command names, you can perform the desired action by calling the associated *Browser function directly. For example, qBrowser() will quit the browser and return you to the S-PLUS prompt.

SEE ALSO:

, , , , , .

EXAMPLES:

trace(foo, browser)  # call browser on entering foo
options(interrupt=browser)
myfun <- function(x,y) {
        # lots of computing
        browser() # now check things just before the moment of truth
        .C("myroutine",x,y,w)
}