"

 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.

"

Object subclass:#Exception

	instanceVariableNames:'signal parameter errorString suspendedContext handlerContext

		rejected originator resumeBlock rejectBlock proceedable'

	classVariableNames:'EmergencyHandler RecursiveExceptionSignal'

	poolDictionaries:''

	category:'Kernel-Exceptions'

!

Exception class instanceVariableNames:'NotifierString'

"

 The following class instance variables are inherited by this class:

	Object - 

"

!

!Exception 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

"

    Exception and its subclasses implement the same protocal as Signal.

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

    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          - dont 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)

        resumeBlock      <Block>      private to the exception; needed to perform resume action

        rejectBlock      <Block>      private to the exception; needed to perform reject action

    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]

    [Class variables:]

        EmergencyHandler <Block>    this block is evaluated, if no handler was defined

                                    for a signal (i.e. this one is responsible for the

                                    unhandled exception debugger).

                                    Having this being a block allows to globally catch

                                    these errors - even when no enclosing handler-scope

                                    around the erronous code exists.

                                    (as the catch/through does).

        RecursiveExceptionSignal

                         <Signal>   raised when within a handler for some signal,

                                    the same signal is raised again.

    [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.

    Some commonly used (useful) emergency handlers are provided in the

    'useful handlers' section; try them to learn more

    (especially, the mailingHandler is fun).

    Of course, these are only examples - you may define your own handler

    block and pass it to the #emergencyHandler: method.

    BTW: the Launchers 'source & debugger' settings menu allows you

         to install either a default or the notifying handler.

    A handler which shows a box, then aborts - (no more debuggers):

                                                                [exBegin]

        Exception emergencyHandler:(Exception abortingEmergencyHandler)

                                                                [exEnd]

    A handler which aborts - (no box, no debugger):

                                                                [exBegin]

        Exception emergencyHandler:[:ex | AbortSignal raise]

                                                                [exEnd]

    try some exception (for demonstration, in some other process):

                                                                [exBegin]

        [

            #(1 2 3) at:4

        ] fork.

                                                                [exEnd]

    cleanup (switch back to the regular handler, which enters the debugger):

                                                                [exBegin]

        Exception emergencyHandler:nil

                                                                [exEnd]

    A handler which shows a warnBox and asks for debugging:

                                                                [exBegin]

        Exception emergencyHandler:(Exception notifyingEmergencyHandler)

                                                                [exEnd]

    A handler which dumps information to a file (watch the file 'errorTrace.stx'):

                                                                [exBegin]

        Exception emergencyHandler:(Exception dumpingEmergencyHandler)

                                                                [exEnd]

    A handler which sends you mail:

                                                                [exBegin]

        Exception emergencyHandler:(Exception mailingEmergencyHandler)

                                                                [exEnd]

"

! !

!Exception class methodsFor:'initialization'!

initialize 

    "setup the signal used to handle unhandled signals"

    RecursiveExceptionSignal isNil ifTrue:[

	RecursiveExceptionSignal := ErrorSignal newSignalMayProceed:false.

	RecursiveExceptionSignal nameClass:self message:#recursiveExceptionSignal.

	RecursiveExceptionSignal notifierString:'recursive signal raise in handler'

    ]

! !

!Exception 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.

! !

!Exception class methodsFor:'Signal constants'!

recursiveExceptionSignal

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

    ^ RecursiveExceptionSignal

! !

!Exception class methodsFor:'compatibility - accessing'!

errorString

    "return the notifier string.

     If the notifier string starts with space, prepend

     the parents notifier string"

    NotifierString isNil ifTrue:[

        ^ self parent errorString

    ] ifFalse:[

        (NotifierString size > 0 

         and:[NotifierString first == (Character space)]) ifTrue:[

            ^ self parent errorString, NotifierString

        ] ifFalse:[

            ^ NotifierString

        ].

    ]

    "

      Object errorSignal errorString

    "

    "Created: / 23.7.1999 / 14:22:25 / stefan"

!

errorStringExtra:extraString with:aParameter

    "used when raising with a given error string and/or parameter; 

     if the errorString starts with a space, it is appended to the receivers

     notifier string; if it ends with a space, it is prepended.

     Otherwise, the extraString is returned.

     If no extraString is given, use the signals default errorString."

    |t|

    (self inheritsFrom:Object userNotificationSignal) ifTrue:[

        "/ all userNotifications pass the extraString unchanged.

        ^ extraString

    ].

    extraString isNil ifTrue:[

        t := self errorString

    ] ifFalse:[

        t := extraString.

        (extraString endsWith:Character space) ifTrue:[

            t := extraString, self errorString

        ] ifFalse:[

            (extraString startsWith:Character space) ifTrue:[

                t := self errorString, extraString

            ]

        ].

    ].

    ^ t.

"/    aParameter isNil ifTrue:[

"/        ^ t

"/    ].

"/

"/    (t startsWith:' ') ifTrue:[

"/        ^ aParameter printString , t

"/    ].

"/    (t endsWith:' ') ifTrue:[

"/        ^ t , aParameter printString

"/    ].

"/    ^ t

    "Modified: / 25.3.1997 / 12:12:37 / cg"

    "Created: / 23.7.1999 / 14:23:38 / stefan"

!

handlerBlock

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

     block. They redefine the #action method instead"

    ^ nil

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

! !

!Exception 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|

    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"

!

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 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."

    |con r|

    con := aContext.

    [con notNil] whileTrue:[

        con := con findNextContextWithSelector:#'handle:do:' or:#'handle:from:do:' or:nil.

        con notNil ifTrue:[

            "

             is this is a #handle:do: or a #handle:from:do: context

             with self in it ?

            "

            ((r := con receiver) notNil

            and:[r accepts:self]) ifTrue:[

                "found a handler context"

                ^ true

            ]

        ]

    ].

    ^ false

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

!

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 == Exception ifTrue:[

        ^ nil

    ].

    ^ superclass

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

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

! !

!Exception class methodsFor:'compatibility - raising'!

newException

    ^ self new signal:self.

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

    "Modified: / 23.7.1999 / 13:53:12 / 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."

    ^ self newException 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."

    ^ (self newException 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"

!

raiseErrorString:aString in:aContext

    "raise a signal nonproceedable.

     The argument is used as errorString.

     The additional context is passed as the context responsible for the raise,

     allowing a raise to mimicri the exception happened somewhere else."

    ^ (self newException   

              signal:self

              parameter:nil 

              errorString:aString

              suspendedContext:aContext

              originator:nil) raise.

    "Modified: / 26.7.1996 / 16:42:47 / cg"

    "Modified: / 12.3.1998 / 15:43:43 / stefan"

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

!

raiseFrom:something