/tags/rel-1-3-15/SWIG/Doc/Devel/migrate.txt

  1SWIG1.3 Migration Guide 
  2(The not entirely complete guide to updating language modules to work with SWIG1.3).
  3
  4Dave Beazley
  5August 15, 2000
  6
  71. Introduction
  8---------------
  9
 10Virtually all of SWIG's internal data structures have now been
 11rewritten.  Take everything you thought you knew about SWIG1.1 and
 12throw it out.
 13
 142. DataTypes
 15------------
 16The old 'DataType' data structure is gone.  Therefore, direct
 17manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr'
 18attributes no longer applies.  Sorry.
 19
 20Datatypes are now represented by the type 'SwigType' which has no
 21public attributes.  Actually, if you look at it closely, 'SwigType' is
 22really just an alias for 'void' and if you look at it even closer than
 23that you will realize that it's nothing more than a string!
 24
 25The string encoding of types is described in more detail in the file
 26Source/Swig/stype.c and is not so important here. What is important is
 27the functions used to produce various types of output:
 28
 29SwigType_str(type,name = 0);
 30     This produces an exact C representation of the datatype with all
 31     qualifiers, arrays, references, and so forth.  name is an optional
 32     name that is given if you wanted to associate the type with a
 33     parameter name or something.
 34
 35SwigType_lstr(type,name = 0);
 36     This function takes a type and produces a C string containing
 37     a type suitable for assignment (appearing as an lvalue in an
 38     expression).  To do this, certain things such as 'const',
 39     arrays, and references are stripped away or converted into
 40     pointers.  
 41     
 42SwigType_ltype(type);
 43     Returns a SwigType object corresponding to the type created
 44     by SwigType_lstr().
 45
 46SwigType_lcaststr(type,name);
 47     Produces a string casting a value 'name' from the real datatype
 48     to the assignable type created by SwigType_lstr().
 49
 50SwigType_rcaststr(type,name)
 51     Produces a string that casts a value 'name' from the type
 52     created by SwigType_lstr() to the real datatype.
 53    
 54SwigType_manglestr(type)
 55     Produces the 'mangled' version of a datatype.
 56
 57
 58Getting the 'type' code.  Most language modules still operate by
 59looking at special integer type codes.  This interface is a little
 60ragged and will probably go away at some point.  However, for now the
 61following function can be used to get the type code:
 62
 63   int SwigType_type(type)
 64
 65The codes are the same as the before, except that there are a few 
 66special codes:
 67
 68     T_STRING          - The 'char *' type and variations.
 69     T_POINTER         - Any pointer type (not char * though)
 70     T_REFERENCE       - Any C++ reference
 71     T_ARRAY           - Any array
 72     T_FUNCTION        - A function (this is usually an error).
 73
 74Because of the special codes, it is no longer necessary to have code like this:
 75
 76     if ((t->is_pointer == 1) and (t->type == T_CHAR)) {
 77           ... get a string ...
 78     }
 79
 80Instead, just use the type code above like this:
 81
 82     switch(SwigType_type(type)) {
 83     case T_STRING:
 84          ... get a string ...
 85          break;
 86     case T_POINTER:
 87          ... get a pointer ...
 88          break;
 89     }
 90
 91There are about 2-dozen type manipulation functions that could also be useful.
 92See Source/Swig/swig.h and Source/Swig/stype.c.
 93
 943. Parameter Lists
 95------------------
 96
 97The ParmList data structure is gone.  In reality, parameter lists are nothing more than
 98a linked list of parameters.   The proper way to iterate over this list and get
 99parameter values is as follows:
100
101  ParmList *l;
102  Parm *p;
103
104  for (p = l; p; p = Getnext(p)) {
105      SwigType *pt = Gettype(p);        /* Get parameter type */
106      String   *pn = Getname(p);        /* Get parameter name */
107      String   *value = Getvalue(p);    /* Get parameter value */
108      ...
109      do whatever
110      ...
111  }
112
1134. Typemaps
114-----------
115
116Typemaps more or less work.  However, the interface has changed slightly.  Instead of
117
118     typemap_lookup("in","python",type,pname,"$source","$target",wrapper);
119
120the function is
121
122     Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
123
124There are a variety of other changes to typemaps (see CHANGES).
125
1265. Use of new types
127-------------------
128When possible, language modules should try to use the built in String,
129List, and Hash objects instead of C arrays or 'char *'.   This will probably require a
130detailed pass through the code with an eye towards cleanup.
131
1326. Miscellaneous
133----------------
134Language modules no longer need to concern themselves with formatting the
135wrapper code they produce (provided you are using the special Wrapper object).
136The function Wrapper_print() passes everything through a pretty-printer that
137automatically performs indentation and tries to clean things up.   This especially
138works well when there are lots of typemaps.
139
140