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 a 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 here:

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 a 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 
The syntax and a detailed description of each is available with help, e.g. help step.

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.

SEE ALSO:

, , , , , , .

EXAMPLES:

   inspect(f(x)) 
   
   my.error.function <- function() cat("This is called on error.\n") 
   inspect(f(x), my.error.function)