Debugging

When you have written a Lisp program you will have to debug it (unless all your programs work first time?). There are two main classes of errors; syntax errors and semantic errors.

Syntax errors occur when the text you've typed out to represent your program is not a valid representation of a Lisp object (since a program is simply an ordered set of Lisp objects). When you try to load your program the Lisp reader will find the syntax error and tell you about, unfortunately though it probably won't be able to tell you exactly where the error is.

The most common source of syntax errors is too few or too many parentheses; the Ctrl-Meta-f and Ctrl-Meta-b commands can be used to show the structure of the program as the Lisp reader sees it.

Semantic errors are what we normally call bugs -- errors in logic, the program is syntactically correct but doesn't do what you want it to. For these types of errors Jade provides a simple debugger which allows you to single step through the Lisp forms of your program as they are being evaluated.

There are several ways to enter the Lisp debugger; functions can be marked so that they cause the debugger to be entered when they are called, breakpoints can be written in functions or it can be called explicitly with a form to step through.

Command: trace symbol

This command marks the symbol symbol so that each time the function stored in the function cell of symbol is called the debugger is entered immediately.

When called interactively symbol is prompted for.

Command: untrace symbol

The opposite of trace -- unmarks the symbol.

Function: break

This function causes the debugger to be entered immediately. By putting the form (break) at suitable points in your program simple breakpoints can be created.

Command: step form

This function invokes the debugger to step through the form form.

When called interactively form is prompted for.

Whenever the Lisp debugger is entered the form waiting to be evaluated is printed at the bottom of the buffer, at this point the special debugger commands available are,

Ctrl-c Ctrl-s

Step into the current form; this means that in a list form the debugger is used to evaluated each argument in turn.

Ctrl-c Ctrl-i

Ignore the current form; makes the current form immediately return nil.

Ctrl-c Ctrl-n

Continue evaluating forms normally until the next form at the current level is entered, then re-enter the debugger.

Ctrl-c Ctrl-r

Continue execution normally. Note that this command is the one to use when an error has been trapped.

Ctrl-c Ctrl-b

Print a backtrace of the current Lisp call stack, note that calls of primitive functions aren't currently recorded in this stack.

Ctrl-c Ctrl-x

Prompt for a Lisp form, evaluate it and return this value as the result of the current form.

After the form has been evaluated (i.e. after you've typed one of the commands above) the value of the form is printed in the buffer, prefixed by the string `=> '.

Note that it is also possible to make certain types of errors invoke the debugger immediately they are signalled, see section Errors.

Go to the first, previous, next, last section, table of contents.