Diagnostic Evaluation Under Interactive Control
DESCRIPTION:
Facilitates controlled evaluation of function calls with user-directed starting and stopping, function tracking reports, and interactive examination or modification of S-PLUS frame objects.
USAGE: 
inspect(x, error.action=<<see below>>)
REQUIRED ARGUMENTS:
x:
a function call, exactly as it would appear at the S-PLUS prompt.
OPTIONAL ARGUMENTS:
error.action:
a function (with no arguments) to be called when an error or interrupt occurs. This will temporarily replace the system default options("error") for the duration of inspect. An expression is also accepted. The value NULL eliminates the error action. The default error.action under inspect calls traceback to print the sequence of function calls at the time of the error, then calls dump.frames, then starts a restricted version of the inspect shell. See the DETAILS section.
VALUE:
The value returned by the function call.
SIDE EFFECTS:
Objects are created on the expression frame (frame 1). Altering these will corrupt the inspect session. Among them are versions of functions which have been entered, tracked, or marked (see below). All frame 1 objects are removed at the end of any top level expression, in this case the call to inspect.

A few objects are also created in the local frames of functions entered, tracked, or marked. These have names which are unlikely to cause conflicts. However, their presence may break code which relies on the number of local objects.

The number of the frame in which a function is evaluated will differ from what it is under normal evaluation. But the relative frame parentage is preserved, of course.

Output produced by inspect appears on the standard output, and is therefore vulnerable to redirection with sink.

DETAILS:
inspect provides a user-controlled environment for diagnostic evaluation of an S-PLUS expression. Its functionality has much in common with other interactive language debuggers. It is intended to be called only from the top level (prompt). inspect(f(x)) arranges for evaluation to be suspended at the top of f, then begins evaluation of f(x). At this (and every other) break point, the prompt "d>" is presented, and input is read from the terminal. The input must match one of the instructions known to inspect. These instructions are not S-PLUS expressions, but together define a debugger shell through which you examine and modify S-PLUS objects in any frame, search for S-PLUS objects by name, look at function return values and on.exit expressions, track functions with your own entry and exit expressions, set new break points ("marks"), descend into subfunctions, and continue evaluation,

The instruction help prints a complete list of instructions, an excerpt of which is included below. The syntax and a detailed description of each is available with help <instruction>.

The default error.action starts a restricted version of the inspect shell on error, which allows examination of the state of the evaluator at the time of the error. You may examine frame and database objects, move among extant frames, and evaluate S-PLUS expressions you type in. Use quit to return to the top-level S-PLUS prompt.

Overview of instructions: Advance evaluation: step - walk through expressions complete - a loop or function resume - continue evaluation to next mark enter - descend into a function call quit - abandon inspect()

Display: where - print current function calls and current expression objects - names of objects in the local frame find - the location of an S-PLUS object show - installed tracks and marks

Halt evaluation; track functions: mark, unmark - arrange to stop in a function or at an expression track, untrack - install/change/remove function call reporting

Examine other current frames: up, down

Miscellaneous: eval - evaluate S-PLUS expressions you type in help - print instruction syntax and description

SEE ALSO:
browser , dump.frames , traceback , debugger , sys.status , trace, options .
EXAMPLES: 
   inspect(f(x))
   my.error.function <- function() cat("This is called on error.\n")
   inspect(f(x), my.error.function)