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

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.

3. 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
      ...
  }

4. 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).

5. Use of new types
-------------------
When possible, language modules should try to use the built in String,
List, and Hash objects instead of C arrays or 'char *'.   This will probably require a
detailed pass through the code with an eye towards cleanup.

6. Miscellaneous
----------------
Language modules no longer need to concern themselves with formatting the
wrapper code they produce (provided you are using the special Wrapper object).
The function Wrapper_print() passes everything through a pretty-printer that
automatically performs indentation and tries to clean things up.   This especially
works well when there are lots of typemaps.