Scieneer Common Lisp 1.3.9 online documentation

trace &rest specs[Macro]

trace {option global-value}* {name {option value}*}*

trace is a debugging tool that prints information when specified functions are called. In its simplest form:
(trace name-1 name-2 ...)

trace causes a printout on *trace-output* each time that one of the named functions is entered or returns (the Names are not evaluated.) The output is indented according to the number of pending traced calls, and this trace depth is printed at the beginning of each line of output.

Options allow modification of the default behavior. Each option is a pair of an option keyword and a value form. Options may be interspersed with function names. Options only affect tracing of the function whose name they appear immediately after. Global options are specified before the first name, and affect all functions traced by a given use of trace.

The following options are defined:

:condition form :condition-after form :condition-all form
If :condition is specified, then trace does nothing unless form evaluates to true at the time of the call. :condition-after is similar, but suppresses the initial printout, and is tested when the function returns. :condition-all tries both before and after.
:wherein names
If specified, names is a function name or list of names. trace does nothing unless a call to one of those functions encloses the call to this function (i.e. it would appear in a backtrace.) Anonymous functions have string names like "defun foo".
:break form :break-after form :break-all form
If specified, and form evaluates to true, then the debugger is invoked at the start of the function, at the end of the function, or both, according to the respective option.
:print form :print-after form :print-all form
In addition to the usual printout, he result of evaluating form is printed at the start of the function, at the end of the function, or both, according to the respective option. Multiple print options cause multiple values to be printed.
:function function-form
This is a not really an option, but rather another way of specifying what function to trace. The function-form is evaluated immediately, and the resulting function is traced.
:encapsulate {:default | t | nil}
If t, the tracing is done via encapsulation, redefining the function name, rather than by modifying the function. :default is the default, and means to use encapsulation for interpreted functions and funcallable instances, breakpoints otherwise. When encapsulation is used, forms are *not* evaluated in the function's lexical environment, but debug:arg can still be used.

:condition, :break and :print forms are evaluated in the lexical environment of the called function; debug:var and debug:arg can be used. The -after and -all forms are evaluated in the null environment.