Doc/Devel/migrate.txt

   1 SWIG1.3 Migration Guide
   2 (The not entirely complete guide to updating language modules to work with SWIG1.3).
   3
   4 Dave Beazley
   5 August 15, 2000
   6
   7 1. Introduction
   8 ---------------
   9
  10 Virtually all of SWIG's internal data structures have now been
  11 rewritten.  Take everything you thought you knew about SWIG1.1 and
  12 throw it out.
  13
  14 2. DataTypes
  15 ------------
  16 The old 'DataType' data structure is gone.  Therefore, direct
  17 manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr'
  18 attributes no longer applies.  Sorry.
  19
  20 Datatypes are now represented by the type 'SwigType' which has no
  21 public attributes.  Actually, if you look at it closely, 'SwigType' is
  22 really just an alias for 'void' and if you look at it even closer than
  23 that you will realize that it's nothing more than a string!
  24
  25 The string encoding of types is described in more detail in the file
  26 Source/Swig/stype.c and is not so important here. What is important is
  27 the functions used to produce various types of output:
  28
  29 SwigType_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
  35 SwigType_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
  42 SwigType_ltype(type);
  43      Returns a SwigType object corresponding to the type created
  44      by SwigType_lstr().
  45
  46 SwigType_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
  50 SwigType_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
  54 SwigType_manglestr(type)
  55      Produces the 'mangled' version of a datatype.
  56
  57
  58 Getting the 'type' code.  Most language modules still operate by
  59 looking at special integer type codes.  This interface is a little
  60 ragged and will probably go away at some point.  However, for now the
  61 following function can be used to get the type code:
  62
  63    int SwigType_type(type)
  64
  65 The codes are the same as the before, except that there are a few
  66 special 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
  74 Because 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
  80 Instead, 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
  91 There are about 2-dozen type manipulation functions that could also be useful.
  92 See Source/Swig/swig.h and Source/Swig/stype.c.
  93
  94 3. Parameter Lists
  95 ------------------
  96
  97 The ParmList data structure is gone.  In reality, parameter lists are nothing more than
  98 a linked list of parameters.   The proper way to iterate over this list and get
  99 parameter 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
 113 4. Typemaps
 114 -----------
 115
 116 Typemaps more or less work.  However, the interface has changed slightly.  Instead of
 117
 118      typemap_lookup("in","python",type,pname,"$source","$target",wrapper);
 119
 120 the function is
 121
 122      Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
 123
 124 There are a variety of other changes to typemaps (see CHANGES).
 125
 126 5. Use of new types
 127 -------------------
 128 When possible, language modules should try to use the built in String,
 129 List, and Hash objects instead of C arrays or 'char *'.   This will probably require a
 130 detailed pass through the code with an eye towards cleanup.
 131
 132 6. Miscellaneous
 133 ----------------
 134 Language modules no longer need to concern themselves with formatting the
 135 wrapper code they produce (provided you are using the special Wrapper object).
 136 The function Wrapper_print() passes everything through a pretty-printer that
 137 automatically performs indentation and tries to clean things up.   This especially
 138 works well when there are lots of typemaps.
 139
 140