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