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 = nextSibling(p)) { SwigType *pt = Getattr(p, "type"); /* Get parameter type */ String *pn = Getattr(p, "name"); /* Get parameter name */ String *value = Getattr(p, "value"); /* 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", node, pname, 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.