diff options
Diffstat (limited to 'Doc/Devel/migrate.txt')
-rw-r--r-- | Doc/Devel/migrate.txt | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/Doc/Devel/migrate.txt b/Doc/Devel/migrate.txt new file mode 100644 index 000000000..b40fa36ae --- /dev/null +++ b/Doc/Devel/migrate.txt @@ -0,0 +1,140 @@ +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. + + |