10.5 An example debugging session

To better understand how you can make use of the debugger, try working through the following example session. In this example, you define the factorial function, save the definition to a file on disk, compile that file and then call the function erroneously.

1. Choose File > New or click on.

   A new file is created and displayed in the Editor. If you have not already invoked the Editor, it is started for you automatically.

2. In the new file, define the function fac to calculate factorial numbers.

   (defun fac (n)
     (if (= n 1) 1
       (* n (fac (- n 1)))))
   

3. Choose File > Save or click on and enter a filename when prompted.
4. Choose File > Compile and Load to compile the file and load the resulting fasl file.

   The Editor switches to the output view while compilation takes place. When prompted, press Space to return to the text view. The fac function is now defined and available for you to use.

5. In the Listener, call fac erroneously with a string argument.

   (fac "turtle")
   

   LispWorks notices the error: The arguments of = should be numbers, and one of them is not.

6. Choose Debug > Start GUI Debugger or click to invoke the Debugger tool.

   Take a moment to examine the backtrace that is printed in the Backtrace area.

7. Starting from the selected frame, expand or select the next three frames in the Backtrace area in turn to examine the state of the variables which were passed to the functions in each call frame. Pay particular attention to the fac function.

   The error displayed in the Condition box informs you that the = function is called with two arguments: the integer 1 and the string "turtle". Clearly, one of the arguments was not the correct type for =, and this has caused entry into the debugger. However, the arguments were passed to = by fac, and so the real problem lies in the fac function.

   In this case, the solution is to ensure that fac generates an appropriate error if it is given an argument which is not an integer.

8. Double-click on the line FAC in the Backtrace area of the debugger tool.

   The Editor appears. The subform within the definition of fac which actually caused the error is highlighted. Double-clicking on a line in the Backtrace area is a shortcut for choosing Frame > Find Source or using the button. If the Debugger can find the erroneous subform, this is highlighted, otherwise the definition itself is highlighted if it can be found.

9. Edit the definition of the fac function so that an extra if statement is placed around the main clause of the function. The definition of fac now reads as follows:

   (defun fac (n) 
     (if (integerp n)
         (if (= n 1) 1
           (* n (fac (- n 1)))) 
       (print "Error: argument must be an integer")))
   

   The function now checks that the argument it has been passed is an integer, before proceeding to evaluate the factorial. If an integer has not been passed, an appropriate error message is generated.

10. Choose File > Save and File > Compile and Load again, to save, recompile and load the new definition.
11. Click on the Abort button in the debugger tool, to destroy the tool and return the Listener to the top level loop.
12. In the Listener, type another call to fac, once again specifying a string as an argument. Note that the correct error message is generated. You will see it twice, because fac prints the message and then the Listener prints the return value of fac.

This next part of the example shows you how you can use the various restarts which are listed as commands in the Restarts menu.

1. Call fac again with a new argument, but this time type the word length incorrectly.

   (fac (legnth "turtle"))
   

2. Choose Debug > Start GUI Debugger or click to invoke the debugger tool.

   You can spot immediately what has gone wrong here, so the simplest strategy is to return a value to use.

3. Choose Restarts > Return some values from the form (LEGNTH "turtle").

   You are prompted for a form to be evaluated.

4. Enter 6 in the dialog and click OK. This is the value that would have been returned from the correct call to (length "turtle").

Having returned the correct value from (length "turtle"), fac is called with the correct argument and returns the value 720.