4.6 Reference Pages

4.6.1 The Tracer

Syntax:*max-trace-indentation*

The variable*max-trace-indentation* specifies the maximum number of spaces for indentation in the trace output. The default value is 60.

> (defun recur (x) (when (> x 0) (recur (1- x))))
RECUR

> (trace recur)
(RECUR)

> (recur 2)
1 Enter RECUR 2
| 2 Enter RECUR 1
|   3 Enter RECUR 0
|   3 Exit RECUR NIL
| 2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

> (let ((*max-trace-indentation* 2)) (recur 2))
1 Enter RECUR 2
| 2 Enter RECUR 1
| 3 Enter RECUR 0
| 3 Exit RECUR NIL
| 2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

Syntax:trace {trace-spec}*

trace-spec::= function-name |
({function-name | ({function-name}+)} {keyword form}*)

keyword::=:cond |:entrycond |:exitcond |:break
|:exitbreak |:entry |:exit |:step

The macrotrace allows you to trace one or more functions and to perform certain actions at the time a function is called or at the time it returns. It returns as its value a list of names of all the functions it has traced.

You can specify the following keyword-value pairs totrace:

• :cond form

If form has a non-nil value, this keyword argument displays the trace output. This keyword argument overrides the:exitcond and:entrycond arguments; if the value of this argument isnil, no trace information is displayed. The default value of form is non-nil.

• :entrycond form

If form has a non-nil value, this keyword argument displays tracing information on entry to the traced function. The default value of form is non-nil.

• :exitcond form

If form has a non-nil value, this keyword argument displays tracing information on exit from the traced function. The default value of form is non-nil.

• :break form

If form has a non-nil value, this keyword argument calls the Debugger after the entry trace information is printed but before the traced function is applied to its arguments. The default value of form isnil.

• :exitbreak form

If form has a non-nil value, this keyword argument calls the Debugger after the traced function has been executed and the exit trace information has been printed but before control returns. The default value of form isnil.

• :entry ({form}+)

This keyword argument displays the values of the forms in the list on entry to the traced function. The displayed values are preceded by two backslashes (\\).

• :exit ({form}+)

This keyword argument displays the values of the forms in the list on exit from the traced function. The displayed values are preceded by two backslashes (\\).

• :step form

If form is non-nil, this keyword argument calls the Stepper on the traced function. The Stepper allows you to interactively step through the evaluation of a function; it is described in Section 4.3 on page 52. The default value of form isnil.

Iftrace is called with no arguments, a list of all currently traced functions is returned.

If a function is already being traced,trace callsuntrace before starting the new trace. Callinguntrace restores all functions to their normal state.

Callingtrace on a macro traces the macro expansion, not the evaluation of the form. Special forms cannot be traced because they are neither functions nor macros.

> (progn (untrace) (trace))
NIL

> (trace cdr)
(CDR)

> (trace)
(CDR)

> (cdr '(1 2))
1 Enter CDR (1 2)
1 Exit CDR (2)
(2)

> (trace (cdr :cond nil))
(CDR)

> (cdr '(1 2))
(2)

> (trace (cdr :entry ("entry banner") :exitcond nil))
(CDR)

> (cdr '(1 2))
1 Enter CDR (1 2)  \\ "entry banner"
(2)

See Also: step , untrace

Syntax:*trace-arglist*

The variable*trace-arglist* provides information on the arguments of the function that is being traced. It is bound to the traced function's argument list and is available for inspection.

You should not change the value of this variable.

> (defun empty-list (x) (if (null x) x (empty-list (cdr x))))
EMPTY-LIST

> (trace (empty-list :entry (*trace-arglist*)))
(EMPTY-LIST)

> (empty-list '(1 2 3))
1 Enter EMPTY-LIST (1 2 3)  \\ ((1 2 3))
| 2 Enter EMPTY-LIST (2 3)  \\ ((2 3))
|   3 Enter EMPTY-LIST (3)  \\ ((3))
|   | 4 Enter EMPTY-LIST NIL  \\ (NIL)
|   | 4 Exit EMPTY-LIST NIL
|   3 Exit EMPTY-LIST NIL
| 2 Exit EMPTY-LIST NIL
1 Exit EMPTY-LIST NIL
NIL

Syntax:*trace-bar-p*

The variable*trace-bar-p* controls whether columns of vertical bars are printed in the trace output. Bars are printed if the value is non-nil; otherwise, spaces are printed. The default value ist.

> (defun recur (x) (when (> x 0) (recur (1- x))))
RECUR

> (trace recur)
(RECUR)

> (recur 1)
1 Enter RECUR 1
| 2 Enter RECUR 0
| 2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

> (let ((*trace-bar-p* nil)) (recur 1))
1 Enter RECUR 1
  2 Enter RECUR 0
  2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

Syntax:*trace-columns-per-level*

The variable*trace-columns-per-level* controls how many columns are added to the trace output for each level of function call. The value must be a positive integer; the default value is 2.

> (defun recur (x) (when (> x 0) (recur (1- x))))
RECUR

> (trace recur)
(RECUR)

> (recur 1)
1 Enter RECUR 1
| 2 Enter RECUR 0
| 2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

> (let ((*trace-columns-per-level* 10)) (recur 1))
1 Enter RECUR 1
|         2 Enter RECUR 0
|         2 Exit RECUR NIL
1 Exit RECUR NIL
NIL

Syntax:*trace-level*

The variable*trace-level* represents how deeply nested a call to the macrotrace is.

The value is an integer.

> (defun recur2 (x) (unless (< x 0) (cons *trace-level* (recur2 (1- x)))))
RECUR2

> (trace recur2)
(RECUR2)

> (recur2 2)
1 Enter RECUR2 2
| 2 Enter RECUR2 1
|   3 Enter RECUR2 0
|   | 4 Enter RECUR2 -1
|   | 4 Exit RECUR2 NIL
|   3 Exit RECUR2 (3)
| 2 Exit RECUR2 (2 3)
1 Exit RECUR2 (1 2 3)
(1 2 3)

untrace-method Function

Syntax:trace-method&optional method-spec ({keyword form}*)

method-spec ::= method-object
| (generic-function-name {qualifier}* ({specializer}*))

The functiontrace-method allows you to trace the execution of a method and to perform certain actions when the method is called or when it returns. If you calltrace-method with no arguments, a list of all currently traced methods is returned.

The functionuntrace-method disables tracing for a method. If you calluntrace-method with no arguments, tracing is turned off for all methods currently being traced.

The generic-function-name argument of the optional method-spec argument is either a symbol or a list of the form(setf symbol).

The optional (keyword form) arguments totrace-method are treated like (keyword form) arguments to the macrotrace.

> (trace-method '(frobulate :before (food)))
(FROBULATE :BEFORE (FOOD))

> (frobulate d)
1 Enter #:|(METHOD FROBULATE :BEFORE (FOOD))| #<Food #X89DAB6>
1 Exit #:|(METHOD FROBULATE :BEFORE (FOOD))| NIL
NIL

> (untrace-method)
((METHOD FROBULATE :BEFORE (FOOD)))

See Also: trace, untrace

Syntax:*trace-new-definitions*

The variable*trace-new-definitions* traces all new definitions when its value is non-nil. Its default value isnil, which means that new definitions are not traced.

> (defun new1 ())
NEW1

> (trace)
NIL

> (let ((*trace-new-definitions* t)) (defun new2 ()))
NEW2

> (trace)
(NEW2)

Syntax:*trace-values*

The variable*trace-values* provides information on the returned values of the function that is currently being traced. It is bound to the traced function's list of returned values.

You can inspect*trace-values*, but you cannot control the behavior of the macrotrace with it.

> (trace (cdr :exitbreak t))
(CDR)

> (cdr '(1 2 3))
1 Enter CDR (1 2 3)
1 Exit CDR (2 3)

>>Break: Trace exit
(:ADVICE CDR :TRACE):
:C  0: Return from Break
:A  1: Abort to Lisp Top Level

-> *trace-values*
((2 3))

-> (setq *trace-values* '((override-return)))
((OVERRIDE-RETURN))

-> :c
Return from Break
(OVERRIDE-RETURN)

Syntax:*traced-function-list*

The variable*traced-function-list* returns a list of the names of all the functions that are being traced.

> *traced-function-list*
NIL

> (trace cdr car)
(CDR CAR)

> *traced-function-list*
(CAR CDR)

Syntax:untrace {function-name}*

The macrountrace restores traced functions to their normal state. It can take multiple arguments. Calling it with no arguments untraces all of the functions currently being traced.

> (progn (untrace) (trace car caar caaar))
(CAR CAAR CAAAR)

> (untrace car)
(CAR)

> (trace)
(CAAAR CAAR)

> (untrace)
(CAAR CAAAR)

> (trace)
NIL

> (untrace)
NIL

See Also: trace

Generated with Harlequin WebMaker