Next: , Previous: Program development, Up: Program development


5.1 The Tracer

The Tracer causes selected functions to be traced. When such a traced function is invoked, it prints

       level > (name   arg1   ...   argn)

On return from a traced function, it prints

       < level  (name   value1   ...   valuen)

name is the name of the traced function, args are the arguments, and values are the return values. level is a number which is incremented each time a traced function is invoked and is decremented at the completion of the invocation. Trace print-outs are indented according to the level.

In the current version of ECL, macros and special forms cannot be traced.

— Macro: trace {function-name | (function-name {&key form}*)}*

Causes one or more functions to be traced. Each function-name must be a symbol which is not evaluated. If a function is called from a compiled function in the same file, tracing will not be enabled. If this is the case, to enable tracing, recompile the caller with a notinline declaration for the called function. trace returns a name list of those functions that were traced by the call to trace. If no function-name is given, trace simply returns a name list of all the currently traced functions.

Trace options can cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options. form is an expression to be evaluated in an environment where sys::arglist is bound to the current list of arguments to the function.

The following options are defined:

:cond form
:cond-before form
:cond-after form
If :cond-before is specified, then trace does nothing unless form evaluates to true at the time of the call. :cond-after is similar, but suppresses the initial printout, and is tested when the function returns. :cond tries both before and after.
:step form
If form evaluates to true, the stepper is entered.
:break form
:break-after form
If specified, and form evaluates to true, then the debugger is invoked at the start of the function or at the end of the function according to the respective option.
:print form
:print-after form
In addition to the usual printout, the result of evaluating form is printed at the start of the function or at the end of the function, according to the respective option. Multiple print options cause multiple values to be

— Macro: untrace {function-name}*

Causes the specified functions to be not traced any more. function-names must be symbols and they are not evaluated. untrace returns a name list of those functions that were untraced by the call to untrace. If no function-name is given, untrace will untrace all the currently traced functions and will return a list of their names.