--- a/Signal.st	Sun Jan 16 04:38:33 1994 +0100
+++ b/Signal.st	Sun Jan 16 04:47:41 1994 +0100
@@ -22,25 +22,48 @@
 COPYRIGHT (c) 1993 by Claus Gittinger
               All Rights Reserved
 
+$Header: /cvs/stx/stx/libbasic/Signal.st,v 1.6 1994-01-16 03:46:05 claus Exp $
+'!
+
+!Signal class methodsFor:'documentation'!
+
+documentation
+"
 Signal and Exception provide a framework for exception handling.
+
 A Signal object is usually defined somewhere up in the calling chain
-and associated with some abnormal event. When the event is raised 
-(by Signal>>raise) the control will be either given to a debugger
-or - if a handler was defined - to the handler. The handler will 
-get a description of what (and where) happened in an Exception object.
+and associated with some abnormal event. Many signals are also
+created at startup time and reused.
+
+When the event is raised (by Signal>>raise) the control will be either 
+given to a debugger or - if a handler was defined - to the handler. 
+The handler will get a description of what (and where) happened in an 
+Exception object and decide how to react on the situation (i.e. proceed,
+return or restart).
+
+There is also a companion class called SignalSet, which allows handling
+multiple signals in with one handler (for example all arithmetic signals).
+And, finally there is a very special SignalSet which allows catching
+any signal.
 
 This Signal implementation has been modeled after what some PD
 programs seem to expect - it may not be perfect currently
 (especially, I dont know what nameClass and message are for).
 
-See samples in doc/coding.
+Parts of the implementation is a left-over from old times when the resume/
+restart things in context did not work properly; now, with the handler-
+and suspendedContext at hand, the exception can do it using other mechanisms.
+This might be cleaned up ...
 
-$Header: /cvs/stx/stx/libbasic/Signal.st,v 1.5 1993-12-20 17:32:27 claus Exp $
-'!
+See samples in doc/coding.
+"
+! !
 
 !Signal class methodsFor:'initialization'!
 
 initialize
+    "setup the signal used to handle unhandled signals"
+
     NoHandlerSignal := (Signal new).
     NoHandlerSignal mayProceed:true.
     NoHandlerSignal notifierString:'no Handler'
@@ -57,6 +80,8 @@
 !Signal class methodsFor:'signal access'!
 
 noHandlerSignal
+    "return the signal used to handle unhandled signals"
+
     ^ NoHandlerSignal
 ! !
 
@@ -84,7 +109,9 @@
 !
 
 mayProceed:aBoolean
-    "set/clear the signals ability to proceed"
+    "set/clear the signals ability to proceed.
+     This flag is not checked in the current version of
+     the debugger."
 
     mayProceed := aBoolean
 !
@@ -113,6 +140,18 @@
      aBlock."
 
      ^ aBlock value  "the real logic is in raise/Exception"
+!
+
+catch:aBlock
+     "evaluate the argument, aBlock.
+      If the receiver-signal is raised during evaluation, abort
+      the evaluation and return nil."
+
+      ^ self handle:[:ex | ex return] do:aBlock
+
+      "Object messageNotUnderstoodSignal catch:[
+          123 foobar
+       ]"
 ! !
 
 !Signal methodsFor:'raising'!
@@ -126,7 +165,11 @@
 
     |ex|
 
-    ex := Exception new signal:self.
+    ex := Exception new signal:self
+                     parameter:nil 
+                   errorString:nil
+              suspendedContext:thisContext sender.
+
     ex resumeBlock:[:value | ^ value].
     self evaluateHandlerWith:ex.
 
@@ -150,8 +193,11 @@
 
     |ex|
 
-    ex := Exception new signal:self.
-    ex parameter:aParameter.
+    ex := Exception new signal:self
+                     parameter:aParameter 
+                   errorString:nil
+              suspendedContext:thisContext sender.
+
     ex resumeBlock:[:value | ^ value].
     self evaluateHandlerWith:ex.
 
@@ -171,8 +217,11 @@
 
     |ex|
 
-    ex := Exception new signal:self.
-    ex parameter:aParameter.
+    ex := Exception new signal:self
+                     parameter:aParameter 
+                   errorString:aString
+              suspendedContext:thisContext sender.
+
     ex resumeBlock:[:value | ^ value].
     self evaluateHandlerWith:ex.
 
@@ -211,8 +260,10 @@
             ((con receiver == self) 
             or:[(con receiver isMemberOf:SignalSet) and:[con receiver includes:self]]) ifTrue:[
                 "call the handler"
+
                 anException handlerContext:con.
                 self doCallHandler:(con args at:1) with:anException.
+
                 "if the handler rejects or falls through we arrive here"
                 "continue search for another handler"
             ].
@@ -222,7 +273,10 @@
 !
 
 doCallHandler:aHandler with:ex
-    ex rejectBlock:[^ self].
+    "call the handler proper - needed an extra method
+     to have a separate returncontext for the rejectBlock"
+
+    ex rejectBlock:[^ self]. "this will return on reject"
     aHandler value:ex.
     "handler return - is just like a reject"
 ! !