[unix-history] / .ref-BSD-3 / usr / doc / lisp / ch11.n

.Lc The\ Joseph\ Lister\ Trace\ Package 11
.de Tf
.sp 2v
.ti -.5i
\fB\\$1\fP - 
..
.pp
The trace package is an important tool for interactive debugging of a Lisp
program.
It allows you to examine selected  calls to a function or functions, and
optionally to stop execution of the Lisp program to examine the contents
of variables.
.pp
The trace package is a set of Lisp programs located in the Lisp program 
library (usually in the file /usr/lib/lisp/trace.l).
To load the trace package into Lisp, type
.b "(load 'trace)" .
There are two user callable functions  in the trace package: 
.i trace 
and 
.i untrace .
Both functions are nlambdas (their arguments are not evaluated).
The form of a call to 
.i trace
is 
.br
.tl ''\fB(trace \fIarg1 arg2 ...\fB)\fR''
where the 
.i argi
have one of the following forms:
.in .75i
.Tf "foo"
when foo is entered and exited, the trace information will be printed.
.Tf "(foo break)"
when foo is entered and exited the trace information will be printed.
Also, just after the trace information for foo is printed upon entry,
you will be put in  a special break loop.
The prompt is `T>' and you may type and Lisp expression, and see its
value printed.
The 
.i i th 
argument to the function just called can be accessed as (arg i).
To leave the trace loop, just type ^D and execution will continue.
.Tf "(foo if expression)"
when foo is entered and the expression evaluates to non nil, then the
trace information will be printed for both exit and entry.
If expression evaluates to nil, then no trace information will be
printed.
.Tf "(foo ifnot expression)"
when foo is entered and the expression evaluates to nil, then the
trace information will be printed for both entry and exit.
.Tf "(foo evalin expression)"
when foo is entered and after the entry trace information is printed,
expression will be evaluated. 
Exit trace information will be printed when foo exits.
.Tf "(foo evalout expression)"
when foo is entered, entry trace information will be printed.
When foo exits, and before the exit trace information is printed,
expression will be evaluated.
.Tf "(foo evalinout expression)"
this has the same effect as (trace (foo evalin expression evalout expression)).
Commit	Line	Data
550cf40a JF	1	.Lc The\ Joseph\ Lister\ Trace\ Package 11
	2	.de Tf
	3	.sp 2v
	4	.ti -.5i
	5	\fB\\$1\fP -
	6	..
	7	.pp
	8	The trace package is an important tool for interactive debugging of a Lisp
	9	program.
	10	It allows you to examine selected calls to a function or functions, and
	11	optionally to stop execution of the Lisp program to examine the contents
	12	of variables.
	13	.pp
	14	The trace package is a set of Lisp programs located in the Lisp program
	15	library (usually in the file /usr/lib/lisp/trace.l).
	16	To load the trace package into Lisp, type
	17	.b "(load 'trace)" .
	18	There are two user callable functions in the trace package:
	19	.i trace
	20	and
	21	.i untrace .
	22	Both functions are nlambdas (their arguments are not evaluated).
	23	The form of a call to
	24	.i trace
	25	is
	26	.br
	27	.tl ''\fB(trace \fIarg1 arg2 ...\fB)\fR''
	28	where the
	29	.i argi
	30	have one of the following forms:
	31	.in .75i
	32	.Tf "foo"
	33	when foo is entered and exited, the trace information will be printed.
	34	.Tf "(foo break)"
	35	when foo is entered and exited the trace information will be printed.
	36	Also, just after the trace information for foo is printed upon entry,
	37	you will be put in a special break loop.
	38	The prompt is `T>' and you may type and Lisp expression, and see its
	39	value printed.
	40	The
	41	.i i th
	42	argument to the function just called can be accessed as (arg i).
	43	To leave the trace loop, just type ^D and execution will continue.
	44	.Tf "(foo if expression)"
	45	when foo is entered and the expression evaluates to non nil, then the
	46	trace information will be printed for both exit and entry.
	47	If expression evaluates to nil, then no trace information will be
	48	printed.
	49	.Tf "(foo ifnot expression)"
	50	when foo is entered and the expression evaluates to nil, then the
	51	trace information will be printed for both entry and exit.
	52	.Tf "(foo evalin expression)"
	53	when foo is entered and after the entry trace information is printed,
	54	expression will be evaluated.
	55	Exit trace information will be printed when foo exits.
	56	.Tf "(foo evalout expression)"
	57	when foo is entered, entry trace information will be printed.
	58	When foo exits, and before the exit trace information is printed,
	59	expression will be evaluated.
	60	.Tf "(foo evalinout expression)"
	61	this has the same effect as (trace (foo evalin expression evalout expression)).