:trace

Top-level Command

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 6.2
Unrevised from 6.1

:trace

Arguments: &rest function-or-option-list

When called with no arguments, all the functions currently being traced are printed, otherwise the arguments to :trace are function names (symbols) or option lists. An option list starts with a function name, and the other elements of the list are options for tracing that particular function. The options for one function do not affect the tracing of any other function. The options come in pairs, the first element of the pair being the option name (i.e., a keyword), and the second part being the option value. Missing options default to nil. Here are some valid calls to :trace:

:trace foo
:trace foo (bar :break-before t) baz
:trace (baz :inside foo :break-before t)
:trace

Note that the following is invalid:

:trace foo :inside bar

You must enclose options in a list along with the function name and the option value. If you enter the invalid case above, Lisp will complain that :inside does not have a function definition.

The minimal abbreviation of :trace is :tr.

See top-level.htm for more information on top-level commands. See debugging.htm for information on the debugger and examples of tracing.

valid options to :trace

Option	Arguments	Description
`:condition`	expr	Trace this function if expr evaluates to a true value.
`:break-before`	val	The expression val is evaluated just before entering a function. If val is `t`, then a new break level is entered. Otherwise, execution continues. When used in combination with :inside and :not-inside, breaks only occur when the :inside and :not-inside conditions are satisfied.
`:break-after`	val	The expression val is evaluated just after exiting a function. If val is `t`, then a new break level is entered. Otherwise, execution continues. When used in combination with :inside and :not-inside, breaks only occur when the :inside and :not-inside conditions are satisfied.
`:break-all`	val	The expression val is evaluated just before entering a function and just after exiting a function. If val is `t`, then a new break level is entered. Otherwise, execution continues. When used in combination with :inside and :not-inside, breaks only occur when the :inside and :not-inside conditions are satisfied.
`:inside`	func	Trace this function if Lisp is currently inside the evaluation of the function func. func may also be a list of functions, optionally starting with the symbols cl:and or cl:or. If neither symbol or cl:and starts the list (e.g. `(cl:and foo1 bar2)` or `(foo1 bar2)`, tracing is done when the function to be traced has been called directly or indirectly by all the functions in the list (by foo1 and bar2 in the example). If cl:or starts the list (e.g. `(cl:or foo1 bar2)`) tracing is done when the function to be traced has been called directly or indirectly by any the functions in the list (by foo1 or bar2 in the example). `:inside` works in combination with `:not-inside`, described next. Both must be satisified for tracing to occur. For example, `(trace (deeper :inside deep))` would trace the function deeper only when called from within a call to deep. `(trace (deeper :inside deep :not-inside (cl:or foo1 bar2)))` would trace the function deeper only when called from within a call to deep but not within a call to foo1 or bar2. See Note on inside and not inside for a fuller description of a call being inside another.
`:not-inside`	func	Trace this function if Lisp is not currently inside the evaluation of the function func. func may also be a list of functions, optionally starting with the symbols cl:and or cl:or. If neither symbol or cl:and starts the list (e.g. `(cl:and foo1 bar2)` or `(foo1 bar2)`, tracing is done when the function to be traced has not been called directly or indirectly by all the functions in the list (by foo1 and bar2 in the example). If cl:or starts the list (e.g. `(cl:or foo1 bar2)`) tracing is done when the function to be traced has not been called directly or indirectly by any the functions in the list (by foo1 or bar2 in the example). `:not-inside` works in combination with `:inside`, described above. Both must be satisified for tracing to occur. For example, `(trace (deeper :not-inside deep))` would trace the function deeper except when called from within a call to deep. `(trace (deeper :not-inside deep :inside (cl:or foo1 bar2)))` would trace the function deeper except when called from within a call to deep and within a call to foo1 or bar2. See Note on inside and not inside for a fuller description of a call being inside another.
`:print-before`	expr	expr should either be a single object or a list of objects which will be evaluated. The results will be printed before entering the function.
`:print-after`	expr	expr should either be a single object or a list of objects which will be evaluated. The results will be printed after leaving the function.
`:print-all`	expr	expr should either be a single object or a list of objects which will be evaluated. The results will be printed before entering and after leaving the function.

Note on inside and not inside

A call to function foo is inside a call to function bar if bar appears on the stack when foo is called. bar can call foo directly, meaning there is an explicit call to foo in the code defining bar, or indirectly, meaning bar calls another function which (perhaps calls more itermediate function) which calls foo directly.

There are a few special cases. One is caused by tail-merging. Thus, if bar calls baz which does a tail-merged call to foo, then foo is considered inside bar but not inside baz.

The other special case is generic functions. If a method is on the stack, its generic function is also considered to be on the stack, even though it never will be seen there (meaning you can specify the generic function rather than the specific method). Thus the following all work for tracing foo inside a call to device-read called on a terminal-simple-stream, but the first will catch calls to foo inside any device-read method.