12a43edc2d
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@4141 626c5289-ae23-0410-ae9c-e8d60b6d4f22
140 lines
4.6 KiB
Text
140 lines
4.6 KiB
Text
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.
|
|
|
|
|