"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libbasic' }"

Object subclass:#GenericException

	instanceVariableNames:'signal parameter errorString suspendedContext handlerContext

		rejected originator proceedable handlingException'

	classVariableNames:''

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

GenericException class instanceVariableNames:'NotifierString'

"

 No other class instance variables are inherited by this class.

"

!

!GenericException class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    GenericException and its subclasses implement the same protocol as Signal.

    So class based exceptions may be implemented as subclasses of GenericException.

    Instances of Exception are passed to a Signal handling block as argument.

    The handler block may perform various actions by sending corresponding messages

    to the exception object. The following actions are possible:

        reject          - don't handle this signal;

                          another handler will be searched for, 

                          upper in the calling hierarchy

        proceed         - return from the Signal>>raise, with nil as value

        proceedWith:val - same, but return val from Signal>>raise

        return          - return from the Signal>>handle:do:, with nil as value

        returnWith:val  - same, but return val from Signal>>handle:do:

                          (this is also the handlers default, 

                           if it falls through; taking the handlerBlocks value

                           as return value)

        restart         - restart the Signal>>handle:do:, after repairing

    Via the Exception object, the handler can also query the state of execution:

    where the Signal was raised, where the handler is, the signal which caused

    the error and the errorString passed when the signal was raised. Also, an optional

    parameter can be passed - the use is signal specific.

    [instance variables:]

        signal           <Signal>     the signal which caused the exception

        parameter        <Object>     a parameter (if any) which was passed when raising

                                      the signal (only if raised with #raiseWith:aParameter)

        errorString      <String>     an errorString 

                                      (usually the signals own errorString, but sometimes

                                       changed explicitely in #raiseWith:errorString:)

        suspendedContext <Context>    the context in which the raise occured

        handlerContext   <Context>    the context of the handler (if any)

    In case of an unhandled signal raise, Exceptions EmergenyHandler will be evaluated. 

    The default emergeny handler will enter the debugger.

    For applications, which do not want Debuggers to come up, other handlers are

    possible.

    For example, to get the typical C++ behavior, use:

        Exception emergencyHandler:[:ex | Smalltalk exitWithCoreDump]

    [see also:]

        Signal  SignalSet QuerySignal

        Context Block

        Object DebugView

        (``Exception handling and signals'': programming/exceptions.html)

    [author:]

        Claus Gittinger

"

!

examples

"

    Examples on Exception-raising & handling are found in the doc/coding

    section (CodingExamples).

    The emergencyHandler stuff is very useful, to prevent endUser applications

    from entering the debugger. See the examples in NoHandlerError.

"

! !

!GenericException class methodsFor:'initialization'!

initialize 

    NotifierString := 'unknown exception'.

    "Modified: / 4.8.1999 / 09:06:26 / stefan"

! !

!GenericException class methodsFor:'instance creation'!

signal:aSignal originator:origin

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew) signal:aSignal originator:origin.

    "Created: / 23.7.1999 / 13:40:45 / stefan"

!

signal:aSignal parameter:aParameter errorString:aString suspendedContext:sContext originator:origin

    "create a new instance and set the fields in preparation for a raise.

     - only to be sent from the signal when raising"

    "{ Pragma: +inlineNew }"

    ^ (self basicNew)

        signal:aSignal 

        parameter:aParameter 

        errorString:aString 

        suspendedContext:sContext 

        originator:origin.

! !

!GenericException class methodsFor:'Compatibility - ANSI'!

signalWith:errorString

    self raiseErrorString:errorString

! !

!GenericException class methodsFor:'Signal constants'!

noHandlerError

    ^ NoHandlerError

    "Created: / 4.8.1999 / 08:33:35 / stefan"

!

proceedError

    ^ ProceedError

    "Created: / 4.8.1999 / 08:34:30 / stefan"

!

recursiveExceptionError

    "return the signal used to handle recursive signals in the handlers"

    ^ RecursiveExceptionError

    "Created: / 4.8.1999 / 09:05:06 / stefan"

!

recursiveExceptionSignal

    "return the signal used to handle recursive signals in the handlers.

     This is for backward compatinility. Use recursiveExceptionError"

    ^ RecursiveExceptionError

    "Modified: / 4.8.1999 / 09:05:59 / stefan"

!

wrongProceedabilityError

    ^ WrongProceedabilityError

    "Created: / 4.8.1999 / 08:34:19 / stefan"

! !

!GenericException class methodsFor:'accessing'!

notifierString:aString

    NotifierString := aString

! !

!GenericException class methodsFor:'compatibility - accessing'!

errorString

    "#errorString is deprecated, use description instead"

    ^ self description

!

handlerBlock

    "Compatibility with Signal. Class based exeptions do not have a handler

     block. They redefine the #action method instead"

    ^ nil

    "Created: / 23.7.1999 / 14:43:18 / stefan"

    "Modified: / 24.7.1999 / 20:52:10 / stefan"

! !

!GenericException class methodsFor:'compatibility - defaults'!

emergencyHandler

    ^ NoHandlerError emergencyHandler.

!

emergencyHandler:aOneArgBlock

    "set the handler used for unhandled exceptions.

     The default (a nil-handler) leads to a debugger to be shown."

    ^ NoHandlerError emergencyHandler:aOneArgBlock.

    "ST-80 behavior of first showing a notifier:

     (I prefer to get right into the debugger, though)

     Exception

        emergencyHandler:

            [:ex | self errorNotify:ex errorString ]

    "

    "ST-X behavior of going right into the debugger:

     Exception

        emergencyHandler:nil

    "

    "automatically aborting current operation, on error:

     (may be useful for end-user apps; make certain, 

      you have abortSignal handlers at appropriate places)

     Exception

        emergencyHandler:

            [:ex | Object abortSignal raise. ex return. ]

    "

    "finally, traditional language system behavior; dump core ;-)

     Exception

        emergencyHandler:

            [:ex | Smalltalk exitWithCoreDump. ]

    "

    "Modified: 15.1.1997 / 20:49:06 / cg"

! !

!GenericException class methodsFor:'compatibility - queries'!

accepts:aSignal

    "return true, if the receiver accepts the argument, aSignal.

     (i.e. the receiver is aSignal or a parent of it). False otherwise."

    |s|

    self == aSignal ifTrue:[^ true].

    aSignal isQuerySignal ifTrue:[^ false].

    s := aSignal.

    [s notNil] whileTrue:[

        self == s ifTrue:[^ true].

        s := s parent

    ].

    ^ false

    "Created: / 23.7.1999 / 14:00:47 / stefan"

!

exception:anExceptionOrSignal isHandledIn:aContext

    "return true, if there is a handler for the receiver signal in the 

     contextChain starting with aContext."

    |con r|

    con := Context findFirstSpecialHandle:true raise:false.

    [con notNil] whileTrue:[

        ((r := con receiver) notNil

         and:[(r handlerForSignal:anExceptionOrSignal context:con originator:nil) notNil]

        ) ifTrue:[

            "found a handler context"

            ^ true

        ].

        con := con findSpecialHandle:true raise:false.

    ].

    ^ false

!

handlerForSignal:signal context:theContext originator:originator

    "answer the handler block for the signal from originator.

     The block is retrieved from aContext.

     Answer nil if the signal is not handled"

    (theContext selector ~~ #'handle:from:do:'

     or:[(theContext argAt:2) == originator]) ifTrue:[

        (self == signal or:[self accepts:signal]) ifTrue:[

            ^ theContext argAt:1

        ]

    ].

    ^ nil

    "Created: / 25.7.1999 / 19:52:58 / stefan"

!

handlerProtectedBlock:doBlock inContext:context

    "set the handlerProtectedBlock in context"

    context selector == #handle:do: ifTrue:[

        context argAt:2 put:doBlock.

    ] ifFalse:[context selector == #handle:from:do: ifTrue:[

        context argAt:3 put:doBlock.

    ]].

!

handlingExceptionInContext:theContext

    "answer the handling exception from aContext."

    (theContext selector == #'handle:from:do:'

     or:[theContext selector == #'handle:do:']) ifTrue:[

        ^ theContext receiver

    ].

    ^ nil

!

inheritsFrom:anotherSignal

    "return true, if the receiver is a child of anotherSignal

     (i.e. if handling anotherSignal also handles the receiver)

     This is almost the same as accepts, but returns false, if

     the receiver is identical to anotherSignal."

    self == anotherSignal ifTrue:[^ false].

    ^ anotherSignal accepts:self

    "Created: / 23.7.1999 / 13:59:51 / stefan"

!

isHandled

    "return true, if there is a handler for the receiver signal.

     Raising an unhandled signal will usually lead into the debugger,

     but can be caught globally by setting Exceptions EmergencyHandler."

    ^ self exception:self isHandledIn:(thisContext sender).

    "Created: / 23.7.1999 / 14:03:50 / stefan"

!

isHandledIn:aContext

    "return true, if there is a handler for the receiver signal in the 

     contextChain starting with aContext."

    ^ self exception:self isHandledIn:aContext

!

isQuerySignal

    "return true, if this is a querySignal - always return false here"

    ^ false

    "Created: / 23.7.1999 / 13:50:16 / stefan"

!

isSignal

    "return true, if the receiver is some kind of signal;

     true returned here - the method is redefined from Object."

    ^ true

    "Created: / 23.7.1999 / 13:49:59 / stefan"

!

mayProceed

    "return true, if the exception handler is allowed to proceed

     the execution where the exception occured.

     Subclasses may redefine this."

    ^ true

    "Modified: / 23.7.1999 / 14:50:11 / stefan"

!

parent

    "return the parent Signal/Exception of myself.

     Subclasses may redefine this to install themself as child of

     existing Signals."

    self == GenericException ifTrue:[

        ^ nil

    ].

    ^ self superclass

    "Created: / 23.7.1999 / 14:01:29 / stefan"

    "Modified: / 23.7.1999 / 16:15:38 / stefan"

! !

!GenericException class methodsFor:'compatibility - raising'!

new

    "{ Pragma: +inlineNew }"

    ^ self basicNew signal:self.

    "Modified: / 23.7.1999 / 13:53:12 / stefan"

    "Created: / 24.7.1999 / 13:21:13 / stefan"

!

newException

    ^ self new

    "Created: / 23.7.1999 / 13:45:49 / stefan"

    "Modified: / 24.7.1999 / 13:21:25 / stefan"

!

newExceptionFrom:originator

    "answer a new exception object for this signal.

     Set the originator.

     Subclasses may redefine this method"

    ^ self new originator:originator

    "Created: / 23.7.1999 / 13:47:07 / stefan"

!

raise

    "raise a signal nonproceedable.

     The signals notifierString is used as errorString."

    <context: #return>

    ^ self newException 

        suspendedContext:thisContext sender;

        raise

    "Modified: / 2.5.1996 / 16:36:23 / cg"

    "Modified: / 5.3.1998 / 16:44:36 / stefan"

    "Created: / 23.7.1999 / 14:07:17 / stefan"

!

raiseErrorString:aString

    "raise a signal nonproceedable.

     The argument is used as errorString."

    <context: #return>

    ^ self newException 

        suspendedContext:thisContext sender;

        errorString:aString;

        raise.

    "Modified: / 9.5.1996 / 15:17:59 / cg"

    "Modified: / 12.3.1998 / 15:15:22 / stefan"

    "Created: / 23.7.1999 / 14:07:33 / stefan"

!

raiseFrom:something

    "raise a signal nonproceedable.

     The argument, something is passed both as parameter and originator."

    <context: #return>

    ^ (self newExceptionFrom:something) 

        suspendedContext:thisContext sender;

        parameter:something;

        raise

    "Modified: / 2.5.1996 / 16:36:38 / cg"

    "Modified: / 5.3.1998 / 16:49:55 / stefan"

    "Created: / 23.7.1999 / 14:07:59 / stefan"

!

raiseRequest

    "raise a signal proceedable.

     The signals notifierString is used as errorString."

    <context: #return>

    ^ self newException