Copyright (c) 1980 The Regents of the University of California.
All rights reserved.
%sccs.include.redist.roff%
@(#)ch14.n 6.3 (Berkeley) 04/17/91
." $Header: /na/franz/doc/RCS/ch14.n,v 1.1 83/01/31 07:08:43 jkf Exp $ .Lc The LISP Stepper 14 .sh 2 Simple Use Of Stepping \n(ch 1 .Lf step "s_arg1..." .No The LISP "stepping" package is intended to give the LISP programmer a facility analogous to the Instruction Step mode of running a machine language program. The user interface is through the function (fexpr) step, which sets switches to put the LISP interpreter in and out of "stepping" mode. The most common step invocations follow. These invocations are usually typed at the top-level, and will take effect immediately (i.e. the next S-expression typed in will be evaluated in stepping mode). .Eb (step t) ; Turn on stepping mode. (step nil) ; Turn off stepping mode. .Ee .Se In stepping mode, the LISP evaluator will print out each S-exp to be evaluated before evaluation, and the returned value after evaluation, calling itself recursively to display the stepped evaluation of each argument, if the S-exp is a function call. In stepping mode, the evaluator will wait after displaying each S-exp before evaluation for a command character from the console. .Eb STEP COMMAND SUMMARY <return> Continue stepping recursively. c Show returned value from this level only, and continue stepping upward. e Only step interpreted code. g Turn off stepping mode. (but continue evaluation without stepping). n <number> Step through <number> evaluations without stopping p Redisplay current form in full (i.e. rebind prinlevel and prinlength to nil) b Get breakpoint q Quit d Call debug .Ee .sh 2 Advanced Features .sh 3 Selectively Turning On Stepping. If (step foo1 foo2 ...) is typed at top level, stepping will not commence immediately, but rather when the evaluator first encounters an S-expression whose car is one of foo1, foo2, etc. This form will then display at the console, and the evaluator will be in stepping mode waiting for a command character. .pp Normally the stepper intercepts calls to funcall and eval. When funcall is intercepted, the arguments to the function have already been evaluated but when eval is intercepted, the arguments have not been evaluated. To differentiate the two cases, when printing the form in evaluation, the stepper preceded intercepted calls to .i funcall with "f:". Calls to funcall are normally caused by compiled lisp code calling other functions, whereas calls to eval usually occur when lisp code is interpreted. To step only calls to eval use: (step e) .sh 3 Stepping With Breakpoints. .pp For the moment, step is turned off inside of error breaks, but not by the break function. Upon exiting the error, step is reenabled. However, executing (step nil) inside a error loop will turn off stepping globally, i.e. within the error loop, and after return has be made from the loop. .sh 2 Overhead of Stepping. .pp If stepping mode has been turned off by (step nil), the execution overhead of having the stepping packing in your LISP is identically nil. If one stops stepping by typing "g", every call to eval incurs a small overhead--several machine instructions, corresponding to the compiled code for a simple cond and one function pushdown. Running with (step foo1 foo2 ...) can be more expensive, since a member of the car of the current form into the list (foo1 foo2 ...) is required at each call to eval. .sh 2 Evalhook and Funcallhook .pp There are hooks in the .Fr interpreter to permit a user written function to gain control of the evaluation process. These hooks are used by the Step package just described. There are two hooks and they have been strategically placed in the two key functions in the interpreter: .i eval (which all interpreted code goes through) and .i funcall (which all compiled code goes through if (sstatus translink nil) has been done). The hook in .i eval is compatible with Maclisp, but there is no Maclisp equivalent of the hook in .i funcall . .pp To arm the hooks two forms must be evaluated: (*rset t) and (sstatus evalhook t). Once that is done, .i eval and .i funcall do a special check when they enter. .pp If .i eval is given a form to evaluate, say (foo bar), and the symbol `evalhook' is non nil, say its value is `ehook', then .i eval will lambda bind the symbols `evalhook' and `funcallhook' to nil and will call ehook passing (foo bar) as the argument. It is ehook's responsibility to evaluate (foo bar) and return its value. Typically ehook will call the function `evalhook' to evaluate (foo bar). Note that `evalhook' is a symbol whose function binding is a system function described in Chapter 4, and whose value binding, if non nil, is the name of a user written function (or a lambda expression, or a binary object) which will gain control whenever eval is called. `evalhook' is also the name of the .i status tag which must be set for all of this to work. .pp If .i funcall is given a function, say foo, and a set of already evaluated arguments, say barv and bazv, and if the symbol `funcallhook' has a non nil value, say `fhook', then .i funcall will lambda bind `evalhook' and `funcallhook' to nil and will call fhook with arguments barv, bazv and foo. Thus fhook must be a lexpr since it may be given any number of arguments. The function to call, foo in this case, will be the .i last of the arguments given to fhook. It is fhooks responsibility to do the function call and return the value. Typically fhook will call the function .i funcallhook to do the funcall. This is an example of a funcallhook function which just prints the arguments on each entry to funcall and the return value. .Eb -> (defun fhook n (let ((form (cons (arg n) (listify (1- n)))) (retval)) (patom "calling ")(print form)(terpr) (setq retval (funcallhook form 'fhook)) (patom "returns ")(print retval)(terpr) retval)) fhook -> (*rset t) (sstatus evalhook t) (sstatus translink nil) -> (setq funcallhook 'fhook) calling (print fhook) ;; now all compiled code is traced fhookreturns nil calling (terpr) returns nil calling (patom "-> ") -> returns "-> " calling (read nil Q00000) (array foo t 10) ;; to test it, we see what happens when returns (array foo t 10) ;; we make an array calling (eval (array foo t 10)) calling (append (10) nil) returns (10) calling (lessp 1 1) returns nil calling (apply times (10)) returns 10 calling (small-segment value 10) calling (boole 4 137 127) returns 128 ... there is plenty more ... .Ee
All rights reserved.
%sccs.include.redist.roff%
@(#)ch14.n 6.3 (Berkeley) 04/17/91
." $Header: /na/franz/doc/RCS/ch14.n,v 1.1 83/01/31 07:08:43 jkf Exp $ .Lc The LISP Stepper 14 .sh 2 Simple Use Of Stepping \n(ch 1 .Lf step "s_arg1..." .No The LISP "stepping" package is intended to give the LISP programmer a facility analogous to the Instruction Step mode of running a machine language program. The user interface is through the function (fexpr) step, which sets switches to put the LISP interpreter in and out of "stepping" mode. The most common step invocations follow. These invocations are usually typed at the top-level, and will take effect immediately (i.e. the next S-expression typed in will be evaluated in stepping mode). .Eb (step t) ; Turn on stepping mode. (step nil) ; Turn off stepping mode. .Ee .Se In stepping mode, the LISP evaluator will print out each S-exp to be evaluated before evaluation, and the returned value after evaluation, calling itself recursively to display the stepped evaluation of each argument, if the S-exp is a function call. In stepping mode, the evaluator will wait after displaying each S-exp before evaluation for a command character from the console. .Eb STEP COMMAND SUMMARY <return> Continue stepping recursively. c Show returned value from this level only, and continue stepping upward. e Only step interpreted code. g Turn off stepping mode. (but continue evaluation without stepping). n <number> Step through <number> evaluations without stopping p Redisplay current form in full (i.e. rebind prinlevel and prinlength to nil) b Get breakpoint q Quit d Call debug .Ee .sh 2 Advanced Features .sh 3 Selectively Turning On Stepping. If (step foo1 foo2 ...) is typed at top level, stepping will not commence immediately, but rather when the evaluator first encounters an S-expression whose car is one of foo1, foo2, etc. This form will then display at the console, and the evaluator will be in stepping mode waiting for a command character. .pp Normally the stepper intercepts calls to funcall and eval. When funcall is intercepted, the arguments to the function have already been evaluated but when eval is intercepted, the arguments have not been evaluated. To differentiate the two cases, when printing the form in evaluation, the stepper preceded intercepted calls to .i funcall with "f:". Calls to funcall are normally caused by compiled lisp code calling other functions, whereas calls to eval usually occur when lisp code is interpreted. To step only calls to eval use: (step e) .sh 3 Stepping With Breakpoints. .pp For the moment, step is turned off inside of error breaks, but not by the break function. Upon exiting the error, step is reenabled. However, executing (step nil) inside a error loop will turn off stepping globally, i.e. within the error loop, and after return has be made from the loop. .sh 2 Overhead of Stepping. .pp If stepping mode has been turned off by (step nil), the execution overhead of having the stepping packing in your LISP is identically nil. If one stops stepping by typing "g", every call to eval incurs a small overhead--several machine instructions, corresponding to the compiled code for a simple cond and one function pushdown. Running with (step foo1 foo2 ...) can be more expensive, since a member of the car of the current form into the list (foo1 foo2 ...) is required at each call to eval. .sh 2 Evalhook and Funcallhook .pp There are hooks in the .Fr interpreter to permit a user written function to gain control of the evaluation process. These hooks are used by the Step package just described. There are two hooks and they have been strategically placed in the two key functions in the interpreter: .i eval (which all interpreted code goes through) and .i funcall (which all compiled code goes through if (sstatus translink nil) has been done). The hook in .i eval is compatible with Maclisp, but there is no Maclisp equivalent of the hook in .i funcall . .pp To arm the hooks two forms must be evaluated: (*rset t) and (sstatus evalhook t). Once that is done, .i eval and .i funcall do a special check when they enter. .pp If .i eval is given a form to evaluate, say (foo bar), and the symbol `evalhook' is non nil, say its value is `ehook', then .i eval will lambda bind the symbols `evalhook' and `funcallhook' to nil and will call ehook passing (foo bar) as the argument. It is ehook's responsibility to evaluate (foo bar) and return its value. Typically ehook will call the function `evalhook' to evaluate (foo bar). Note that `evalhook' is a symbol whose function binding is a system function described in Chapter 4, and whose value binding, if non nil, is the name of a user written function (or a lambda expression, or a binary object) which will gain control whenever eval is called. `evalhook' is also the name of the .i status tag which must be set for all of this to work. .pp If .i funcall is given a function, say foo, and a set of already evaluated arguments, say barv and bazv, and if the symbol `funcallhook' has a non nil value, say `fhook', then .i funcall will lambda bind `evalhook' and `funcallhook' to nil and will call fhook with arguments barv, bazv and foo. Thus fhook must be a lexpr since it may be given any number of arguments. The function to call, foo in this case, will be the .i last of the arguments given to fhook. It is fhooks responsibility to do the function call and return the value. Typically fhook will call the function .i funcallhook to do the funcall. This is an example of a funcallhook function which just prints the arguments on each entry to funcall and the return value. .Eb -> (defun fhook n (let ((form (cons (arg n) (listify (1- n)))) (retval)) (patom "calling ")(print form)(terpr) (setq retval (funcallhook form 'fhook)) (patom "returns ")(print retval)(terpr) retval)) fhook -> (*rset t) (sstatus evalhook t) (sstatus translink nil) -> (setq funcallhook 'fhook) calling (print fhook) ;; now all compiled code is traced fhookreturns nil calling (terpr) returns nil calling (patom "-> ") -> returns "-> " calling (read nil Q00000) (array foo t 10) ;; to test it, we see what happens when returns (array foo t 10) ;; we make an array calling (eval (array foo t 10)) calling (append (10) nil) returns (10) calling (lessp 1 1) returns nil calling (apply times (10)) returns 10 calling (small-segment value 10) calling (boole 4 137 127) returns 128 ... there is plenty more ... .Ee