Package:LISP
Syntax:
(trace {function-name}*)
Traces the specified functions. With no FUNCTION-NAMEs, returns a list of
functions currently being traced.
Additional Keywords are allowed in GCL with the
syntax (trace {fn | (fn {:kw form}*)}*)
For each FN naming a function, traces that function. Each :KW should
be one of the ones listed below, and FORM should have the
corresponding form. No :KW may be given more than once for the same
FN. Returns a list of all FNs now traced which weren't already
traced.
EXAMPLE (Try this with your favorite factorial function FACT):
;; print entry args and exit values
(trace FACT)
;; Break coming out of FACT if the value is bigger than 1000.
(trace (fact :exit
(progn
(if (> (car values) 1000)(break "big result"))
(car values))))
;; Hairy example:
;;make arglist available without the si:: prefix
(import 'si::arglist)
(trace (fact
:DECLARATIONS
((in-string "Here comes input: ")
(out-string "Here comes output: ")
all-values
(silly (+ 3 4)))
:COND
(equal (rem (car arglist) 2) 0)
:ENTRY
(progn
(cond
((equal (car arglist) 8)
(princ "Entering FACT on input 8!! ")
(setq out-string "Here comes output from inside (FACT 8): "))
(t
(princ in-string)))
(car arglist))
:EXIT
(progn
(setq all-values (cons (car values) all-values))
(princ out-string)
(when (equal (car arglist) 8)
;; reset out-string
(setq out-string "Here comes output: "))
(cons 'fact values))
:ENTRYCOND
(not (= (car arglist) 6))
:EXITCOND
(not (= (car values) (* 6 (car arglist))))
:DEPTH
5))
Syntax is :keyword form1 :keyword form2 ...
:declarations
-
DEFAULT: NIL
FORM is ((var1 form1 )(var2 form2 )...), where
the var_i are symbols distinct from each other and from
all symbols which are similarly declared for currently
traced functions. Each form is evaluated immediately.
Upon any invocation of a traced function when not already
inside a traced function call, each var is bound to
that value of form .
:COND
-
DEFAULT: T
Here, FORM is any Lisp form to be evaluated (by EVAL)
upon entering a call of FN, in the environment where si::ARGLIST
is bound to the current list of arguments of FN. Note that
even if the evaluation of FORM changes the value of SI::ARGLIST
(e.g. by evaluation of (SETQ si::ARGLIST ...)), the list of
arguments passed to FN is unchanged. Users may alter args passed
by destructively modifying the list structure of SI::ARGLIST
however. The call is traced
(thus invoking the :ENTRYCOND and :EXITCOND forms, at least)
if and only if FORM does not evaluate to NIL.
:ENTRYCOND
-
DEFAULT: T
This is evaluated (by EVAL) if the :COND form evaluates to
non-NIL, both in an environment where SI::ARGLIST is bound to the
current list of arguments of FN. If non-NIL, the :ENTRY form
is then evaluated and printed with the trace "prompt".
:ENTRY
-
DEFAULT: (CONS (QUOTE x) SI::ARGLIST),
where x is the symbol we call FN
If the :COND and :ENTRYCOND forms evaluate to non-NIL,
then the trace "prompt" is printed and then this FORM is
evaluated (by EVAL) in an environment where SI::ARGLIST is bound
to the current list of arguments of FN. The result is then
printed.
:EXITCOND
-
DEFAULT: T
This is evaluated (by EVAL) in the environment described
below for the :EXIT form. The :EXIT form is then evaluated
and printed with the "prompt" if and only if the result here
is non-NIL.
:EXIT
-
DEFAULT: (CONS (QUOTE x) VALUES),
where x is the symbol we call FN
Upon exit from tracing a given call, this FORM is
evaluated (after the appropriate trace "prompt" is printed),
using EVAL in an environment where SI::ARGLIST is bound to the
current list of arguments of FN and VALUES is bound to the
list of values returned by FN (recalling that Common Lisp
functions may return multiple values).
:DEPTH
-
DEFAULT: No depth limit
FORM is simply a positive integer specifying the maximum
nesting of traced calls of FN, i.e. of calls of FN in which
the :COND form evaluated to non-NIL. For calls of FN in
which this limit is exceeded, even the :COND form is not
evaluated, and the call is not traced.
|