-*- Mode: LISP -*-		Error Proposal #5 by KMP 3/15/86, Page 1

Error System Proposal #5 by Kent M. Pitman (KMP@Symbolics), 15-Mar-86.

This draft incorporates numerous suggestions made by David A. Moon 
(Moon@Symbolics) and Richard Mlynarik (MLY@MIT-MC). Not all of their
suggestions made it into this proposal however, either because of
some technical disagreement or limitations of time, so it shouldn't
be seen as contradictory if they criticize aspects of the proposal.


				 TERMINOLOGY
				 -----------

A ``condition'' is a kind of object which is created when an exceptional
situation arises in order to represent the relevant features of that
situation.

Once a condition is created, it is common to ``signal'' it. When a condition
is signalled, a set of handlers are tried in some pre-defined order until one
decides to ``handle'' the condition or until no more handlers are found. A
condition is said to have been ``handled'' if a handler performs a non-local 
transfer of control to exit the signalling process.

Although such transfers of control may be done directly using traditional Lisp
mechanisms such as CATCH and THROW, BLOCK and RETURN, or TAGBODY and GO, the
condition system also provides a way to ``proceed'' from a condition which is
more structured. Among other things, the use of these structured primitives
for proceeding allow better a more integrated relationship between the user
program and the interactive debugger.

It is not necessary that all conditions be handled. Some conditions are 
trivial enough that a failure to handle them may be disregarded. Others,
which we will call ``serious conditions'' must be handled in order to assure
correct program behavior. If a serious condition is signalled but no handler
is found, the debugger will be entered so that the user may interactively 
specify how to proceed.

Serious conditions which result from incorrect programs or data are
called ``errors.'' Not all serious conditions are errors, however. Storage 
conditions are examples of serious conditions that are not errors. 
For example, the control stack may legitimately overflow without a program
being in error. Even though a stack overflow is not necessarily a program
error, it is serious enough to warrant entry to the debugger if the 
condition goes unhandled.

Some types of conditions are predefined by the system. All types of conditions
are subtypes of CONDITION. That is, (TYPEP C 'CONDITION) is true iff C is a
condition. 

Systems with non-hierarchical type systems are allowed to use such
non-hierarchical types in a CL-visible way as long as (TYPEP c 'CONDITION) is
true for such conditions.  No mechanism is currently provided at this time for
creating condition types that directly exploit non-hierarchical inheritance.

The only CL-provided mechanism for defining new condition types is DEFINE-CONDITION.
The only CL-provided mechanism for instantiating a condition is MAKE-CONDITION.


				Error Proposal #5 by KMP 3/15/86, Page 2

When a condition object is created, the most common operation to be performed
upon it is to ``signal'' it (although there may be applications in which this
does not happen, or does not happen immediately).

When a condition is signalled, the system tries locate the most appropriate 
handler for the condition and invoke that handler. Handlers are located according
to the following rules:

  * Check for locally defined (ie, bound) handlers.
  * If no appropriate bound handler is found, check for the default handler
    first of the signalled type and then of each of its superiors.

If an appropriate handler is found, it is called. In some circumstances
(to be described later), the handler may ``decline'' by simply returning
without performing a non-local transfer of control. In such cases, the 
search for an appropriate handler is picked up where it left off, as if
the called handler had never been present.

If no bound handler or default handler is found, or if all handlers which were
found decline, SIGNAL returns the condition which was signalled.

When a condition is signalled, handlers are searched for in the dynamic 
environment of the signaller. Handlers can be established within a dynamic 
context by use of CONDITION-BIND. 

A ``handler'' is a function of one argument, the condition to be handled. The 
handler may inspect the object (using primitives described in another section)
to be sure it is `interested' in handling the condition.  After inspecting the
condition, the handler must take one of the following actions:

  * It may decline to handle the condition, by simply returning. When this 
    happened, the returned values are ignored and the effect is the same as
    if the handler had been invisible to the mechanism seeking to find a 
    handler. The next handler in line will be tried, or if no such handler, 
    the default action for the given condition will be taken. A default handler
    may also decline, in which case the condition will go unhandled.

  * It may perform some non-local transfer of control using GO, RETURN, THROW,
    ABORT, or INVOKE-PROCEED-CASE.

  * It may signal another condition.

  * It may invoke the interactive debugger.

In some cases, it may be useful to ``report'' a condition or a proceed case 
to a user or a log file of some sort. When the printer is invoked on a condition
or proceed case while *PRINT-ESCAPE* is NIL, the report-function for that object
is invoked. In particular, this means that an expression like 
 (FORMAT T "~A" CONDITION)
will invoke CONDITION's report function. Because of this, no special function 
is provided for invoking the report function of a condition or a proceed case.

				Error Proposal #5 by KMP 3/15/86, Page 3


		  PROGRAM INTERFACE TO THE CONDITION SYSTEM
		  -----------------------------------------

ERROR datum &rest arguments				[Function]

  Invokes the signal facility on a condition. If the condition is not handled,
  (DEBUG condition) is done.

  If DATUM is a condition, then that condition is used directly. 
  In this case, it is an error for ARGUMENTS to be non-NIL.

  If DATUM a condition type, then the condition used is the result
  of doing (APPLY #'MAKE-CONDITION datum arguments).

  If DATUM is a string, then the condition used is the result of 
  doing (MAKE-CONDITION 'SIMPLE-ERROR 
	  :FORMAT-STRING    datum
	  :FORMAT-ARGUMENTS arguments).

CERROR proceed-format-string datum &rest arguments	[Function]

  Invokes the error facility on a condition. If the condition is not handled,
  (DEBUG condition). While signalling is going on, and while in the 
  debugger if it is reached, it is possible to proceed this error using the
  proceed function PROCEED.

  If DATUM is a condition, then that condition is used directly. 
  In this case, ARGUMENTS will be used only with the PROCEED-FORMAT-STRING
  and will not be used to initialized DATUM.

  If DATUM a condition type, then the condition used is the result
  of doing (APPLY #'MAKE-CONDITION datum arguments).

  If DATUM is a string, then the condition used is the result of 
  doing (MAKE-CONDITION 'SIMPLE-ERROR 
	  :FORMAT-STRING datum
	  :FORMAT-ARGUMENTS arguments).

  The PROCEED-FORMAT-STRING must be a string. Note that if DATUM is not a 
  string, then the format arguments used by the PROCEED-FORMAT-STRING will
  still be the ARGUMENTS (in the keyword format as specified). In this case,
  some care may be necessary to set up the PROCEED-FORMAT-STRING correctly. 
  The format op ~* may be particularly useful in this situation.

  The value returned by CERROR is the condition which was signalled.

				Error Proposal #5 by KMP 3/15/86, Page 4

BREAK datum &rest arguments				[Function]

  Directly enters the debugger with a condition without trying to invoke
  the signal facility. Executing the function PROCEED while in the debugger
  will cause a return from the BREAK. 

  If DATUM is a condition, then that condition is used directly. 
  In this case, it is an error for ARGUMENTS to be non-NIL.

  If DATUM is a condition type, then the condition used is the result
  of doing (APPLY #'MAKE-CONDITION datum arguments).

  If DATUM is a string, then the condition used is the result of 
  doing (MAKE-CONDITION 'SIMPLE-BREAK
	  :FORMAT-STRING datum
	  :FORMAT-ARGUMENTS arguments).

  If the break is proceeded, the value returned is the condition that was used.

  Implementation Note: BREAK could be defined by:

	(DEFUN BREAK (DATUM &REST ARGUMENTS)
	  (PROCEED-CASE (DEBUG
			  (COND ((TYPEP DATUM 'CONDITION) DATUM)
				((SYMBOLP DATUM) ;roughly, (SUBTYPEP DATUM 'CONDITION)
				 (APPLY #'MAKE-CONDITION DATUM ARGUMENTS))
				((STRINGP DATUM)
				 (MAKE-CONDITION 'SIMPLE-BREAK
				   :FORMAT-STRING DATUM
				   :FORMAT-ARGUMENTS ARGUMENTS))
				(T
				 (ERROR "Bad argument to BREAK: ~S" DATUM))))
	    (PROCEED (CONDITION) 
		:TEST (LAMBDA (IGNORE) T)
	        :REPORT "Return from BREAK."
	      CONDITION)))

  See Footnote: {TRUE}

				Error Proposal #5 by KMP 3/15/86, Page 5


WARN datum &rest arguments				[Function]

  Invokes the signal facility on a condition. If the condition is not handled,
  then the text of the warning is output to error output (with possible
  implementation-specific extras such as moving to a fresh line before and
  after the display of the warning, or supplying some introductory that might 
  mention the name of the function which called WARN).  If *BREAK-ON-WARNINGS* 
  is true, then in addition to printing the warning, the debugger is entered.
  In this case, WARN returns only if PROCEED is done from the debugger. The
  value returned by WARN is the condition which was signalled.

  If DATUM is a condition, then that condition is used directly. 
  In this case, it is an error for ARGUMENTS to be non-NIL.

  If DATUM is a condition type, then the condition used is the result
  of doing (APPLY #'MAKE-CONDITION datum arguments).

  If DATUM is a string, then the condition used is the result of 
  doing (MAKE-CONDITION 'SIMPLE-WARNING
	  :FORMAT-STRING datum
	  :FORMAT-ARGUMENTS arguments).


*BREAK-ON-WARNINGS*					[Variable]

  {As described in CLtL}

				Error Proposal #5 by KMP 3/15/86, Page 6

DEFINE-CONDITION name parent-type [keyword value]* &rest slots
							[Special Form]

  Defines a new condition type with the given NAME, which is a 
  subtype of the given PARENT-TYPE. Except as otherwise noted,
  the arguments are not evaluated.

  The valid KEYWORD/VALUE pairs are:

   :CONC-NAME symbol-or-string

     As in DEFSTRUCT, this sets up automatic prefixing of the names 
     of slot accessors. Also as in DESTRUCT, the default behavior is to use
     the name of the new type, NAME, followed by a hyphen.

   :REPORT-FUNCTION expression

     EXPRESSION should be a suitable argument to the FUNCTION special form.
     It designates a function of two arguments, a condition and a stream, 
     which prints the condition to the stream when *PRINT-ESCAPE* is NIL.

   :REPORT form

     A short form of :REPORT-FUNCTION to cover two common cases.
     If form is a constant string, this is the same as
	:REPORT-FUNCTION (LAMBDA (IGNORE STREAM) (WRITE-STRING form STREAM))
     Otherwise, this is the same as
	:REPORT-FUNCTION (LAMBDA (CONDITION *STANDARD-OUTPUT*) form)
     In this latter case, the form describes how to print objects of the type
     being defined. The form should do output to standard output. The condition
     being printed will be the value of the variable CONDITION.

   :HANDLE form

     An expression to be used as the body of a default handler for this
     condition type. While executing form, the variable CONDITION will
     be bound to the condition being handled.

  It is an error to specify both :REPORT-FUNCTION and :REPORT in the
  same DEFINE-CONDITION. If neither :REPORT-FUNCTION nor :REPORT is specified,
  information about how to print this type of condition will be inherited 
  from the PARENT-TYPE.

  SLOTS is a list of slot spec, and specifies slots to be used by the
  given type. In addition to those specified, the slots of the PARENT-TYPE 
  are also available.
 
  A slot spec is either the name of a slot, or a list, the car of
  which is the slot name and the cadr is a form which will can evaluated
  by MAKE-CONDITION to produce a default value when an explicit value 
  is not provided. If no slot default is specified, NIL is assumed.
 
  If a slot name is specified which is the same as the name in some
  type of which this type is a subtype, only one shared slot is created
  in the condition object, but the specified default overrides any 
  default which might otherwise have been inherited from a parent type.
 
				Error Proposal #5 by KMP 3/15/86, Page 7

  MAKE-CONDITION will accept keywords with the printname of any of 
  the designated slots, and will initialize the corresponding slots in
  conditions it creates.
 
  Accessors are created according to the same rules as used by DEFSTRUCT.
  For example:
	    (DEFINE-CONDITION BAD-FOOD-COLOR FOOD-LOSSAGE
		:REPORT (FORMAT T "The food ~A was ~A."
				(BAD-FOOD-COLOR-FOOD  CONDITION)
				(BAD-FOOD-COLOR-COLOR CONDITION))
	      FOOD 
	      COLOR)
  defines an error of type BAD-FOOD-COLOR which inherits from the 
  FOOD-LOSSAGE condition type. The new type has slots FOOD and COLOR
  so that MAKE-CONDITION will accept :FOOD and :COLOR keywords and 
  accessors BAD-FOOD-COLOR-FOOD and BAD-FOOD-COLOR-COLOR will apply
  to objects of this type.

No functions are provided for directly accessing the printer or the default
handler for a condition since it is not believed that this will be very 
useful in portable code (at least until an object system is better defined).

The printer for a condition will be implicitly called any time a condition
is printed with *PRINT-ESCAPE* being NIL. Hence, (PRINC condition) or
(FORMAT T "~A" condition) are possible ways of invoking the condition's 
printer.

The default handler will be implicitly called during the signalling process
and never has any reason to be manually invoked.

Here are some examples of creating conditions. These forms define a condition
called MACHINE-ERROR which inherits from ERROR: 
 
   (DEFINE-CONDITION MACHINE-ERROR ERROR
       :REPORT (FORMAT T "There is a problem with ~A."
		       (MACHINE-ERROR-MACHINE-NAME CONDITION))
     MACHINE-NAME)
 
This defines a new error condition (a subtype of MACHINE-ERROR) for use when
machines are not available: 
 
   (DEFINE-CONDITION MACHINE-NOT-AVAILABLE-ERROR MACHINE-ERROR
       :REPORT (FORMAT T "The machine ~A is not available."
		       (MACHINE-ERROR-MACHINE-NAME CONDITION)))
 
This defines a still more specific condition, built upon
MACHINE-NOT-AVAILABLE-ERROR, which provides a default for MACHINE-NAME but
which does not provide any new slots: 
 
   (DEFINE-CONDITION MY-FAVORITE-MACHINE-NOT-AVAILABLE-ERROR
		     MACHINE-NOT-AVAILABLE-ERROR
     (MACHINE-NAME "MIT-MC.ARPA"))

This gives the MACHINE-NAME slot a default initialization. Since no :REPORT
clause was given, the information supplied in the definition of
MACHINE-NOT-AVAILABLE-ERROR will be used if a condition of this type is
printed while *PRINT-ESCAPE* is NIL.

				Error Proposal #5 by KMP 3/15/86, Page 8

MAKE-CONDITION type &rest slot-initializations		[Function]

   Calls the appropriate constructor function for the given type, passing
   along the given slot initializations to the constructor, and returning
   an instantiated condition.

   The SLOT-INITIALIZATIONS are given in alternating keyword/value pairs.
   eg, (MAKE-CONDITION 'BAD-FOOD-COLOR :FOOD MY-FOOD :COLOR MY-COLOR)

   Design Note: If either DEFSTRUCT or some other type system adopted
   later by CL ever provides a MAKE-INSTANCE primitive, MAKE-CONDITION 
   would no longer be necessary.

SIGNAL datum &rest arguments				[Function]

  Invokes the signal facility on a condition. If the condition is not handled,
  SIGNAL returns the condition object it was attempting to handle.

  If DATUM is a condition, then that condition is used directly. 
  In this case, it is an error for ARGUMENTS to be non-NIL.

  If DATUM is a condition type, then the condition used is the result
  of doing (APPLY #'MAKE-CONDITION datum arguments).

  If DATUM is a string, then the condition used is the result of 
  doing (MAKE-CONDITION 'SIMPLE-CONDITION 
	  :FORMAT-STRING datum
	  :FORMAT-ARGUMENTS arguments).

CONDITION-BIND bindings &rest forms			[Special Form]

  Executes body in a dynamic context where the giving local handler bindings 
  are in effect. The BINDINGS must take the form (type handler).

  TYPE may be a type or a list of types.

  HANDLER should evaluate to a function to be used to handle conditions of the
  given type(s) during execution of the FORMS.

DEBUG condition			 			[Function]

  Enters the debugger with a given condition. 

  This function  will never directly return. Return can occur only by a
  special transfer of control, such as to a PROCEED-CASE or CATCH-ABORT.


				Error Proposal #5 by KMP 3/15/86, Page 9

COMPUTE-PROCEED-CASES condition				[Function]

  Uses the dynamic state of the program to compute a list of ``proceed 
  cases'' which may be used with the given CONDITION. 

  Each ``proceed case'' represents a point in the current dynamic state of
  the program to which control may be transferred. Implementations are free
  to implement these objects in whatever manner is most convenient; the 
  objects need have only dynamic extent. The only operations which 
  Common Lisp defines for such objects are PROCEED-CASE-NAME, 
  FIND-PROCEED-CASE, INVOKE-PROCEED-CASE, PRINC and PRINT, the 
  identification of an object as a proceed case using 
  (TYPEP x 'PROCEED-CASE), and standard lisp operations which work for 
  all objects such as EQ, EQL, DESCRIBE, etc.

  The list which results from a call to COMPUTE-PROCEED-CASES is ordered 
  so that the innermost (ie, more-recently established) proceed cases 
  are nearer the head of the list.

  Note, too, that COMPUTE-PROCEED-CASES returns all valid proceed cases for
  CONDITION, even if some of them have the same name as others and therefore
  would not be found by FIND-PROCEED-CASE.

  Implementations are permitted, but not required, to return different 
  (ie, non-EQ) lists from repeated calls to COMPUTE-PROCEED-CASES while 
  in the same lexical/dynamic environment. It is an error to modify the
  list which is returned by COMPUTE-PROCEED-CASES.

				Error Proposal #5 by KMP 3/15/86, Page 10

When a condition is signalled, a facility is available for use by handlers to
non-locally transfer control to an outer dynamic contour of the program. The
form which creates contours which may be returned to is called PROCEED-CASE.
The function which transfers control to a PROCEED-CASE clause is called
INVOKE-PROCEED-CASE.

PROCEED-CASE form &rest clauses			[Special Form]

  The form is evaluated in a dynamic context where the clauses have 
  special meanings as points to which control may be transferred in the 
  event that a condition is signalled. If form runs to completion and 
  returns any values, all values returned by the form are simply returned
  by the PROCEED-CASE form. If a condition is signalled while form is 
  running, a handler may tranfer control to one of the clauses. If a
  transfer occurs, the forms in the body of that clause will be evaluated 
  and any values returned by the last such form will be returned by the 
  PROCEED-CASE form.

  A PROCEED-CASE clause has the form:

	(proceed-function-name arglist [keyword value]* [body-form]*)

  The PROCEED-FUNCTION-NAME may be NIL or the name of a defined proceed 
  function.

  The ARGLIST is a list of variables to be bound during the execution of 
  the body-forms. The first variable will be the condition, and the remaining
  will be additional data provided by the proceed function. By special 
  exemption, the arglist may be () if you don't care about any of the 
  arguments; otherwise, the argument list must be compatible with the 
  arguments as passed by INVOKE-PROCEED-CASE. If a PROCEED-FUNCTION-NAME was
  supplied, then the arguments in the arglist need not be optional, since 
  the proceed-function will have taken care of filling in all optional
  arguments and a fixed number of arguments will always be passed to 
  INVOKE-PROCEED-CASE.

  The valid KEYWORD/VALUE pairs are:

   :TEST function

     A function of one argument, the condition, which must return true for
     this case to be "visible" to handlers. The function should be in a form
     which is acceptable as an argument to the FUNCTION special form.

   :CONDITION type

      Shorthand for the common special case of :TEST in which the user is
      doing a test of the given TYPE of condition being signalled to 
      determine its visibility. The following two pairs are equivalent:
	:CONDITION foo
	:TEST (LAMBDA (C) (TYPEP C 'foo))
				
				Error Proposal #5 by KMP 3/15/86, Page 11

   :REPORT-FUNCTION exp

     The EXP must be an appropriate argument to the FUNCTION special form,
     and should designate a function of two arguments, a proceed case and
     a stream, which summarizes the action that this proceed case will take.

   :REPORT form

     This is a shorthand for two important special cases of :REPORT-FUNCTION.
     If FORM is a constant string, then this is the same as:
	:REPORT-FUNCTION (LAMBDA (IGNORE STREAM)
			   (WRITE-STRING form STREAM))
     Otherwise, this is the same as
	:REPORT-FUNCTION (LAMBDA (CONDITION *STANDARD-OUTPUT*)
			   form)
     In the latter case, form must do output to standard output, summarizing
     the action that this proceed case will take.

  Only one of :TEST or :CONDITION may be specified. 
  Only one of :REPORT or :REPORT-FUNCTION may be specified.

  If a named proceed function has a default for any of :TEST or :CONDITION 
  and the proceed case specifies any of :TEST or :CONDITION,
  then the information supplied in the proceed case is the only information 
  considered. Similarly, if :REPORT or :REPORT-FUNCTION is specified in 
  the proceed case, then only that information is considered, and any :REPORT 
  or :REPORT-FUNCTION specified as a default for the named proceed function 
  is not used.

  If a named proceed function is used but no report information is supplied, 
  the name of the proceed function is used to generate the default help 
  information. It is an error if no named proceed case is used and no report
  information is provided; implementations are encouraged to flag this error 
  at the earliest convenient time (eg, compilation time).

  When *PRINT-ESCAPE* is NIL, the printer will use report information for
  a proceed case. eg, a debugger might announce the action of typing
  Control-Z by doing:
      (FORMAT T "~&Control-Z: ~A~%" SOME-PROCEED-CASE)
  which would then display as something like:
      Control-Z: Return to command level.

				Error Proposal #5 by KMP 3/15/86, Page 12

  Examples:

	(PROCEED-CASE (A-RANDOM-COMPUTATION)
	  (NEW-FUNCTION (IGNORE NEW-FUNCTION)
	    (SETQ FUNCTION NEW-FUNCTION)))

        (PROCEED-CASE (A-RANDOM-COMPUTATION)
	  (NIL (IGNORE &OPTIONAL
			 (NEW-FUNCTION (READ-TYPED-OBJECT 'FUNCTION "Function: ")))
	       :REPORT "Use a different function."
	       :CONDITION UNDEFINED-FUNCTION
	    (SETQ FUNCTION NEW-FUNCTION)))

        (PROCEED-CASE (A-COMMAND-LOOP)
	  (RETURN-FROM-COMMAND-LEVEL ()
              :REPORT (FORMAT T "Return from command level ~D." LEVEL)
	    NIL))

	(LOOP 
          (PROCEED-CASE (ANOTHER-RANDOM-COMPUTATION)
	    (PROCEED ())))

  Assuming that NEW-FUNCTION is defined as a proceed function with defaults:
    :REPORT "Use a different function."
    :CONDITION UNDEFINED-FUNCTION
  then the first and second example are equivalent from the point of view of 
  someone using the interactive debugger, but differ in one important aspect 
  for non-interactive handling. If a handler `knows about' proceed function 
  names, as in: (IF (FIND-PROCEED-CASE 'NEW-FUNCTION CONDITION)
	            (NEW-FUNCTION CONDITION THE-REPLACEMENT))
  then only the first example, and not the second, will have control transfered 
  to its correction clause.

  Here's a more complete example:

 	(LET ((MY-FOOD 'MILK)
	      (MY-COLOR 'GREENISH-BLUE))
	  (DO ()
	      ((NOT (BAD-FOOD-COLOR-P FOOD COLOR)))
	    (PROCEED-CASE (ERROR 'BAD-FOOD-COLOR :FOOD MY-FOOD :COLOR MY-COLOR)
	      (USE-FOOD  (IGNORE NEW-FOOD)  (SETQ MY-FOOD  NEW-FOOD))
	      (USE-COLOR (IGNORE NEW-COLOR) (SETQ MY-COLOR NEW-COLOR))))
	  ;; We won't get to here until MY-FOOD and MY-COLOR are compatible.
	  (LIST MY-FOOD MY-COLOR))

  A handler can then proceed the error in either of two ways. It may correct
  the color or correct the food. For example:

       #'(LAMBDA (CONDITION) ... (USE-COLOR CONDITION 'WHITE)  ...) ;Corrects color
   or  #'(LAMBDA (CONDITION) ... (USE-FOOD  CONDITION 'CHEESE) ...) ;Corrects food

  Here is an example using CONDITION-BIND and SIGNAL-CASE...

	(CONDITION-BIND ((FOO-ERROR
			   #'(LAMBDA (CONDITION) (USE-VALUE CONDITION 7))))
	  (PROCEED-CASE (ERROR 'FOO-ERROR)
	    (USE-VALUE (IGNORE X) (* X X))))
	=> 49

				Error Proposal #5 by KMP 3/15/86, Page 13

PROCEED-CASE-NAME proceed-case				[Function]

  Returns the name of the given PROCEED-CASE, or NIL if it is not named.

FIND-PROCEED-CASE name condition			[Function]

  Searches for a proceed case by the given NAME which is applicable to the
  given condition in the current dynamic contour.

  If NAME is a proceed function name, then the innermost (ie, most recently
  established) proceed case with that function name that matches the given
  condition is returned. NIL is returned if no such proceed case is found.

  If NAME is a proceed case object, then it is simply returned unless it
  is not currently valid for use. In that case, NIL is returned.

INVOKE-PROCEED-CASE proceed-case condition &rest values	
							[Function]

  Transfers control to the given PROCEED-CASE, passing the given VALUES.
  The PROCEED-CASE must a proceed case or the name of a proceed function
  which is valid in the current dynamic context. If the argument is not
  valid, an error will be signalled.

  This operation is used primarily as a sub-primitive for implementing
  named proceed functions, but may be necessary when writing certain kinds
  of portable, interactive debuggers. 
  See Footnote: {INVOKE-PROCEED-CASE vs Named Proceed Functions}

				Error Proposal #5 by KMP 3/15/86, Page 14

DEFINE-PROCEED-FUNCTION name [keyword value]* &rest variables
							[Special Form]

  Valid KEYWORD/VALUE pairs are the same as those which are defined for
  the PROCEED-CASE special form. That is, :TEST, :CONDITION, 
  :REPORT-FUNCTION, and :REPORT.

  This form defines a function called NAME which will proceed an error in 
  a typed way. The proceed function takes a required argument of a condition
  and optional arguments which are given by the VARIABLES specification.

  The variable CONDITION is bound to the condition object itself so that it
  will be accessible during the initialization of the optional arguments.

  Each element of VARIABLES has the form 
       VARIABLE-NAME
    or (VARIABLE-NAME INITIAL-VALUE).
  If initial-value is not supplied, it defaults to NIL.

  For example, here are some possible proceed functions which might be useful
  in conjunction with the BAD-FOOD-COLOR error we used as an example earlier:

	(DEFINE-PROCEED-FUNCTION USE-FOOD 
	    :REPORT "Use another food."
	  (FOOD (READ-TYPED-OBJECT 'FOOD "Food to use instead: ")))

	(DEFINE-PROCEED-FUNCTION USE-COLOR 
	    :REPORT "Change the food's color."
	  (COLOR (READ-TYPED-OBJECT 'FOOD "Color to make the food: ")))

        (DEFUN MAYBE-USE-WATER (CONDITION) ;A sample named handler
	  (IF (EQ (BAD-FOOD-COLOR-FOOD CONDITION) 'MILK)
	      (USE-FOOD CONDITION 'WATER)))

	(CONDITION-BIND ((BAD-FOOD-COLOR #'MAYBE-USE-WATER))
	  ...)

  The condition argument to a proceed function is optional. If not provided,
  it defaults to NIL. This may be useful in the implementation of proceed 
  functions such as ABORT, which are not normally called with a condition argument.

  If a named proceed function is invoked in a context in which there is 
  no active proceed case by that name, the proceed function simply returns NIL.
  So, for example, in each of the following pairs of handlers, the first is
  equivalent to the second except for efficiency:
  and less efficient:

	#'(LAMBDA (CONDITION)					;OK, but slow
	    (IF (FIND-PROCEED-CASE 'USE-FOOD CONDITION)
		(USE-FOOD CONDITION 'MILK)))

	#'(LAMBDA (CONDITION) (USE-FOOD CONDITION 'MILK))	;Preferred

     -----

	#'(LAMBDA (CONDITION)
	    (USE-FOOD  CONDITION 'CHOCOLATE)
	    (USE-COLOR CONDITION 'ORANGE))

	#'(LAMBDA (CONDITION)
	    (COND ((FIND-PROCEED-CASE 'USE-FOOD CONDITION)
		   (USE-FOOD CONDITION 'CHOCOLATE))
		  ((FIND-PROCEED-CASE 'USE-COLOR CONDITION)
		   (USE-COLOR CONDITION 'ORANGE))))

				Error Proposal #5 by KMP 3/15/86, Page 15

*** NOTE: In contrast to the way that Zetalisp has defined ABORT as a kind
***       of condition to be handled, we define ABORT as a manner of proceeding
***       a condition rather than as a condition type to be handled.

CATCH-ABORT print-form &body forms			[Macro]

  Sets up a PROCEED-CASE context for the proceed function ABORT.

  If no ABORT is done while executing FORMS, all values returned by the last 
  form in FORMS are returned. If an ABORT transfers control to this CATCH-ABORT, 
  two values are returned: NIL and the condition which was given to ABORT 
  (or NIL if none was given).

  CATCH-ABORT could be defined by:

	(DEFMACRO CATCH-ABORT (PRINT-FORM &REST FORMS)
	  `(PROCEED-CASE (PROGN ,@FORMS)
	     (ABORT (CONDITION)
                 :REPORT ,PRINT-FORM
	         :TEST (LAMBDA (IGNORE) T)
	       (VALUES NIL CONDITION))))

  Example:

    (DEFUN READ-EVAL-PRINT-LOOP (LEVEL)
      (CATCH-ABORT (FORMAT T "Exit command level ~D." LEVEL)
        (LOOP
	  (CATCH-ABORT (FORMAT T "Return to command level ~D." LEVEL)
            (PRINT (EVAL (READ)))))))

  If while executing (READ-EVAL-PRINT-LOOP 1) the user typed (+ 'a 3)
  and landed in the debugger, he might expect to see something like:

	The argument, A, to the function + was of the wrong type.
	The function expected a number.
	[0] Lisp Toplevel
	[1] Exit command level 1
	[2] Return to command level 1
	[3] Supply a new value for this argument
	Selection: 
		
ABORT &optional condition				[Function]

  Transfers control to the innermost (dynamic) CATCH-ABORT form, causing it to
  return NIL immediately. 

  It is not usually useful to specify a CONDITION. This is because the default
  test for ABORT unconditionally returns true and all CATCH-ABORT forms are
  therefore likely to be visible. The only such forms which might not be visible
  are those which override the default test. In that rare case, specifying
  a CONDITION may make a difference.

  ABORT could be defined by:

	(DEFINE-PROCEED-FUNCTION ABORT
	    :REPORT "Abort."
	    :TEST (LAMBDA (IGNORE) T))

  
				Error Proposal #5 by KMP 3/15/86, Page 16

CONDITION-CASE form &rest cases				[Special Form]

  Executes the given form. Each case has the form (type ([var]) . body).
  If a condition is signalled (and not handled by an intervening handler) 
  during the execution of the form for which there is an appropriate clause
  -- ie, one for which (TYPEP condition 'type) is true -- then control is 
  transferred to the body of the relevant clause, binding the given VAR to 
  the condition which was signalled. If no error occurs, then the values
  resulting from the FORM are returned by the CONDITION-CASE.

  If VAR is not needed, it may be omitted.

  TYPE may also be a list of types, in which case it will catch conditions of
  any of the specified types.  

  Examples:

	(CONDITION-CASE (/ X Y)
	  (DIVISION-BY-ZERO () NIL))

        (CONDITION-CASE (OPEN *THE-FILE* :DIRECTION :INPUT)
 	  (FILE-ERROR (CONDITION) (FORMAT T "~&Open failed: ~A~%" CONDITION)))

	(CONDITION-CASE (SOME-USER-FUNCTION)
	  (FILE-ERROR (CONDITION) CONDITION)
	  (DIVISION-BY-ZERO () 0)
	  ((UNBOUND-VARIABLE UNDEFINED-FUNCTION) () 'UNBOUND))

IGNORE-ERRORS &body forms				[Macro]

  Executes its body in a context which handles errors of type ERROR
  by returning control to this form. If no error is signalled, any
  return values returned by the last form are returned by IGNORE-ERRORS.
  Otherwise, NIL is returned. 

  Synonym for (CONDITION-CASE (PROGN . forms) 
		(ERROR () NIL)).


Although they are not described in detail here, it is expected that the 
macros CHECK-TYPE, ASSERT, ETYPECASE, CTYPECASE, ECASE, and CCASE should 
continue to be supported essentially as described in CLtL.

				Error Proposal #5 by KMP 3/15/86, Page 17


			      PRE-DEFINED TYPES
			      -----------------

Implementation Note: The types PROCEED-CASE, CONDITION, etc. are new ``first 
  class'' types in the sense that they must be distinguishable from any other
  CL types of which they are subtypes. This is necessary because PRINC is 
  specified to treat them specially. DEFSTRUCT is one way to implement these
  types.

PROCEED-CASE						[Type]

  This is the data type used to represent a proceed case.

The CONDITION type hierarchy looks like this:

		     CONDITION
			 !
	 +---------------+---------------+
	 !               !               !
 SIMPLE-CONDITION     WARNING     SERIOUS-CONDITION
			 !               !
		  SIMPLE-WARNING         !
					 !
					 !
	     +--------------+------------+---------+
	     !              !                      !
       SIMPLE-BREAK   STORAGE-CONDITION          ERROR
			    !                      !
		   +--------+--------+             !
		   !                 !             !
	      STACK-OVERFLOW  STORAGE-EXHAUSTED    !
						   !
						   !
				       +-----------+---+------------------+--- . . .
				       !               !                  !
				 SIMPLE-ERROR    ARITHMETIC-ERROR   CONTROL-ERROR
 

The types which are non-terminals in the above tree (ie, CONDITION, 
WARNING, SERIOUS-CONDITION, STORAGE-CONDITION, ERROR, ARITHMETIC-ERROR, 
CONTROL-ERROR, etc.) are provided primarily for type inclusion 
purposes. Normally, they would not be directly instantiated. 

Implementations are permitted to support non-portable synonyms for 
these types, as well as to introduce other types which above, below, 
or between the types shown in this tree as long as the indicated 
subtype relationships are not violated. 
See Footnote: {TYPEP vs CONDITION-TYPEP}

				Error Proposal #5 by KMP 3/15/86, Page 18

CONDITION						[Type]

  All types of conditions, whether error or non-error, must inherit from 
  this type.

WARNING							[Type]

  All types of warnings should inherit from this type. 
  This is a subtype of CONDITION.

SERIOUS-CONDITION					[Type]

  Any condition, whether error or non-error, which should enter the debugger
  when signalled but not handled should inherit from this type. This is a
  subtype of CONDITION.

  Note: IGNORE-ERRORS will ignore conditions of type ERROR, not of type
  SERIOUS-CONDITION. Conditions which are serious conditions but not errors
  are typically those that may require more sophisticated handling than
  simply being ignored. For example, IGNORE-ERRORS will not ignore a
  STORAGE-CONDITION, which is a serious condition but is not generally 
  a program error.

  Compatibility Note: SERIOUS-CONDITION is similar to Zetalisp's 
  DBG:DEBUGGER-CONDITION.

ERROR							[Type]

  All types of error conditions inherit from this condition.
  This is a subtype of CONDITION.

				Error Proposal #5 by KMP 3/15/86, Page 19

The default condition type for SIGNAL is SIMPLE-CONDITION, for 
break is SIMPLE-BREAK, and for ERROR and CERROR is SIMPLE-ERROR.

SIMPLE-CONDITION					[Type]

  Conditions signalled by SIGNAL when given a format string as a first
  argument are of this type. This is a subtype of CONDITION.
  The init keywords :FORMAT-STRING and :FORMAT-ARGUMENTS are supported.

SIMPLE-WARNING						[Type]

  Conditions signalled by WARN when given a format string as a first
  argument are of this type. This is a subtype of WARNING.
  The init keywords :FORMAT-STRING and :FORMAT-ARGUMENTS are supported.

SIMPLE-BREAK						[Type]

  Conditions used by BREAK when given a format string as a first
  argument are of this type. This is a subtype of SERIOUS-CONDITION.
  The init keywords :FORMAT-STRING and :FORMAT-ARGUMENTS are supported.

  Note: This type of condition is not generally signalled, but objects
  of this type are generally used as a reference while in a break to
  compute the available proceed types. See the description of BREAK
  for more details.

SIMPLE-ERROR						[Type]

  Conditions signalled by ERROR and CERROR when given a format string 
  as a first argument are of this type. This is a subtype of ERROR.
  The init keywords :FORMAT-STRING and :FORMAT-ARGUMENTS are supported.

				Error Proposal #5 by KMP 3/15/86, Page 20

STORAGE-CONDITION					[Type]

  Conditions which relate to memory overflow conditions should inherit 
  from this type. This is a subtype of SERIOUS-CONDITION.

STACK-OVERFLOW						[Type]

  Conditions which relate to stack overflow should inherit from this type.
  This is a subtype of STORAGE-CONDITION.

STACK-EXHAUSTED						[Type]

  Conditions which relate to any kind of GC overflow should inherit from
  this type. This is a subtype of STORAGE-CONDITION.

-------------------------

CONTROL-ERROR						[Type]

  Errors in the transfer of control in a program should inherit from
  this type. This is a subtype of ERROR.

ILLEGAL-THROW						[Type]

  The error which results when THROW is given a tag which is not active
  should inherit from this. This is a subtype of CONTROL-ERROR. The
  function ILLEGAL-THROW-TAG will access the offending tag.

ILLEGAL-GO						[Type]

  The error which results when GO is given a tag which is no longer 
  available should inherit from this. This is a subtype of CONTROL-ERROR.
  The function ILLEGAL-GO-TAG will access the offending tag.

-------------------------

STREAM-ERROR						[Type]

  Errors which occur during input from or output to a stream should
  inherit from this type. This is a subtype of ERROR. The function
  STREAM-ERROR-STREAM will access the offending stream.

READ-ERROR						[Type]

  Errors which occur during an input operation on a stream should inherit
  from this type. This is a subtype of STREAM-ERROR.

END-OF-FILE						[Type]

  The error which results when a read operation is done on a stream which has no
  more tokens should inherit from this type. This is a subtype of READ-ERROR.

				Error Proposal #5 by KMP 3/15/86, Page 21

CELL-ERROR						[Type]

  Errors which occur while accessing a location should inherit from this
  type. This is a subtype of ERROR. The function CELL-ERROR-NAME will
  access the name of the offending cell.

UNBOUND-VARIABLE					[Type]

  The error which results from trying to access the value of an unbound
  variable should inherit from this type. This is a subtype of CELL-ERROR.

UNDEFINED-FUNCTION					[Type]

  The error which results from trying to access the value of an undefined
  function should inherit from this type. This is a subtype of CELL-ERROR.

-------------------------

ARITHMETIC-ERROR					[Type]

  Errors which occur while doing arithmetic type operations should inherit
  from this type. This is a subtype of ERROR. The functions
  ARITHMETIC-ERROR-OPERATION and ARITHMETIC-ERROR-OPERANDS will access the
  offending operation and arguments, respectively.

				Error Proposal #5 by KMP 3/15/86, Page 22


				FOOTNOTES
				---------

{INVOKE-PROCEED-CASE vs Named Proceed Functions}

    Some readers may wonder why there both proceed functions and an 
    INVOKE-PROCEED-CASE primitive. 
   
    The reason for named proceed functions is to formalize interfaces, 
    while the reason for PROCEED-CASE-INVOKE is to provide flexible 
    and portable access to the mechanism.
   
    INVOKE-PROCEED-CASE has the following two purposes:
     * As a sub-primitive, to implement named proceed functions.
     * To invoke anonymous proceed cases. (eg, in an interactive debugger).
   
    Writers of portable code are encouraged to prefer the use of named proceed 
    functions over the use of INVOKE-PROCEED-CASE in any situation where it is 
    feasible. Nevertheless, it should be recognized that some useful, portable 
    programs (particularly, interactive debuggers) can only be written using 
    INVOKE-PROCEED-CASE.

{TRUE}

    The function #'(LAMBDA (IGNORE) T) is going to be a common one to use in
    conjunction with this system. Hopefully we can agree that a function
    #'TRUE could be established to mean #'(LAMBDA (&REST IGNORE) T) to help
    reduce visual clutter.

{TYPEP vs CONDITION-TYPEP}

    An earlier version of this proposal used a function called CONDITION-TYPEP
    rather than using real TYPEP. Over MLY's objections, I finally chose to
    use TYPEP for the following reasons:

     * We need a type system which can deal with these issues. Reducing the
       need for TYPEP to address these issues might reduce the perceived need
       for us to converge on a better type system.

     * If we later adopt a better type system, it is possible that any
       CONDITION-TYPEP introduced now would have different inheritance rules.
       It would be undue burden on the user to have to remember the rules
       for more than one kind of type system.

     * Introducing a CONDITION-TYPEP sets up a precedent for the introduction
       of other xxx-TYPEP operations. It would be too easy for such type systems
       to vary in subtle ways. It is better to simply insist that TYPEP be 
       good enough as is, or be improved until it is good enough.

				Error Proposal #5 by KMP 3/15/86, Page 23

{:REPORT vs :REPORT-FUNCTION}

    Originally, I had :REPORT-FUNCTION, :REPORT-STRING, and :REPORT.

    Moon objected to a bunch of keywords which did similar things. He wanted
    just one keyword. He also objected to the new term "report", feeling that
    "print" was adequate. 

    I circulated a draft proposal with just a :PRINT option that did what the
    :REPORT option does in this proposal, but with no analog for the 
    :REPORT-FUNCTION. I wasn't completely happy with the absence of 
    :REPORT-FUNCTION but figured I'd live with it if it saved a lot of fuss.

    MLY objected to the absence of :PRINT-FUNCTION. So I backed up a bit
    and decided that there were probably really two camps and that we should
    just serve both. MLY also wondered why this option controlled typeout 
    only in the case where *PRINT-ESCAPE* was NIL. So I backed up and introduced
    the term "report" instead of PRINT so that people wouldn't wonder why
    the :PRINT option didn't control the entire behavior of PRIN1 and PRINT.

    The final result of this was to revert back to :REPORT and :REPORT-FUNCTION,
    but to omit :REPORT-STRING as being unnecessary. I hope that no one will
    argue a lot about this -- it will serve most people's needs and I think is
    the sort of thing we could go around and around about to no good end.

				Error Proposal #5 by KMP 3/15/86, Page 24


				  REFERENCES
				  ----------

Some background information about motivation for decisions in this proposal
may be found in my paper ``Exceptional Situations in Lisp,'' which is
available as A.I. Working Paper 268 from the MIT AI Lab publications office
(545 Technology Square, Cambridge, MA 02139).

Much of the basis of ``Exceptional Situations in Lisp'' derives from
``Signalling and Handling Conditions,'' a document published by Symbolics,
Inc.  which describes the Lisp Machine's condition system as it looked when
originally introduced in 1983.