9 The Tracer

9.2 Tracing options

There are a number of optional settings available to you when using the tracer, which allow you both to restrict and expand upon the information printed during a trace. For instance, tracing might be restricted to a particular process, or additional actions might be taken on function entry and exit. These options are specified by supplying keyword arguments in the call to trace. They are summarized below.

:after list of forms Tracer keyword

This option evaluates a list of forms upon return from the function to be traced. The forms are evaluated after the results of a call to the function are printed. Their results are also printed by the tracer.

Consider the following example:

CL-USER 7 > (trace (fac :after ('hooray)))
FAC

CL-USER 8 > (fac 2)
0 FAC > (2)
  1 FAC > (1)
  1 FAC < (2)
    HOORAY
0 FAC < (2)
  HOORAY
2

CL-USER 9 > 

More interestingly, you might use this option to print the value of some important variable which is changed during the function call but not normally printed out.

:before list of forms Tracer keyword

This option is similar to :after, except that the list of forms will be evaluated upon entry to the function rather than after it. The forms are evaluated after the arguments to the function are printed. Their results are also printed by the tracer.

:break form Tracer keyword

This option allows you to enter the debugger directly from the tracer. Its argument is a form which is evaluated after printing the standard information upon entry to the function, and after executing any :before forms. If it returns nil, tracing continues -- otherwise, break is called, and the debugger is invoked. This means that you can force entry to the debugger by supplying a form as simple as t, as in the example below:

CL-USER 9 > (trace (fac :break t))
FAC

CL-USER 10 > (fac 10)
0 FAC > (10)

Break on entry to FAC
   1 (continue) return from break . . .

:break-on-exit form Tracer keyword

This option, in common with :break, allows you to enter the debugger from the tracer, but differs in that the debugger is entered after the function call is complete. The form is evaluated after printing the standard information upon return from the function, and before executing any :after forms.

Note: The options :break and :break-on-exit force entry to the debugger even if it is currently disabled.

:entrycond form Tracer keyword

This option controls the printing of standard function-entry information. Its argument is a form which is evaluated upon entry to the function. The information is printed if and only if the form evaluates to a non-nil value. This means that you can turn off entry information printing by supplying a form of nil, as in the example below:

CL-USER 11 > (trace (fac :entrycond nil))
FAC

CL-USER 12 > (fac 2)
  1 FAC < (1)
0 FAC < (2)
2

CL-USER 13 >

:exitcond form Tracer keyword

This option controls the printing of standard function-exit information. Its argument is a form which is evaluated upon exit from the function. The information is printed if and only if the form evaluates to a non-nil value.

:trace-output stream Tracer keyword

This option allows you to direct all output from the tracer to a specified stream. By using this you can arrange to dispatch traced output from different functions to different places. Consider the following example:

CL-USER 13 > (setq str (open "trace.tra" :direction :output))
#<file-stream "D:\\FREELISP\\TRACE.TRA">

CL-USER 14 > (trace (fac :trace-output str)) FAC

CL-USER 15 > (fac 3) 6

CL-USER 16 > (untrace) NIL

CL-USER 17 > (close str) NIL

CL-USER 18 >

If you now inspect the file trace.tra, you will see the trace output for the call of (fac 3).

:eval-before list of forms Tracer keyword

This option allows you to supply a list of forms for evaluation upon entering the function. The forms are evaluated after printing out the arguments to the function, but unlike :before their results are not printed.

:eval-after list of forms Tracer keyword

This option allows you to supply a list of forms for evaluation upon leaving the function. The forms are evaluated after printing out the results of the function call, but unlike :after their results are not printed.

:step form Tracer keyword

This option puts the tracer into stepping mode, where interpreted code is printed out one step of execution at a time. Its argument is a form which must evaluate to a non-nil value if stepping is to be switched on. See "The stepper" on page 125.


FreeLisp User's Guide - 5 FEB 1996

Generated with Harlequin WebMaker