added migrate.txt

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

Doc/migrate.txt

@@ -0,0 +1,124 @@
+SWIG1.3 Migration Guide 
+(The not entirely complete guide to updating language modules to work with SWIG1.3).
+
+Dave Beazley
+August 15, 2000
+
+1. Introduction
+---------------
+
+Virtually all of SWIG's internal data structures have now been
+rewritten.  Take everything you thought you knew about SWIG1.1 and
+throw it out.
+
+2. DataTypes
+------------
+The old 'DataType' data structure is gone.  Therefore, direct
+manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr'
+attributes no longer applies.  Sorry.
+
+Datatypes are now represented by the type 'SwigType' which has no
+public attributes.  Actually, if you look at it closely, 'SwigType' is
+really just an alias for 'void' and if you look at it even closer than
+that you will realize that it's nothing more than a string!
+
+The string encoding of types is described in more detail in the file
+Source/Swig/stype.c and is not so important here. What is important is
+the functions used to produce various types of output:
+
+SwigType_str(type,name = 0);
+     This produces an exact C representation of the datatype with all
+     qualifiers, arrays, references, and so forth.  name is an optional
+     name that is given if you wanted to associate the type with a
+     parameter name or something.
+
+SwigType_lstr(type,name = 0);
+     This function takes a type and produces a C string containing
+     a type suitable for assignment (appearing as an lvalue in an
+     expression).  To do this, certain things such as 'const',
+     arrays, and references are stripped away or converted into
+     pointers.  
+     
+SwigType_ltype(type);
+     Returns a SwigType object corresponding to the type created
+     by SwigType_lstr().
+
+SwigType_lcaststr(type,name);
+     Produces a string casting a value 'name' from the real datatype
+     to the assignable type created by SwigType_lstr().
+
+SwigType_rcaststr(type,name)
+     Produces a string that casts a value 'name' from the type
+     created by SwigType_lstr() to the real datatype.
+    
+SwigType_manglestr(type)
+     Produces the 'mangled' version of a datatype.
+
+
+Getting the 'type' code.  Most language modules still operate by
+looking at special integer type codes.  This interface is a little
+ragged and will probably go away at some point.  However, for now the
+following function can be used to get the type code:
+
+   int SwigType_type(type)
+
+The codes are the same as the before, except that there are a few 
+special codes:
+
+     T_STRING          - The 'char *' type and variations.
+     T_POINTER         - Any pointer type (not char * though)
+     T_REFERENCE       - Any C++ reference
+     T_ARRAY           - Any array
+     T_FUNCTION        - A function (this is usually an error).
+
+Because of the special codes, it is no longer necessary to have code like this:
+
+     if ((t->is_pointer == 1) and (t->type == T_CHAR)) {
+           ... get a string ...
+     }
+
+Instead, just use the type code above like this:
+
+     switch(SwigType_type(type)) {
+     case T_STRING:
+          ... get a string ...
+          break;
+     case T_POINTER:
+          ... get a pointer ...
+          break;
+     }
+
+There are about 2-dozen type manipulation functions that could also be useful.
+See Source/Swig/swig.h and Source/Swig/stype.c.
+
+Parameter Lists
+---------------
+
+The ParmList data structure is gone.  In reality, parameter lists are nothing more than
+a linked list of parameters.   The proper way to iterate over this list and get
+parameter values is as follows:
+
+  ParmList *l;
+  Parm *p;
+
+  for (p = l; p; p = Getnext(p)) {
+      SwigType *pt = Gettype(p);        /* Get parameter type */
+      String   *pn = Getname(p);        /* Get parameter name */
+      String   *value = Getvalue(p);    /* Get parameter value */
+      ...
+      do whatever
+      ...
+  }
+
+Typemaps
+--------
+Typemaps more or less work.  However, the interface has changed slightly.  Instead of
+
+     typemap_lookup("in","python",type,pname,"$source","$target",wrapper);
+
+the function is
+
+     Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
+
+There are a variety of other changes to typemaps (see CHANGES).
+