rename %throws to %catchs

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8351 626c5289-ae23-0410-ae9c-e8d60b6d4f22

CHANGES.current

@@ -1,8 +1,8 @@
 Version 1.3.28 (unreleased).
 ===========================
 01/10/2006: mmatus
-
+	    
-            - Add the %throws directive, which complements the %exception
+            - Add the %catchs directive, which complements the %exception
 	    directive in a more automatic way. For example, if you have
 
                 int foo() throw(E1);
@@ -31,39 +31,57 @@ Version 1.3.28 (unreleased).
 	         } catch(E2) {	... }				  
 	       }				
 	    
-	    which is very tedious. Well, the %throws directive adds the
+	    which is very tedious. Well, the %catchs directive defines
-            'missing' throw list, and from swig:
+	    the list of exception to catch, and from swig:
  	
-	       %throws(E1,E2) barfoo(int i);
+	       %catch(E1,E2) barfoo(int i);
 	       int barfoo(int i);
 
             is equivalent to 
 
 	       int barfoo(int i) throw(E1,E2);
 
-            and then, swig will generate the proper try/catch code
+	    Note, however, that the %catchs list doesn't have to
-            automatically.
+	    correspond to the C++ 'throw' list. For example, if you
+	    have:
 
-	    The complementing part refers to the fact that you use the
+		struct E {};
-	    %exception and %throws directive togheter:
+		struct E1 : E {};
+		struct E2 : E {};
+
+  	        int barfoo(int i) throw(E1,E2);
+
+            you can define
+	        
+		%catchs(E) barfoo(int i);
+	
+	    and swig will generate an action code equivalent to
 
-	       %throws(E1,E2) barfoo(int i);
-               %exception barfoo(int i) {
 	         try {				
 	           $action			
-	         } catch(...) {	
+	         } catch(E &_e) { 
-		    <SWIG fail>;
+		   <raise _e>;
-                 }				  
+		 }	
-	       }				
-	     
-	       int barfoo(int i);
 
-	     and swig, besides adding the code to catch E1,E2, will add the
+            Of course, you still have to satisfy the C++ restrictions,
-	     code to catch the "unknown" exception case.
+	    and the catchs list must be compatible (not the same)
+	    than the original C++ throw list.
 
-	     And not, you can't use it as
+	    Also, you can now specify that you want to catch the
+	    unknown exception '...', for example:
 
-	       %throws(E1,E2,...) barfoo(); // ERROR!!!!
+	       %catchs(E1,E2,...) barfoo(int);
+
+	    In any case, the %catchs directive will emit the
+	    'rethrowing' code using the 'throw' typemap.
+
+	    For the same, for the '...' case to work, you need to
+	    write the proper typemap in your target language. In the
+	    UTL, this looks like:
+
+	      %typemap(throws,noblock=1) (...) {
+                %raise(SWIG_ErrorType(SWIG_UnknownError), "UnknownError", 0);
+              }
 
 
 01/05/2006: wsfulton

Examples/test-suite/exception_order.i

@@ -15,7 +15,7 @@
   }
 }
 
-%throws(E1,E2*,ET<int>,ET<double>) A::barfoo(int i);
+%catchs(E1,E2*,ET<int>,ET<double>,...) A::barfoo(int i);
 
 
 %inline %{

Lib/swig.swg

@@ -88,10 +88,10 @@
 #define %clearexception %feature("except","")
 
 
-/* the %throws directive */
+/* the %catchs directive */
 
-#define %throws(tlist...)       %feature("throws","("`tlist`")")
+#define %catchs(tlist...)    %feature("catchs","("`tlist`")")
-#define %clearthrows         %feature("throws","")
+#define %clearcatchs         %feature("catchs","")
 
 /* the %exceptionclass directive */
 

Lib/typemaps/swigtype.swg

@@ -438,6 +438,10 @@
   %raise(SWIG_NewPointerObj(%as_voidptr(&$1),$descriptor,0), "$type", $descriptor);
 }
 
+%typemap(throws,noblock=1) (...) {
+  %raise(SWIG_ErrorType(SWIG_UnknownError), "UnknownType", 0);
+}
+
 /* ------------------------------------------------------------
  * --- CLASS::* typemaps --- 
  * ------------------------------------------------------------ */

Source/Modules/allocate.cxx

@@ -465,16 +465,19 @@ class Allocate : public Dispatcher {
   }
 
   void mark_exception_classes(Node *n) {
-    ParmList *throws = Getattr(n,"throws");
+    ParmList *throws = 0;
-    if (!throws) {
+    /* the "catchs" feature take precedence over the original throw  list */
-      String *sthrows = Getattr(n,"feature:throws");
+    String *sthrows = Getattr(n,"feature:catchs");
-      if (sthrows) {
+    if (sthrows) {
-	throws = Swig_cparse_parms(sthrows);
+      throws = Swig_cparse_parms(sthrows);
-	if (throws) {
+      if (throws) {
-	  Setattr(n,"throws",throws);
+	Setattr(n,"throws",throws);
-	}
+	Delete(throws);
       }
     }
+    if (!throws) {
+      throws = Getattr(n,"throws");
+    }
     if (throws) {
       ParmList *p = throws;
       while(p) {

Source/Modules/emit.cxx

@@ -437,8 +437,10 @@ void emit_action(Node *n, Wrapper *f) {
         SwigType *etr = SwigType_typedef_resolve_all(et);
         if (SwigType_isreference(etr) || SwigType_ispointer(etr) || SwigType_isarray(etr)) {
           Printf(eaction,"catch(%s) {", SwigType_str(et, "_e"));
-        } else {
+        } else if (SwigType_isvarargs(etr)) {
-          Printf(eaction,"catch(%s) {", SwigType_str(et, "&_e"));
+	  Printf(eaction,"catch(...) {");
+	} else {
+	  Printf(eaction,"catch(%s) {", SwigType_str(et, "&_e"));
         }
 	Printv(eaction,em,"\n",NIL);
 	Printf(eaction,"}\n");