type: system variable location: built-in source file: xleval.c Common LISP compatible: related supported on: all machines
*EVALHOOK* is a system variable whose value is user code that will intercept evaluations either through normal system evaluation or through calls to EVALHOOK. The default value for *EVALHOOK* is NIL, which specifies to use the built in system evaluator. If *EVALHOOK* is non-NIL, the routine is called with expression and environment parameters. If the environment argument is NIL, then the the current global environment is used. The environment, if non-NIL, is a structure composed of dotted pairs constructed of the symbol and its value which have the form ((( (<sym1> . <val1> ) (<sym2> . <val2> ) ... ))).
(defun myeval (exp env) ; define MYEVAL routine (princ "exp: ") (print exp) ; (princ "env: ") (print env) ; (evalhook exp #'myeval NIL env)) ; (defun foo (a) (+ a a)) ; create simple function (setq *evalhook* #'myeval) ; and install MYEVAL as hook (foo 1) ; prints ; exp: (FOO 1) env:NIL ; exp: 1 env:NIL ; exp: (+ A A) env:((((A . 1)))) ; exp: A env:((((A . 1)))) ; exp: A env:((((A . 1)))) ; returns 2 (top-level) ; to clean up *evalhook*)
NOTE: The EVALHOOK function and *EVALHOOK* system variable are very useful in the construction of debugging facilities within XLISP. The TRACE and UNTRACE functions use EVALHOOK and *EVALHOOK* to implement their functionality. The other useful aspect of EVALHOOK and *EVALHOOK* is to help in understanding how XLISP works to see the expressions, their environment and how they are evaluated.
CAUTION: Be careful when using *EVALHOOK* and EVALHOOK. If you put in a 'bad' definition into *EVALHOOK*, you might not be able to do anything and will need to exit XLISP.
UNUSUAL BEHAVIOUR: The EVALHOOK function and *EVALHOOK* system variable, by their nature, cause some unusual things to happen. After you have set *EVALHOOK* to some non-NIL value, your function will be called. However, when you are all done and set *EVALHOOK* to NIL or some other new routine, it will never be set. This is because the XEVALHOOK function (in the xlbfun.c source file) saves the old value of *EVALHOOK* before calling your routine, and then restores it after the evaluation. The mechanism to reset *EVALHOOK* is to execute the TOP-LEVEL function, which sets *EVALHOOK* to NIL.