.comment -*- Mode:TEXT; -*-
.document TRACE - How to use the Lisp TRACE package to debug your programs.
.tag TRACE
Lesson TRACE, Version 2			Kent M. Pitman, 3/28/79
                             revised by Victoria Pigman, 9/1/82

This is an advanced lesson and should be saved for when you already know
a fair amount about the basics of what is going on.

Monitoring calls to a function in Maclisp is accomplished through the TRACE 
function. For example, suppose you want to know every time a function is 
called, what args it is called on and what it returns. Just saying 

	(TRACE <name1> <name2> ... <nameN>)

will trace each of <name1> through <nameN>. The <name>'s are not evaluated.
For an example, consider the following function which counts the number of
atoms in a list:

.eval-print
(DEFUN COUNT-ATOMS (X)
  (COND ((NULL X) 0.)
	((ATOM X) 1.)
	((ATOM (CAR X))
	 (+ 1. (COUNT-ATOMS (CDR X))))
	(T
	 (+ (COUNT-ATOMS (CAR X))
	    (COUNT-ATOMS (CDR X))))))


We have defined the function COUNT-ATOMS for you, so you don't have to type it
in again. If you aren't sure how it works, or some of the cases confuse you, 
you should try doing

 (TRACE COUNT-ATOMS)

and then run the function on some of the following test cases...

 (COUNT-ATOMS '(A B C))

 (COUNT-ATOMS '(A (B C) D))

 (COUNT-ATOMS '(A NIL B))
.try
When you are done tracing a function, you can make it stop printing out all
that long-winded stuff by using the untrace function. Its syntax is

  (UNTRACE <name1> <name2> ...)

so you would want to do

  (UNTRACE COUNT-ATOMS) 

to undo your trace of our function above. If you forget which functions have 
been traced, you can type 

  (TRACE) 

and it will return a list of all the functions currently being traced. Typing:

  (UNTRACE)

with no args will untrace all traced functions. These can save a bit of typing
sometimes.

Study the output from the TRACE carefully until you understand what is going 
on. It can be very useful in helping to debug complex programs.
.eof