Previous: Condition Types, Up: Error System

16.7 Condition-Type Taxonomy

The MIT/GNU Scheme error system provides a rich set of predefined condition types. These are organized into a forest through taxonomic links providing the relationships for “specializes” and “generalizes”. The chart appearing below shows these relationships by indenting all the specializations of a given type relative to the type. Note that the variables that are bound to these condition types are prefixed by `condition-type:'; for example, the type appearing in the following table as `simple-error' is stored in the variable condition-type:simple-error. Users are encouraged to add new condition types by creating specializations of existing ones.

Following the chart are detailed descriptions of the predefined condition types. Some of these types are marked as abstract types. Abstract types are not intended to be used directly as the type of a condition; they are to be used as generalizations of other types, and for binding condition handlers. Types that are not marked as abstract are concrete; they are intended to be explicitly used as a condition's type. 

     serious-condition
         error
             simple-error
             illegal-datum
                 wrong-type-datum
                     wrong-type-argument
                     wrong-number-of-arguments
                 datum-out-of-range
                     bad-range-argument
                 inapplicable-object
             file-error
                 file-operation-error
                 derived-file-error
             port-error
                 derived-port-error
             variable-error
                 unbound-variable
                 unassigned-variable
             arithmetic-error
                 divide-by-zero
                 floating-point-overflow
                 floating-point-underflow
             control-error
                 no-such-restart
             not-loading
             primitive-procedure-error
                 system-call-error
     warning
         simple-warning
     simple-condition
     breakpoint
— condition type: condition-type:serious-condition

This is an abstract type. All serious conditions that require some form of intervention should inherit from this type. In particular, all errors inherit from this type.

— condition type: condition-type:error

This is an abstract type. All errors should inherit from this type.

— condition type: condition-type:simple-error message irritants

This is the condition generated by the error procedure when its first argument is not a condition or condition type. The fields message and irritants are taken directly from the arguments to error; message contains an object (usually a string) and irritants contains a list of objects. The reporter for this type uses format-error-message to generate its output from message and irritants.

— condition type: condition-type:illegal-datum datum

This is an abstract type. This type indicates the class of errors in which a program discovers an object that lacks specific required properties. Most commonly, the object is of the wrong type or is outside a specific range. The datum field contains the offending object.

— condition type: condition-type:wrong-type-datum datum type

This type indicates the class of errors in which a program discovers an object that is of the wrong type. The type field contains a string describing the type that was expected, and the datum field contains the object that is of the wrong type. 

     (error:wrong-type-datum 3.4 "integer")  error-->
     ;The object 3.4 is not an integer.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:wrong-type-datum datum type

This procedure signals a condition of type condition-type:wrong-type-datum. The datum and type fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:wrong-type-argument datum type operator operand

This type indicates that a procedure was passed an argument of the wrong type. The operator field contains the procedure (or a symbol naming the procedure), the operand field indicates the argument position that was involved (this field contains either a symbol, a non-negative integer, or #f), the type field contains a string describing the type that was expected, and the datum field contains the offending argument. 

     (+ 'a 3)                                error-->
     ;The object a, passed as the first argument to integer-add,
     ; is not the correct type.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify an argument to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.
     
     (list-copy 3)
     ;The object 3, passed as an argument to list-copy, is not a list.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:wrong-type-argument datum type operator

This procedure signals a condition of type condition-type:wrong-type-argument. The datum, type and operator fields of the condition are filled in from the corresponding arguments to the procedure; the operand field of the condition is set to #f.

— condition type: condition-type:wrong-number-of-arguments datum type operands

This type indicates that a procedure was called with the wrong number of arguments. The datum field contains the procedure being called, the type field contains the number of arguments that the procedure accepts, and the operands field contains a list of the arguments that were passed to the procedure. 

     (car 3 4)                               error-->
     ;The procedure car has been called with 2 arguments;
     ; it requires exactly 1 argument.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:wrong-number-of-arguments datum type operands

This procedure signals a condition of type condition-type:wrong-number-of-arguments. The datum, type and operands fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:datum-out-of-range datum

This type indicates the class of errors in which a program discovers an object that is of the correct type but is otherwise out of range. Most often, this type indicates that an index to some data structure is outside of the range of indices for that structure. The datum field contains the offending object. 

     (error:datum-out-of-range 3)            error-->
     ;The object 3 is not in the correct range.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:datum-out-of-range datum

This procedure signals a condition of type condition-type:datum-out-of-range. The datum field of the condition is filled in from the corresponding argument to the procedure.

— condition type: condition-type:bad-range-argument datum operator operand

This type indicates that a procedure was passed an argument that is of the correct type but is otherwise out of range. Most often, this type indicates that an index to some data structure is outside of the range of indices for that structure. The operator field contains the procedure (or a symbol naming the procedure), the operand field indicates the argument position that was involved (this field contains either a symbol, a non-negative integer, or #f), and the datum field is the offending argument. 

     (string-ref "abc" 3)                    error-->
     ;The object 3, passed as the second argument to string-ref,
     ; is not in the correct range.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify an argument to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:bad-range-argument datum operator

This procedure signals a condition of type condition-type:bad-range-argument. The datum and operator fields of the condition are filled in from the corresponding arguments to the procedure; the operand field of the condition is set to #f.

— condition type: condition-type:inapplicable-object datum operands

This type indicates an error in which a program attempted to apply an object that is not a procedure. The object being applied is saved in the datum field, and the arguments being passed to the object are saved as a list in the operands field. 

     (3 4)                                   error-->
     ;The object 3 is not applicable.
     ;To continue, call RESTART with an option number:
     ; (RESTART 2) => Specify a procedure to use in its place.
     ; (RESTART 1) => Return to read-eval-print level 1.
— condition type: condition-type:file-error filename

This is an abstract type. It indicates that an error associated with a file has occurred. For example, attempting to delete a nonexistent file will signal an error. The filename field contains a filename or pathname associated with the operation that failed.

— condition type: condition-type:file-operation-error filename verb noun reason operator operands

This is the most common condition type for file system errors. The filename field contains the filename or pathname that was being operated on. The verb field contains a string which is the verb or verb phrase describing the operation being performed, and the noun field contains a string which is a noun or noun phrase describing the object being operated on. The reason field contains a string describing the error that occurred. The operator field contains the procedure performing the operation (or a symbol naming that procedure), and the operands field contains a list of the arguments that were passed to that procedure. For example, an attempt to delete a nonexistent file would have the following field values: 

          filename        "/zu/cph/tmp/no-such-file"
          verb            "delete"
          noun            "file"
          reason          "no such file or directory"
          operator        file-remove
          operands        ("/zu/cph/tmp/no-such-file")

and would generate a message like this: 

          (delete-file "/zu/cph/tmp/no-such-file") error-->
          ;Unable to delete file "/zu/cph/tmp/no-such-file" because:
          ; No such file or directory.
          ;To continue, call RESTART with an option number:
          ; (RESTART 3) => Try to delete the same file again.
          ; (RESTART 2) => Try to delete a different file.
          ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:file-operation-error filename verb noun reason operator operands

This procedure signals a condition of type condition-type:file-operation-error. The fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:derived-file-error filename condition

This is another kind of file error, which is generated by obscure file-system errors that do not fit into the standard categories. The filename field contains the filename or pathname that was being operated on, and the condition field contains a condition describing the error in more detail. Usually the condition field contains a condition of type condition-type:system-call-error.

— procedure: error:derived-file filename condition

This procedure signals a condition of type condition-type:derived-file-error. The filename and condition fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:port-error port

This is an abstract type. It indicates that an error associated with a I/O port has occurred. For example, writing output to a file port can signal an error if the disk containing the file is full; that error would be signalled as a port error. The port field contains the associated port.

— condition type: condition-type:derived-port-error port condition

This is a concrete type that is signalled when port errors occur. The port field contains the port associated with the error, and the condition field contains a condition object that describes the error in more detail. Usually the condition field contains a condition of type condition-type:system-call-error.

— procedure: error:derived-port port condition

This procedure signals a condition of type condition-type:derived-port-error. The port and condition fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:variable-error location environment

This is an abstract type. It indicates that an error associated with a variable has occurred. The location field contains the name of the variable, and the environment field contains the environment in which the variable was referenced.

— condition type: condition-type:unbound-variable location environment

This type is generated when a program attempts to access or modify a variable that is not bound. The location field contains the name of the variable, and the environment field contains the environment in which the reference occurred. 

     foo                                     error-->
     ;Unbound variable: foo
     ;To continue, call RESTART with an option number:
     ; (RESTART 3) => Specify a value to use instead of foo.
     ; (RESTART 2) => Define foo to a given value.
     ; (RESTART 1) => Return to read-eval-print level 1.
— condition type: condition-type:unassigned-variable location environment

This type is generated when a program attempts to access a variable that is not assigned. The location field contains the name of the variable, and the environment field contains the environment in which the reference occurred. 

     foo                                     error-->
     ;Unassigned variable: foo
     ;To continue, call RESTART with an option number:
     ; (RESTART 3) => Specify a value to use instead of foo.
     ; (RESTART 2) => Set foo to a given value.
     ; (RESTART 1) => Return to read-eval-print level 1.
— condition type: condition-type:arithmetic-error operator operands

This is an abstract type. It indicates that a numerical operation was unable to complete because of an arithmetic error. (For example, division by zero.) The operator field contains the procedure that implements the operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure.

— condition type: condition-type:divide-by-zero operator operands

This type is generated when a program attempts to divide by zero. The operator field contains the procedure that implements the failing operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure. 

     (/ 1 0)
     ;Division by zero signalled by /.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:divide-by-zero operator operands

This procedure signals a condition of type condition-type:divide-by-zero. The operator and operands fields of the condition are filled in from the corresponding arguments to the procedure.

— condition type: condition-type:floating-point-overflow operator operands

This type is generated when a program performs an arithmetic operation that results in a floating-point overflow. The operator field contains the procedure that implements the operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure.

— condition type: condition-type:floating-point-underflow operator operands

This type is generated when a program performs an arithmetic operation that results in a floating-point underflow. The operator field contains the procedure that implements the operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure.

— condition type: condition-type:primitive-procedure-error operator operands

This is an abstract type. It indicates that an error was generated by a primitive procedure call. Primitive procedures are distinguished from ordinary procedures in that they are not written in Scheme but instead in the underlying language of the Scheme implementation. The operator field contains the procedure that implements the operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure.

— condition type: condition-type:system-call-error operator operands system-call error-type

This is the most common condition type generated by primitive procedures. A condition of this type indicates that the primitive made a system call to the operating system, and that the system call signalled an error. The system-call error is reflected back to Scheme as a condition of this type, except that many common system-call errors are automatically translated by the Scheme implementation into more useful forms; for example, a system-call error that occurs while trying to delete a file will be translated into a condition of type condition-type:file-operation-error. The operator field contains the procedure that implements the operation (or a symbol naming the procedure), and the operands field contains a list of the arguments that were passed to the procedure. The system-call and error-type fields contain symbols that describe the specific system call that was being made and the error that occurred, respectively; these symbols are completely operating-system dependent.

— condition type: condition-type:control-error

This is an abstract type. It describes a class of errors relating to program control flow.

— condition type: condition-type:no-such-restart name

This type indicates that a named restart was not active when it was expected to be. Conditions of this type are signalled by several procedures that look for particular named restarts, for example muffle-warning. The name field contains the name that was being searched for. 

     (muffle-warning)                        error-->
     ;The restart named muffle-warning is not bound.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— procedure: error:no-such-restart name

This procedure signals a condition of type condition-type:no-such-restart. The name field of the condition is filled in from the corresponding argument to the procedure.

— condition type: condition-type:not-loading

A condition of this type is generated when the procedure current-load-pathname is called from somewhere other than inside a file being loaded. 

     (current-load-pathname)                 error-->
     ;No file being loaded.
     ;To continue, call RESTART with an option number:
     ; (RESTART 1) => Return to read-eval-print level 1.
— condition type: condition-type:warning

This is an abstract type. All warnings should inherit from this type. Warnings are a class of conditions that are usually handled by informing the user of the condition and proceeding the computation normally.

— condition type: condition-type:simple-warning message irritants

This is the condition generated by the warn procedure. The fields message and irritants are taken directly from the arguments to warn; message contains an object (usually a string) and irritants contains a list of objects. The reporter for this type uses format-error-message to generate its output from message and irritants.

— condition type: condition-type:simple-condition message irritants

This is an unspecialized condition that does not fall into any of the standard condition classes. The message field contains an object (usually a string) and irritants contains a list of objects. The reporter for this type uses format-error-message to generate its output from message and irritants.

— condition type: condition-type:breakpoint environment message prompt

A condition of this type is generated by the breakpoint mechanism. The contents of its fields are beyond the scope of this document.