REF CONDITIONS                                   John Williams, Mar 1995

       COPYRIGHT University of Sussex 1995. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<        CONDITIONS           >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<


This  file  briefly  describes  the  functions,  macros  and   variables
documented in Chapter 29  of the standard Common  Lisp guide, which  is:
Common Lisp: The Language,  2nd Edition (Guy  L. Steele, Digital  Press,
1990).


---------------------------------------------
1  Listing of Variables, Functions and Macros
---------------------------------------------

*break-on-signals*                                            [variable]
        When a  condition  is  signaled with  signal,  the  debugger  is
        entered if  (typep condition  *break-on-signals*) is  true.  The
        initial value of *break-on-signals* is nil.


*debugger-hook*                                               [variable]
        Whenever the  Lisp debugger  is invoked  by invoke-debugger,  it
        first checks the value of *debugger-hook*. This variable  should
        hold either nil or a function of two arguments, a condition  and
        the value of  *debugger-hook*. This function  may either  handle
        the condition (transfer  control) or  return normally  (allowing
        the debugger to  run). Note that,  to minimize recursive  errors
        while debugging, *debugger-hook*  is bound to  nil when  calling
        this function.


(abort &optional condition)                                   [function]
        Invokes the most recently  established restart named abort  (and
        associated with condition, if supplied). Returns nil if no  such
        restart exists.


(arithmetic-error-operands condition)                         [function]
(arithmetic-error-operation condition)                        [function]
        These functions  access  the  operands  and  operator  slots  of
        condition (which should be of type arithmetic-error).


(assert test-form [({place}*) [datum {argument}*]])              [macro]
        assert signals  an  error if  the  value of  test-form  is  nil.
        Continuing from this error allows  the user to alter the  values
        of the  generalized variables  listed in  {places}*, and  assert
        will then  start over,  evaluating  test-form again.  The  forms
        datum and {argument}* are used to construct the condition to  be
        signaled if test-form evaluates to  nil. If these arguments  are
        not supplied, a condition of type simple-error is used.


(break &optional format-string &rest format-arguments)        [function]
        Invokes the  Lisp debugger  on a  simple-condition created  from
        format-string and format-arguments (which default to "" and  nil
        respectively). A restart named continue is associated with  this
        condition, which  when invoked  exits the  debugger and  returns
        from break with nil.


(ccase keyplace {({({key}*) | key} {form}*)}*)                   [macro]
        Like  case,   except  that   a   continuable  error   (of   type
        simple-type-error) is signaled if keyplace  is not eq to any  of
        the specified key's.


(cell-error-name condition)                                   [function]
        Given a condition of  type cell-error, returns  the name of  the
        offending cell.


(cerror continue-format-string datum &rest arguments)         [function]
        Like error, except that when the debugger is entered, a  restart
        named continue is  available which if  invoked returns from  the
        call of cerror with the value nil. continue-format-string is  by
        the debugger  to display  the effect  of invoking  the  continue
        restart.


(check-type place type [string])                                 [macro]
        check-type signals an error (of type simple-type-error) if place
        does not conform to the  type specification type. On  continuing
        from this error with the continue restart, the user can  specify
        a new value  to be stored  in place which  is again checked  for
        type conformity.  string should  be  an English  description  of
        type. If string  is not  supplied it  is computed  automatically
        from type. check-type returns nil.


(compute-restarts &optional condition)                        [function]
        If condition is supplied, returns  a list of restarts  currently
        associated with that condition. Otherwise returns a list of  all
        currently active restarts.


(continue &optional condition)                                [function]
        Invokes the  most recently  established restart  named  continue
        (and associated with condition, if supplied). Returns nil if  no
        such restart exists.


(ctypecase keyplace {(type {form}*)}*)                          [macro]
        Like  typecase,  except  that  a  continuable  error  (of   type
        simple-type-error) is signaled  if the type  of keyplace is  not
        one of the specified type's.


(define-condition name ({parent-type}*)                          [macro]
                  [({slot-specifier}*)
                   {(keyword value)}*])
        For defining new sub-types of condition. The syntax of the lists
        {parent-type}* and  {slot-specifier}* is  the  same as  that  of
        defclass. The possible keyword's are :documentation and :report.
        See Steele 1990 p899 for details of these.


(ecase keyform {({({key}*) | key} {form}*)}*)                    [macro]
        Like case, except that a fatal error (of type simple-type-error)
        is signaled if keyform is not eq to any of the specified key's.


(error datum &rest arguments)                                 [function]
        Uses signal to signal an error, the precise condition type being
        determined by  the values  of datum  and arguments.  Unless  the
        condition is handled specially,  error's default behavior is  to
        print   a   message   describing   the   error   condition    on
        *error-output*, and then enter the debugger.


(etypecase keyform {(type {form}*)}*)                            [macro]
        Like  typecase,   except   that   a   fatal   error   (of   type
        simple-type-error) is signaled if the type of keyform is not one
        of the specified type's.


(file-error-pathname condition)                               [function]
        Returns  the  offending  pathname  from  a  condition  of   type
        file-error.


(find-restart restart-identifier &optional condition)         [function]
        Returns for the most recently established restart whose name  is
        restart-identifier and  that is  associated with  condition,  if
        that argument is supplied.  restart-identifier may be a  restart
        object, in which case it is returned if it is a currently active
        restart.  find-restart  returns  nil  if  it  cannot  locate  an
        appropriate restart.


(handler-bind ({(condition-type handler)}*) {form}*)             [macro]
        Creates a  table  binding  each condition-type  to  its  handler
        function, and  then executes  {form}*.  These bindings  will  be
        visible to calls of  signal that occur  during the execution  of
        {form}*.


(handler-case expression                                         [macro]
              {(condition-type ([var]) {form}*)}*
              [:no-error (arglist) . body])

        Syntactic   sugar    for   handler-bind.    First,   for    each
        condition-type, a handler function  is created which if  invoked
        will set var to the condition being signaled and then return the
        result(s) of executing {form}* from the handler-case form. Then,
        expression is executed.

        If a  :no-error  case  is  present,  the  results  of  executing
        expression are passed to the body  of the :no-error form, as  if
        by:

            (multiple-value-call #'(lambda (arglist) . body)
                expression)

        Assuming, of course, that none of the handler functions has been
        invoked and passed control out of the handler-case form.


(ignore-errors {form}*)                                          [macro]
        Executes {form}*. During execution, conditions of type error are
        handled by a  function which exits  from the ignore-errors  form
        with two  return  values:  nil and  the  error  condition.  Uses
        handler-bind.


(invoke-debugger condition)                                   [function]
        Invokes the Lisp debugger.


(invoke-restart restart-identifier &rest arguments)           [function]
        Invokes  the  restart  identified  by  restart-identifier   with
        arguments as arguments. Uses find-restart to locate the  restart
        identified by restart-identifier.


(invoke-restart-interactively restart-identifier)             [function]
        Similar to invoke-restart, except that the :interactive function
        associated with restart-identifier is executed (if present).


(make-condition type &rest slot-initializations)              [function]
        Returns a condition object of the specified type, with the slots
        initialised from the given slot-initializations.


(muffle-warning &optional condition)                          [function]
        Invokes   the   most   recently   established   restart    named
        muffle-warning (and  associated  with condition,  if  supplied).
        Returns nil if no such restart exists.


(package-error-package condition)                             [function]
        Returns the offending  package (or package  name) involved  in a
        condition of type package-error.


(restart-bind ({(name function {keyword value}*)}*)              [macro]
                {form}*)
        Creates a series of restart bindings, and then executes {form}*.
        Each restart has  name name and  when invoked by  invoke-restart
        will   execute    function.   The    possible   keyword's    are
        :test-function, :interactive-function, and :report-function. See
        Steele 1990 p909-10 for details of these.


(restart-case expression                                         [macro]
              {(case-name arglist
                {keyword value}*
                {form}*)}*)
        Syntactic sugar for  restart-bind. First,  for each  case-name a
        restart is  created whose  effect, if  invoked, is  to exit  the
        restart-case  form  and  return  the  result(s)  of   evaulating
        {form}*. Then, expression is executed.

        The variables in arglist are bound  to the values passed to  the
        restart by invoke-restart.  The possible  keyword's are:  :test,
        :interactive and :report. See Steele 1990 p905-6 for details  of
        these.


(restart-name restart)                                        [function]
        Returns the name of restart.


(signal datum &rest arguments)                                [function]
        Constructs a condition object from datum and arguments, and then
        `signals' it,  i.e. examines  the  handler bindings  created  by
        handler-bind and executes any handler functions associated  with
        this condition. signal returns  nil (unless a handler  transfers
        control elsewhere). Note that  if the condition  is a member  of
        the type  denoted by  *break-on-signals*, the  debugger will  be
        entered prior to beginning the process of signaling

        The condition to be signaled is constructed as follows:

        If datum is a condition, then that condition is used directly.

        If datum  is a  condition  type (a  class  or class  name),  the
        condition used is:

            (apply #'make-condition datum arguments)

        Finally, if datum is a string, then the condition used is:

            (make-condition 'simple-error
                :format-string datum
                :format-arguments arguments)


(simple-condition-format-arguments condition)                 [function]
(simple-condition-format-string condition)                    [function]
        These functions  access the  format-arguments and  format-string
        slots of condition (which should be of type simple-condition).


(store-value value &optional condition)                       [function]
        Invokes the most recently established restart named  store-value
        (and associated  with condition,  if  supplied), with  value  as
        argument. Returns nil if no such restart exists.


(stream-error-stream condition)                               [function]
        Returns  the  offending   stream  from  a   condition  of   type
        stream-error.


(type-error-datum condition)                                  [function]
(type-error-expected-type condition)                          [function]
        These functions  access the  datum  and expected-type  slots  of
        condition (which should be of type type-error).


(use-value value &optional condition)                         [function]
        Invokes the most  recently established  restart named  use-value
        (and associated  with condition,  if  supplied), with  value  as
        argument. Returns nil if no such restart exists.


(warn datum &rest arguments)                                  [function]
        Uses signal  to signal  a warning,  the precise  condition  type
        being determined by  the values of  datum and arguments.  Unless
        the condition is handled  specially, warn's default behavior  is
        to print a message  describing the condition on  *error-output*,
        and then enter the debugger.


(with-condition-restarts condition-form restarts-form            [macro]
                            {declaration}* {form}*)
        The value  of condition-form  should be  a condition  C and  the
        value of restarts-form should be a list of restarts (R1 R2 ...).
        The forms of the body are evaluated as an implicit progn.  While
        in the dynamic context of the body, an attempt to find a restart
        associated with  a particular  condition  C' will  consider  the
        restarts R1, R2, ... if C' is eq to C.


(with-simple-restart (name format-string {format-argument}*)     [macro]
                        {form}*)
        Creates a restart  named name,  and then  executes {form}*.  If,
        during  execution,  the  restart  named  by  name  is   invoked,
        execution of {form}* is terminated and the two values nil  and t
        are returned  from the  with-simple-restart form.  format-string
        and  {format-argument}*  are  used  to  construct  the   :report
        function for the restart.



--- C.all/lisp/ref/conditions
--- Copyright University of Sussex 1995. All rights reserved.
