HELP MISHAP John Williams, July 1987 Updated Feb 1995 This file describes how Poplog Common Lisp reports errors, and how (by default) it recovers from them. For details of the debugging facilities available during break points, see HELP * BREAK. The file HELP * DEBUG provides a general overview of Lisp debugging techniques. CONTENTS - (Use g to access required sections) 1 Classes of Error 2 Error Recovery 3 Message Format 4 When Errors May Occur 5 Read-Time Errors 6 Compile-Time Errors 7 Run-Time Errors 8 See Also ----------------------------------------------------------------------- 1 Classes of Error ----------------------------------------------------------------------- Poplog Common Lisp provides three levels of error handling: fatal errors (signaled by the function error), continuable errors (signaled by cerror), and warnings (signaled by warn). They issue similar error messages, but differ in what happens next, as described below. ----------------------------------------------------------------------- 2 Error Recovery ----------------------------------------------------------------------- The debugger will be entered after an error or warning in the following circumstances: warn If *break-on-warnings* is true. error If *break-on-errors* is true. cerror If *break-on-errors* is true. (The default values of *break-on-warnings* and *break-on-errors* are nil and t respectively). Otherwise, the following error recovery actions occur: warn Returns to its caller with nil. error & cerror Unwind to the nearest Lisp top-level loop, and resume the `read-eval-print' cycle. Note: If it can be proved that the stream *debug-io* is not connected to an interactive i/o device, the Debugger will not be entered. ----------------------------------------------------------------------- 3 Message Format ----------------------------------------------------------------------- Error messages consist of several lines of text, each beginning with an end-of-line comment marker (;;;) followed by one of the following keywords: MISHAP INVOLVING FILE LINE COMPILING DOING CALLING The keywords appear in the order shown. Some keywords may be omitted: see below for details. Note: Warning messages start with the keyword "Warning", and print the keywords in lower case (in order to make messages appear less abrasive). A sample error: (if (member "p" "octopus") (print 'yes) (print 'no)) ;;; MISHAP - List needed ;;; INVOLVING: "octopus" ;;; FILE : /poplog/lisp/help/mishap ;;; LINE: 82 ;;; DOING : (IF (MEMBER "p" "octopus") (PRINT 'YES) ...) ;;; CALLING : ENDP The MISHAP line describes the basic nature of the error, in this case the fact that member has been passed a non-list as its second argument. The INVOLVING line mentions Lisp objects that might have been responsible in some way for the error (in this case the string "octopus"). This line is omitted if there are no relevant objects. Arguments to the call of error, cerror, and warn not otherwise used by the formatting of the MISHAP part of the message will be displayed in the INVOLVING line. For example: (error "Object of type ~S needed" 'string 23) ;;; MISHAP - Object of type STRING needed ;;; INVOLVING: 23 The FILE line indicates which source file was being compiled when the error occurred. It is omitted if Lisp is currently reading from the terminal. The DOING part of the message is always a reminder of the top-level command given to Lisp. It is particularly valuable when compiling from a disc file. The CALLING line shows what functions were being executed at the time of the error. The most immediate caller is the one on the left. So, in the example above, it was the function endp that discovered that "octopus" wasn't a list. This line is omitted if a break is entered after the error (the normal situation); the debugger command :b should be issued to obtain similar information. (See HELP * BREAK for more details). Note: You can limit the number of callers displayed on the CALLING line by assigning to the Poplog-specific variable *lisp-calling-limit*. See REF * POPLOG_ONLY for details. ----------------------------------------------------------------------- 4 When Errors May Occur ----------------------------------------------------------------------- At any given time, the Lisp system is in one of three states: Reading a top-level form (read-time) Compiling that top-level form (compile-time) Executing the resulting code (run-time) The status of the Lisp system influences the format of error messages, as discussed below. ----------------------------------------------------------------------- 5 Read-Time Errors ----------------------------------------------------------------------- Read-time errors can be identified by the presence of the marker "read" in the CALLING part of the message. In the following example, the character 7 has been included in a binary number: (sqrt #b10101017) ;;; MISHAP - #\7 is not a radix 2 digit ;;; CALLING : "#b" "read" ----------------------------------------------------------------------- 6 Compile-Time Errors ----------------------------------------------------------------------- Compile-time errors are indicated by the presence of a COMPILING line in the message. Thus: (floor (abs 2 3) 4) ;;; MISHAP - ABS expects one argument ;;; COMPILING: (ABS 2 3) ;;; DOING : (FLOOR (ABS 2 3) 4) Note that the compiler can not tell if the arguments are appropriate to the function: which is, of course, why run-time errors may occur. However, many improper uses of special-forms can be detected during compilation: (defun foo (a) (setq a b c)) ;;; MISHAP - SETQ expects an even number of arguments ;;; COMPILING: (SETQ A B C) ;;; DOING : (DEFUN FOO (A) ...) The COMPILING line displays the expression that could not be compiled. All compile-time error messages include this line. Like run-time errors, the DOING line shows the expression being executed (unless it is the same as that printed on the COMPILING line). ----------------------------------------------------------------------- 7 Run-Time Errors ----------------------------------------------------------------------- Run-time errors result when Lisp tries to apply a function to inappropriate arguments, as in the first example discussed above, where the function member was applied to a string, not a list. ----------------------------------------------------------------------- 8 See Also ----------------------------------------------------------------------- HELP * BREAK Describes the Poplog Common Lisp Debugger. HELP * DEBUG Overview of Debugging tools in Poplog Lisp. REF * POPLOG_ONLY Lists Poplog-specific Lisp variables. --- C.all/lisp/help/mishap --- Copyright University of Sussex 1987. All rights reserved.