SWIG (Simplified Wrapper and Interface Generator)
The Stable Development Branch
=============================
In this CVS branch "rel-1-3", fixes in the SWIG core and improvements
to the language modules take place, starting from the stable release
1.3.6.
This branch is also the basis for the unofficial "swig1.3" Debian
package that is available from:
http://www.math.uni-magdeburg.de/~mkoeppe/imo-debian
Eventually this branch will be merged back to the trunk of the CVS
tree (maybe).
Version 1.3.11 (January 31, 2002)
=================================
01/30/2002: beazley
Fix to pass/return by value for C++ objects that define
no default constructor. Changes to the typemap system
made it impossible to wrap C++ objects with no default
constructor. This has been fixed, but the solution
involves some clever template magic contributed by
William Fulton. Please see the comments in the file
Lib/swig.swg for further details. This solution is
experimental and may be refined in a future release.
01/30/2002: beazley
Global variables and member data of type "const char *"
can be set, but the old value is silently discarded without
any garbage collection. This may generate a memory leak.
This change is needed to more safely handle variables
like this:
const char *foo = "Hello World\n";
In this case, it's not safe to free the old value. However,
SWIG can dynamically allocate a new value and make foo point
to it. To fix this memory leak, you can probably do this:
%clear const char *foo;
%apply char * {const char *foo};
*** POTENTIAL INCOMPATIBILITY ***
01/30/2002: beazley
Two minor typemap enhancements have been added. First,
typemaps can issue a warning message by including a special
warning attribute. For example:
%typemap(in,warning="I'm going to do something dangerous") ...
The warning message will show up whenever the typemap is
applied.
Second, a typemap can force a no-match by defining
%typemap(in) sometype "pass";
If this is used, the typemap system will *not* record a
typemap match for "sometype". This can be used to block
selected typemaps. For example, if you wanted to disable
a typemap feature for some type, you could do this.
// Do not allow global variables of type 'const char *' to be set.
%typemap(varin) const char * "pass";
It might also be possible to use this to do subtle and
strange things with typemaps. For example, if you wanted to
make 'blah *' an output value and 'const blah *' an input
parameter, you might do this:
%typemap(ignore) blah *(blah temp) {
$1 = &temp;
}
%typemap(argout) blah * {
... return a value ...
}
/* Block unqualified typemaps defined above */
%typemap(ignore) const blah * "pass";
%typemap(argout) const blah * "pass";
%typemap(in) const blah * {
... get input value ...
}
(This potential applications of typemaps suggested by Greg Stein).
*** NEW FEATURE ***
01/29/2002: cheetah (william fulton)
[Java] Bug fix: No enumerations were wrapped when the -shadow
commandline option was not specified. Reported by Israel Taller.
01/28/2002: cheetah (william fulton)
[Java] Global arrays are successfully wrapped. In fact they started
mostly working in SWIG-1.3.10.
01/28/2002:richardp
Added first attempt at C++ and -shadow support for PHP4 module,
please test and mail me if any problems/ideas on improving it.
There is a known problem with uninitialized member variables,
please see Examples/php4/sync/README for details.
Also more PHP documentation added to Doc/Manual/Php.html
01/27/2002:beazley
The ANSI C size_t type is now recognized as an integer by default.
01/26/2002:beazley
long long and unsigned long long support added to many language modules.
This is not a portable feature and will require compiler support
for the long long type. In target languages that do not support
long long (e.g., Tcl and Perl), numbers are converted to a string
of digits. This prevents their use in arithmetic calculations, but
still allows values to be set from a string.
long long support requires the use of the strtoll() and strtoull()
functions as well as the 'lld' and 'llu' format specifiers
of sprintf().
01/26/2002:beazley
Fixed [ #501827 ] Delete method is not called. The Tcl
module wasn't correctly calling destructors when they
were defined using %addmethods. This has been fixed.
Reported by Reinhard Fobbe.
01/26/2002: beazley
Better support for long long and unsigned long long. Typemaps
have been included in a number of modules for handling these types.
In addition, the parser has been modified to accept long long
literals such as 1234LL and 1234ULL.
01/27/2002: cheetah (william fulton)
[Java] A C char[] is mapped to a Java String which is the default
SWIG handling of char[] and char*. It used to be mapped to byte[].
Note that a C signed char[] array is mapped to byte[].
*** POTENTIAL INCOMPATIBILITY ***
01/25/2002: beazley
Fixed a problem with return-by-value, C++, and
objects that define no default constructor.
Reported by Joel Reed.
01/25/2002: cheetah (william fulton)
[Java] Overhaul of the Java module. The C code generation is now
done from typemaps.
01/24/2002: cheetah (william fulton)
[Java] Support for arrays of enum pointers
01/20/2002: cheetah (william fulton)
[Java] Error checking for null Java objects being passed to native
functions. Exception thrown now whereas before the JVM crashed.
01/18/2002: cheetah (william fulton)
[Java] Corrected behaviour for functions that take arrays. For
example, when this c function:
void arrayfn(int array[]);
is wrapped the corresponding native function
public final static native void arrayfn(int[] array);
is produced. Previously if the C function made any changes to the
array elements, these were not reflected back into the Java array.
This has now been corrected so that the changes are propogated back
to Java and the calling function will see these changes. This is
how pure Java functions work, ie arrays are passed by reference.
01/15/2002:mkoeppe
[Guile] New file cplusplus.i with C++ typemaps contributed
by Marcio Luis Teixeira <marciot@holly.colostate.edu>.
01/11/2002: cheetah (william fulton)
[Java] Changed mapping of C long to Java type. Was mapped to Java
long, now mapped to Java int. If you want the previous mapping to
Java long use this approach in your interface file:
%clear long;
%typemap(jni) long "jlong"
%typemap(jtype) long "long"
%typemap(jstype) long "long"
%clear long[ANY];
%typemap(jni) long[ANY] "jlongArray"
%typemap(jtype) long[ANY] "long[]"
%typemap(jstype) long[ANY] "long[]"
%typemap(in) long[ANY] {write me for array support}
%typemap(out) long[ANY] {write me for array support}
%typemap(argout) long[ANY] {write me for array support}
%typemap(freearg) long[ANY] {write me for array support}
*** POTENTIAL INCOMPATIBILITY ***
This new mapping is more appropriate when interfacing to 32 bit
applications which are used in the current 32-bit JVMs. For future
64-bit JVMs you may have to change these mappings - eg on Unix LP64
systems, but not on Microsoft 64bit Windows which will be using a
P64 IL32 model. This may be automated in a future version of SWIG.
01/10/2002:beazley
Fixed [ 501677 ] %init block in wrong place. Reported
by Luigi Ballabio.
01/09/2002: cheetah (william fulton)
[Java] Default support for the long long type. signed long long is
mapped to a Java long. unsigned long long is mapped to BigInteger.
01/09/2002:beazley
Experimental change to parser to better support mixing of
int, long, short, unsigned, float, and double. The parser
should now support types like this:
short unsigned int
int unsigned short
unsigned short int
unsigned int short
This change also enables a type of 'long double' (previously
unsupported) to be used.
*** NEW FEATURE ***
01/05/2002: cheetah (william fulton)
[Java] Casting fix for when function return type is a pointer as
reported by Gary Pennington 2002-01-05. The upper 32bits of the
64 bit jlong will have contained junk for 32bit pointers.
01/05/2002: cheetah (william fulton)
[Java] Better pointer handling in Java is possible as the
INPUT, OUTPUT and INOUT typemaps have been added into typemaps.i.
01/05/2002: cheetah (william fulton)
[Java] $null can be used in input typemaps to return early from JNI
functions that have either void or a non-void return type. Example:
%typemap(check) int * %{
if (error) {
SWIG_exception(SWIG_IndexError, "Array element error");
return $null;
}
%}
If the typemap gets put into a function with void as return, $null
will expand to nothing:
void jni_fn(...) {
if (error) {
SWIG_exception(SWIG_IndexError, "Array element error");
return ;
}
...
}
otherwise $null expands to zero, where javareturntype is either a
pointer or a primitive type:
javareturntype jni_fn(...) {
if (error) {
SWIG_exception(SWIG_IndexError, "Array element error");
return 0;
}
...
}
01/02/2002: cheetah (william fulton)
[Java] The Java module incorrectly used argout typemaps for
strings. This is now corrected and the code now resides
in the freearg typemap. The argout array typemaps have been split into
argout and freearg typemaps. This correction may require some user
written typemaps to be modified.
*** POTENTIAL INCOMPATIBILITY ***
12/28/2001: cheetah (william fulton)
[Java] Multi typemaps now working for Java see multimap example.
[Java] Fix for recently introduced bug - freearg typemap code was appearing
before the function call.
12/28/2001: cheetah (william fulton)
[Java] JCALL macro for JNI calls that work in both C and C++ typemaps
have been replaced with JCALL0, JCALL1, JCALL2, JCALL3 and JCALL4
macros.
*** POTENTIAL INCOMPATIBILITY ***
12/22/2001:beazley
Resolved some inconsistent behavior with %rename and class renaming.
If you specify the following:
%rename(Foo) Bar;
class Bar {
public:
Bar();
~Bar();
}
Then the %rename directive applies to the class itself, the constructor,
and the destructor (all will be renamed to Foo).
If a class defines more than one constructor, the overloaded variants
can still be renamed by specifying parameters to %rename. For example:
%rename(Bar_copy) Bar(Bar &);
class Bar {
public:
Bar();
Bar(Bar &);
~Bar();
};
There are still some odd corner cases. If you specify
%rename(Foo) ::Bar;
then only the name of the class is changed and the constructor/destructor
names are left unmodified. If you specify
%rename(Foo) *::Bar;
then the names of the constructor/destructor functions are modified but
the name of the class is not.
12/21/2001: cheetah (william fulton)
[Java] jni, jtype and jstype typemaps no longer hardcoded but real
typemaps. New variable substitution, $javaclassname, can be used in
the jstype typemaps. It is replaced with the Java shadow class name
where applicable.
[Java] Fix for recently introduced bug to do with inheritance when
using %import.
[Java] A few more bug fixes, todo with %rename and using the kind
with the type, eg
void fn(union uni myuni, struct str mystr, class cl mycl);
12/20/2001:beazley
Fixed [ #494524 ] Preprocessor bug - apostrophe and #subst.
12/20/2001:beazley
Added SWIG_VERSION preprocessor symbol. This is a hexadecimal
integer such as 0x010311 (corresponding to SWIG-1.3.11). This can
be used in the interface as follows:
#if SWIG_VERSION >= 0x010311
/* Use some fancy new feature */
#endif
Note: The version symbol is not defined in the generated SWIG
wrapper file.
*** NEW FEATURE ***
12/20/2001:mkoeppe
[MzScheme]: Renamed mzswig_make_boolean to
swig_make_boolean, as the latter is used in the typemaps.
Reported by Luigi Ballabio.
12/17/2001:mkoeppe
[Guile]: Rewrote list-vector.i using multi-dispatch
typemaps. Updated pointer-in-out.i. Make the
deprecated typemap-substitution of "$source" in "argout"
work as before.
12/16/2001:mkoeppe
[Guile]: Fixed macros %values_as_list, %values_as_vector,
%multiple_values to use the proper %pragma syntax. New
Guile example/test "multivalue"; new Guile run-test for
test-suite item "list-vector" (currently broken).
12/14/2001:mkoeppe
[Guile]: Fixed typemap-substition bug for "varin". Relaxed
valid-identifier check to allow all R5RS identifiers.
Version 1.3.10 (December 10, 2001)
==================================
12/08/2001:beazley
Modified %typemap so that %{ ... %} can also be used as a
code block (mostly for completeness). For example:
%typemap(in) blah %{
...
%}
This form does not introduce a new block scope. Also, the
code enclosed in %{ ... %} is not processed by the preprocessor.
12/08/2001:beazley
Fixed [ #459614 ] SWIG with multiple TCL interpreters.
12/08/2001:beazley
Fixed [ #417141 ] rubydec.swg is wrong
Reported by Paul Brannan.
12/08/2001:beazley
Fixed [ #410557 ] Problem with %addmethods on NT.
Reported by Magnus Ljung.
12/08/2001:beazley
Fixed [ #445233 ] Enhancement: handle access change.
SWIG now parses (but ignores) C++ access changes for the
the following:
class A {
protected:
void something() { }
public:
A() {}
};
class B : private A {
public:
B() : A() { }
protected:
A::something; <---- Parsed, but ignored
};
Suggested by Krzysztof Kozminski.
12/08/2001: cheetah (william fulton)
Fix for Ruby to work using Visual C++.
12/06/2001:beazley
Fixed [ #465687 ] unsigned short parameters fail.
Reported by Gerald Williams.
12/06/2001:beazley
Fixed SF [ #489594 ] PyString_FromString can't take NULL arg.
Reported by John Merritt. SWIG now converts string values
to Python using code like this:
resultobj = result ? PyString_FromString(result) : Py_BuildValue("");
12/06/2001:beazley
Fixed SF [ #463561 ] Type conversions not generated.
Reported by Gerald Williams.
12/04/2001:beazley
Fixed SF [ #470217 ] Tcl default argument handling.
Reported by Shaun Lowry.
12/04/2001:beazley
Fixed SF [ #472088 ] defined(MACRO) expanded everywhere.
Embedded preprocessor directives such as
%#if defined(FOO)
are not expanded by the SWIG preprocessor.
Reported by Gerald Williams.
12/04/2001:beazley
Fixed SF [ #476467 ] Problems with #define & commas.
12/04/2001:beazley
Fixed SF [ #477547 ] wrong declaration of pointer functions.
Bad prototypes in Lib/tcl/ptrlang.i.
12/04/2001:beazley
Fixed SF [ #483182 ] Constants can take args by mistake.
When swig -perl5 -const is used, constants are declared
with a void prototype. For example:
sub ICONST () { $examplec::ICONST }
Patch submitted by Rich Wales.
12/03/2001:beazley
New %exception directive. This is intended to replace %except.
It works in exactly the same manner except it does not accept a
language specifier. For example:
%exception {
try {
$action
}
catch(SomeError) {
error
}
}
%exception is also name aware---allowing it to be applied to
specific declarations in an interface. For example:
%exception foo {
...
exception for any function/method foo
...
}
%exception Foo::bar {
...
exception for method bar in class Foo
...
}
%exception Foo::bar(double) {
...
exception for method bar(double) in class Foo
...
}
The semantics of this name matching is exactly the same as for %rename.
*** NEW FEATURE ***
12/03/2001:beazley
Substantial cleanup of the Python shadow class code. Shadow classes
used to be created in this rather complicated manner involving about
a half-dozen strings created in bits and pieces. Shadow classes
are now generated in a more straightforward manner--in the same
order that appears in the interface file.
*** POTENTIAL INCOMPATIBILITY ***
The order in which declarations appear in the shadow file may differ.
12/03/2001:beazley
The %insert directive (%{ ... %}, %runtime, %header, %wrapper, etc.)
can now be used inside of a class definition. This has potential
uses when generating shadow class code. For example:
class Foo {
...
%insert("shadow") %{
# Some python code
def blah(self):
print "I'm blah!"
%}
...
};
The support for class code insertion depends on the language module.
However, the intent of this feature is to simplify the task of extending
shadow class code. In the Python module, this inserts code with the
proper level of indendation (regardless of what was used in the SWIG
interface).
*** NEW FEATURE ***
11/29/2001: cheetah (william fulton)
Modifications for Java and Python modules to work on cygwin.
Unfortunately a lot of the python module has started to produces code
which cannot be auto-imported using cygwin libtools so most of it is
still broken.
11/28/2001:beazley
The %rename and %feature directive can now be used inside
of a class definition. For example:
class Foo {
%rename(foo_i) foo(int);
%rename(foo_d) foo(double);
public:
...
void foo(int);
void foo(double);
...
};
When used in this manner, the %rename directive only applies
to members of the class in which it appears as well as all
derived classes. In fact, this is really just the same
as saying:
%rename(foo_i) Foo::foo(int);
%rename(foo_d) Foo::foo(double);
class Foo {
...
};
*** NEW FEATURE ***
11/26/2001:beazley
Added the experimental %feature directive. %feature can be
used to attach arbitrary string attributes to parse tree nodes.
For example:
%feature("except") blah {
try {
$function
} catch (Error) {
whatever;
}
}
or
%feature("set") *::x_set "x";
or
%feature("blah") Foo::bar(int,double) const "spam";
The syntax is borrowed from the %rename directive. In fact, the
exact same semantics apply (inheritance, matching, etc.).
%feature is a very powerful low-level primitive that can be used to
customize individual language modules and to provide hints to
any stage of code generation. Features are attached to
parse tree nodes as attributes with names like "feature:*" where *
is replaced by the feature name (e.g., "feature:except", "feature:set",
etc.). Language modules can then look for the features using
a simple attribute lookup.
%feature is intended to be a replacement for a number of
older SWIG directives including %except and specialized
pragmas. It is more powerful (due to its parameterized
name matching) and it provides very precise control over
how customization features are attached to individual
declarations. There are future expansion plans that will
build upon this capability as well.
It's not certain that %feature will ever be used directly
by SWIG users. Instead, it may be a low-level primitive
that is used in high-level macro definitions. For instance,
to support properties, you might define a macro like this:
%define %property(name, setf, getf)
%feature("set") setf #name;
%feature("get") getf #name;
%enddef
Which allows a user to specify things like this:
%property(p, get_p, set_p);
class Blah {
public:
int get_p();
void set_p(int);
};
*** EXPERIMENTAL NEW FEATURE ***
11/24/2001:beazley
The Tcl module has been expanded with some new features for
managing object ownership. For example:
set c [Circle -args 20]
$c area # Invoke a method
$c -disown # Releases ownership of the object
$c -acquire # Acquires ownership of the object
If Tcl owns the object, its destructor is invoked when the
corresponding object command is deleted in Tcl.
To simplify the destruction of objects, the following syntax
can be used:
$c -delete # Delete an object
This is an alternative for the more obscure variant of
rename $c {}
These features also add functionality at the C API level.
The following functions manage ownership from C and
can be used in typemaps.
SWIG_Acquire(void *ptr);
SWIG_Disown(void *ptr);
A new function for constructing instances is also available:
Tcl_Obj *
SWIG_NewInstanceObj(Tcl_Interp *interp, void *ptr,
swig_type_info *type, int own);
When used in a typemap, this creates a pointer object and
an interpreter command that can be used to issue methods and
access attributes as shown above.
*** NEW FEATURE ***
11/23/2001:beazley
All Python-related %pragma operations have been eliminated.
Most of these were written for older SWIG versions in order to
compensate for limitations in earlier releases. In an effort
to reduce the amount of code-clutter and potential for errors,
it is easier to simply eliminate the pragmas and to start over
(if needed). To be honest, I'm not even sure the pragmas
worked in 1.3.9 and recent releases.
Note: If you need to insert code into the shadow class file
created by SWIG, simply use the %shadow directive like this:
%shadow %{
def some_python_code():
print "blah!"
%}
*** POTENTIAL INCOMPATIBILITY ***
11/22/2001:beazley
Sweeping changes to the way in which the Python module handles
shadow classes. In early implementations, shadow classes were
merely Python wrappers around typed pointer objects. However,
some users actually wanted to receive the shadow class object in C.
To accomodate this, the dereferencing of the "this" pointer in
a shadow class was moved to C as described in CHANGES [8/8/99].
However, the process of returning pointers to Python was still
somewhat problematic. Specifically, shadow classes never worked
in situations such as these:
- Use of any kind of output typemap ('out' or 'argout')
- Global variables (broken as far as I can tell).
In the past, some users have dealt with this by manually trying
to create shadow class objects themselves from C/C++. However,
this was difficult because the C wrappers don't really know how
to get access to the corresponding Python class.
The Python module has now been modified to automatically attach
shadow class objects to pointers when they are returned to
Python. This process occurs in the function SWIG_NewPointerObj()
so the process is completely transparent to users. As a result,
shadow classes are now more seamlessly integrated with typemaps
and other features of SWIG.
This change may introduce a number of incompatibilities. The
SWIG_NewPointerObj() now takes an extra parameter "own" to
indicate object ownership. This can be used to return a pointer
to Python that Python should destroy. In addition, older code
that tries to manually construct shadow class objects or which
expects bare pointers may break---such pointers may already be
encapsulated by a shadow class.
*** POTENTIAL INCOMPATIBILITY ***
11/20/2001:beazley
Modified the %insert directive to accept single braces { ... }.
For example:
%insert("header") {
... some code ...
}
This works exactly like %{ ... %} except that the code in the
braces is processed using the preprocessor. This can be useful
in certain contexts such as low-level code generation in
language modules.
*** NEW FEATURE ***
11/20/2001:beazley
Command line options are now translated into preprocessor
symbols. For example:
./swig -python -shadow -module blah interface.i
Creates the symbols:
SWIGOPT_PYTHON 1
SWIGOPT_SHADOW 1
SWIGOPT_MODULE blah
Modules can look for these symbols to alter their code generation
if needed.
*** NEW FEATURE ***
11/20/2001:beazley
Massive overhaul of the Perl5 module. A lot of code generation is
now driven by tables and typemaps. The generated wrapper code
also makes use of tables to install constants, variables, and
functions instead of inlining a bunch of procedure calls. The
separate variable initialization function is gone. Most
code generation is controlled via the perl5.swg file in the
library.
*** POTENTIAL INCOMPATIBILITY ***
11/13/2001:beazley
Added parsing support for the C++ typename keyword. Primarily this
is added to better support templates. For example:
template<typename T> void blah(C& v) {
typename C::iterator i = v.begin();
}
Note: typename is supported in the parser in the same way as 'struct'
or 'class'. You probably shouldn't use it anywhere except in templates.
*** NEW FEATURE ***
11/11/2001:beazley
Massive overhaul of the language module API. Most functions now
use a common, very simple, API. There are also a number of
interesting semantic side-effects of how code is actually generated.
Details will be forthcoming in Doc/Manual/Extending.html.
*** POTENTIAL INCOMPATIBILITY *** Language modules written for
previous versions of SWIG will no longer work,
11/10/2001:beazley
Fixed a very subtle bug due to unnamed class wrapping. For example, if
you did this
typedef struct {
int x,y;
} gdPoint, *gdPointPtr;
void foo(gdPointPtr x);
Then the foo function would get a type-error. The problem has
to do with internal typedef handling and the fact that the typedef
declarations after the struct appear later in the parse tree.
It should work now. Problem reported by Vin Jovanovic.
11/09/2001:beazley
Subtle change to "out" typemaps (and related variations). The name
that is attached to the typemap is now the raw C identifier that
appears on a declaration. This changes the behavior of
member functions. For example:
%typemap(out) int foo {
...
}
class Blah {
public:
int foo(); // typemap gets applied
}
Previous versions never really specified how this was supposed to
work. In SWIG1.1, you could probably write a typemap for the
wrapper name like this:
%typemap(out) int Blah_foo { ... }
However, this old behavior is now withdrawn and not supported.
Just use the member name without any sort of special prefix.
*** POTENTIAL INCOMPATIBILITY ***
11/06/2001:beazley
Changes to Tcl module initialization:
(1) SWIG now automatically includes the code needed to work with
Tcl stubs. Simply compile with -DUSE_TCL_STUBS.
(2) SWIG now automatically calls Tcl_PkgProvide to register
a package name. The package name is the same as the name
specified with the %module directive. The version number is
set to "0.0" by default. To change the version number, use
swig -pkgversion 1.2 interface.i.
*** POTENTIAL INCOMPATIBILITY ***
Modules that provided stubs and Tcl_PkgProvide on their own might
break. Simply remove that code.
11/05/2001:beazley
Changed code generation of constants in the Tcl module. Constants
are now stored in a large table that get installed at module startup.
There are also no longer any static variables so it should generate
somewhat less code.
11/04/2001:beazley
The "const" typemap has been renamed to "constant" in many language
modules. "const" is a C keyword which made the handling of the typemap
directive somewhat awkward in the parser.
*** POTENTIAL INCOMPATIBILITY ***
11/04/2001:beazley
%typemap directive can now accept nearly arbitrary keyword parameters.
For example:
%typemap(in,parse="i",doc="integer") int "...";
The purpose of the keyword parameters is to supply code generation
hints to the target language module. The intepretation of the
parameters is language specific.
*** NEW FEATURE ***
11/04/2001:beazley
Slight semantic change to internal call/return by value handling.
In previous versions of SWIG, call-by-value was translated
into pointers. For example:
double dot_product(Vector a, Vector b);
turned into this:
double wrap_dot_product(Vector *a, Vector *b) {
return dot_product(*a,*b);
}
This translation was normally performed by the SWIG core, outside
of the control of language modules. However, a side effect
of this was a lot of bizarre typemap behavior. For example,
if you did something like this:
%typemap(in) int32 {
...
}
You would find that int32 was transformed into a pointer everywhere!
(needless to say, such behavior is unexpected and quite awkward to
deal with). To make matters worse, if a typedef was also used,
the pointer behavior suddenly disappeared.
To fix this, the pointer transformation is now pushed to the
language modules. This produces wrappers that look roughly
like this:
double wrap_dot_product(Vector *a, Vector *b) {
Vector arg1 = *a;
Vector arg2 = *b;
return dot_product(arg1,arg2);
}
This change also makes it easy to define typemaps for
arbitrary undefined types. For example, you can do this (and it
will work regardless what int32 is):
%typemap(in) int32 {
$1 = (int32) PyInt_AsLong($input);
}
*** POTENTIAL IMCOMPATIBILITY ***
This change may break call/return by value code generation in
some language modules.
11/03/2001:beazley
Changed the name of the default typemaps to the following:
%typemap() SWIGTYPE {
... an object ...
}
%typemap() SWIGTYPE * {
... a pointer ...
}
%typemap() SWIGTYPE & {
... a reference ...
}
%typemap() SWIGTYPE [] {
... an array ...
}
%typemap() enum SWIGTYPE {
... an enum value ...
}
%typemap() SWIGTYPE (CLASS::*) {
... pointer to member ...
}
These types are used as the default for all types that don't match
anything else. See CHANGES log entry for 8/27/2000 for the
old behavior. The role of these types is also described in
Doc/Manual/Typemaps.html
*** POTENTIAL INCOMPATIBILITY ***
10/25/2001:beazley
Modified Guile and Mzscheme modules to support
multi-argument typemaps.
10/25/2001: cheetah (william fulton)
[Java] Fix to handle pointers to arrays.
10/24/2001:beazley
Defining a typemap rule for enum SWIGENUM can now be used
to define default behavior for enum variables.
10/22/2001:beazley
Ruby module modified to support multi-argument typemaps.
10/22/2001:beazley
The Ruby module can now handle functions with an arbitrary
number of arguments. Previous versions were limited to
to functions with only 9 or 16 arguments depending on
the use of default arguments. Note: from some inspection
of the Ruby interpreter source, the new approach might be
a little faster as well.
10/18/2001:beazley
Fixed a bug with forward class declarations and
templates.
class Foo <S,T>;
Bug reported by Irina Kotlova.
10/16/2001:beazley
Support for multivalued typemaps added. The typemaps
are specified using the syntax below. Within each
typemap, variable substitution is handled as follows:
%typemap(in) (int argc, char *argv[]) {
$arg; // The input object in the target language
$1; // C local variable for first argument
$2; // C local variable for second argument
// These variables refer to either argument
$1_type, $1_ltype, $1_basetype, etc... (argc)
$2_type, $2_ltype, $2_basetype, etc... (argv[])
// Array dimension of argv
$2_dim0
}
Basically any variable that was available in normal typemaps
is available for either argument by prefacing the variable
name by '$n_' where n is the argument position.
Notes:
(1) Multi-valued typemaps can only be applied to a single
object in the target scripting language. For example,
you can split a string into a (char *, int) pair or
split a list into a (int, char []) pair. It is not
possible to map multiple objects to multiple arguments.
(2) To maintain compatibility with older SWIG versions, the
variables such as $target and $type are preserved and
are mapped onto the first argument only.
(3) This should not affect compatibility with older code.
Multi-valued typemaps are an extension to typemap handling.
Single valued typemaps can be specified in the usual
way.
The old $source and $target variables are officially
deprecated. Input variables are referenced through
$arg$ and output values are reference through $result$.
*** NEW FEATURE ***
10/16/2001:beazley
Added parsing support for multivalued typemaps. The syntax
is a little funky, but here goes:
// Define a multivalued typemap
%typemap(in) (int argc, char *argv[]) {
... typemap code ...
}
// Multivalued typemap with locals
%typemap(in) (int argc, char *argv[])(int temp) {
... typemap code ...
}
// Copy a multivalued typemap
%typemap(in) (int argcount, char **argv) = (int argc, char *argv[]);
// Apply a multivalued typemap
%apply (int argc, char *argv[]) { (int argcount, char **argv) };
Note: this extra parsing support is added for future extension.
No language modules currently support multi-valued typemaps.
10/11/2001:beazley
Modified the typemap matching code to discard qualifiers when
checking for a match. For example, if you have a declaration
like this:
void blah(const char *x);
The typemap checker checks for a match in the following order:
const char *x
const char *
char *x
char *
If typedef's are involved, qualifier stripping occurs before
typedef resolution. So if you had this,
typedef char *string;
void blah(const string x);
typemap checking would be as follows:
const string x
const string
string x
string
const char *x
const char *
char *x
char *
The primary reason for this change is to simplify the implementation
of language modules. Without qualifier stripping, one has to write
seperate typemaps for all variations of const and volatile (which
is a pain).
*** POTENTIAL INCOMPATIBILITY *** Typemaps might be applied in
places where they weren't before.
10/9/2001: beazley
SWIG now generates wrappers that properly disambiguate
overloaded methods that only vary in constness. For
example:
class Foo {
...
void blah();
void blah() const;
...
};
To handle this, the %rename directive can be used normally.
%rename(blah_const) blah() const;
In the resulting wrapper code, method calls like this
are now generated:
(obj)->blah() // Non-const version
((Foo const *)obj)->blah() // const version
This should force the right method to be invoked.
Admittedly, this is probably obscure, but we might
as well get it right.
10/8/2001: beazley
The preprocessor now ignores '\r' in the input.
This should fix the following bug:
[ #468416 ] SWIG thinks macro defs are declarations?
10/8/2001: beazley
Added support for ||, &&, and ! in constants. This
fixes SF [ #468988 ] Logical ops break preprocessor.
However, at this time, constants using these operators
are not supported (the parser will issue a warning).
10/4/2001: beazley
Added -show_templates command line option. This makes
SWIG display the code it actually parses to generate
template wrappers. Mostly useful for debugging.
*** NEW FEATURE ***
10/4/2001: beazley
Change to semantics of %template directive. When
using %template, the template arguments are handled
as types by default. For example:
%template(vecint) vector<int>;
%template(vecdouble) vector<double>;
To specify a template argument that is *not* a type, you
need to use default-value syntax. For example:
%template(vecint) vector<int,int=50>;
%template(vecdouble) vector<int,size=100>;
In this case, the type name doesn't really matter--only
the default value (e.g., 50, 100) is used during
expansion. This differs from normal C++, but I couldn't
figure out a better way to do it in the parser. Might
implement an alternative later.
*** POTENTIAL INCOMPATIBILITY ***
10/4/2001: beazley
Major changes to template handling in order to provide
better integration with the C++ type-system. The main
problem is as follows:
Suppose you have a template like this:
template<class T> void blah(const T x) { stuff };
Now suppose, that you instantiate the template on a
type like this in SWIG:
%template(blahint) blah<int *>;
In C++, this is *supposed* to generate code like this:
void blah(int *const x) { stuff };
However, in SWIG-1.3.9, the template substitution gets it wrong
and produces
void blah(const int *x) { stuff };
(notice the bad placement of the 'const' qualifier).
To fix this, the SWIG parser now generates implicit typedefs
for template type arguments that produces code roughly
equivalent to doing this:
typedef int *__swigtmpl1;
%template(blahint) blah<__swigtmpl1>;
which generates code like this:
void blah(const __swigtmpl1 x) { stuff };
Since this is correct in both C++ and SWIG, it provides the right
semantics and allows everything to compile properly. However,
to clean up the generated code a little bit, the parser keeps
track of the template types and performs back-substitution to
the original type when building the parse tree. Thus, even
though the implicit typedef is used in the input and may appear
in the generated wrapper file (for proper compilation), the parse
tree will hide a lot of these details. For example:
void blah(const __swigtmpl1 x) { stuff };
will look like it was declared as follows (which is what
you want):
void blah(int *const x) { stuff }
The only place you are likely to notice the typedef hack
is in bodies of template functions. For example, if you
did this,
template<class T> class blah {
...
%addmethods {
void spam() {
T tempvalue;
...
}
}
}
you will find that 'T tempvalue' got expanded into some
strange typedef type. This *still* compiles correctly
so it's not a big deal (other than looking kind of ugly
in the wrapper file).
10/4/2001: beazley
Fixed some inheritance problems in Tcl Object interface.
10/1/2001: beazley
Tcl module has changed to use byte-backed pointer strings. This
implementation should be safe on 64-bit platforms. However,
the order in which digits appear in pointer values no longer
directly corresponds to the actual numerical value of a
pointer (on little-endian machines, pairs of digits appear
in reverse order).
10/1/2001: beazley
Perl5 module is now driven by a configuration file 'perl5.swg'
in the SWIG library.
10/1/2001: beazley
The perl5 module no longer tries to apply the "out" typemap
in code generated for magic variables. I'm surprised that
this ever worked at all (since all of the code that was there
was wrong anyways). Use the "varout" typemap to handle
global variables.
10/1/2001: beazley
Fixed a bug related to character array members of structures.
For example:
struct Foo {
char name[32];
};
SWIG is normally supposed to return a string, but this was
broken in 1.3.9. The reason it was broken was actually
due to a subtle new feature of typemaps. When a data member
is set to an array like this, the return type of the related
accessor function is actually set to an array. This means
that you can now write typemaps like this:
%typemap(python,out) char [ANY] {
$target = PyString_FromStringAndSize($source,$dim0);
}
This functionality can be used to replace the defunct
memberout typemap in a more elegant manner.
9/29/2001: beazley
Some further refinement of qualified C++ member functions.
For example:
class Foo {
...
void foo() const;
...
};
(i) The SWIG parser was extended slightly to allow 'volatile'
and combinations of 'const' and 'volatile' to be used. This
is probably rare, but technically legal. Only added for
completeness.
(ii) For the purposes of overloading, qualified and non-qualified
functions are different. Thus, when a class has methods like this:
void foo();
void foo() const;
Two distinct methods are declared. To deal with this, %rename
and similar directives have been extended to recognize const.
Thus, one can disambiguate the two functions like this:
%rename(fooconst) Foo::foo() const;
or simply ignore the const variant like this:
%ignore Foo::foo() const;
Note: SWIG currently has no way to actually invoke the const
member since the 'const' is discarded when generating wrappers
for objects.
9/27/2001: beazley
New directive. %namewarn can be used to issue warning
messages for certain declaration names. The name
matching is the same as for the %rename directive.
The intent of this directive is to issue warnings for
possible namespace conflicts. For example:
%namewarn("print is a python keyword") print;
The name matching algorithm is performed after a name
has been resolved using %rename. Therefore, a
declaration like this will not generate a warning:
%rename("Print") print;
...
void print(); /* No warning generated */
Since the warning mechanism follows %rename semantics, it is
also to issue warnings for specific classes or just for
certain member function names.
(Dave - I've been thinking about adding something like this
for quite some time. Just never got around to it)
*** NEW FEATURE ***
9/27/2001: beazley
Enhanced the %ignore directive so that warning messages
can be issued to users. This is done using %ignorewarn
like this:
%ignorewarn("operator new ignored") operator new;
The names and semantics of %ignorewarn is exactly the
same as %ignore. The primary purpose of this directive
is for module writers who want to ignore certain types
of declarations, but who also want to alert users about it.
A user might also use this for debugging (since messages
will appear whenever an ignored declaration appears).
*** NEW FEATURE ***
9/26/2001: beazley
Super-experimental support for overloaded operators.
This implementation consists of a few different parts.
(i) Operator names such as 'operator+' are now allowed
as valid declarator names. Thus the 'operator' syntax
can appear *anyplace* a normal declarator name was used
before. On the surface, this means that operators can
be parsed just like normal functions and methods.
However, it also means that operator names can be used
in many other SWIG directives like %rename. For example:
%rename(__add__) Complex::operator+(const Complex &);
(ii) Operators are wrapped *exactly* like normal functions
and methods. Internally, the operator name is used
directly meaning that the wrapper code might contain
statements like this:
arg0->operator*((Complex const &)*arg1);
This all seems to parse and compile correctly (at least
on my machine).
(iii) SWIG will no longer wrap a declaration if its symbol
table name contains illegal identifier characters. If
illegal characters are detected, you will see an error
like this:
Warning. Can't wrap operator* unless renamed to a valid identifier.
The only way to fix this is to use %rename or %name to bind
the operator to a nice name like "add" or something. Note:
the legal identifier characters are determined by the target
language.
There are certain issues with friend functions and operators.
Sometimes, friends are used to define mixed operators such
as adding a Complex and a double together. Currently, SWIG
ignores all friend declarations in a class. A global operator
declaration can probably be made to work, but you'll have to
rename it and it probably won't work very cleanly in the
target language since it's not a class member.
SWIG doesn't know how to handle operator specifications
sometimes used for automatic type conversion. For example:
class String {
...
operator const char*();
...
};
(this doesn't parse correctly and generates a syntax error).
Also: operators no longer show up as separate parse-tree
nodes (instead they are normal 'cdecl' nodes). I may
separate them as a special case later.
See Examples/python/operator for an example.
*** SUPER-EXPERIMENTAL NEW FEATURE ***
Version 1.3.9 (September 25, 2001)
==================================
9/25/2001: beazley
Fixed parsing problem with type declarations like
'char ** const'. SWIG parsed this correctly, but the
internal type was represented incorrectly (the pointers
and qualifiers were in the wrong order).
9/25/2001: beazley
Withdrew experimental feature (noted below) that was
causing serious parsing problems.
Version 1.3.8 (September 23, 2001)
==================================
9/23/2001: beazley
Included improved distutils setup.py file in the Tools
directory (look for the setup.py.tmpl file). Contributed by
Tony Seward.
9/23/2001: beazley
Included two new RPM spec files in the Tools directory. Contributed
by Tony Seward and Uwe Steinmann.
9/21/2001: beazley
Fixed SF Bug [ #463635 ] Perl5.swg does not compile in Visual C++
9/21/2001: beazley
Two new directives control the creation of default
constructors and destructors:
%nodefault
%makedefault
These replace %pragma nodefault and %pragma makedefault.
(old code will still work, but documentation will only
describe the new directives).
9/21/2001: beazley
Fixed SF Bug [ #462354 ] %import broken in 1.3.7.
9/20/2001: beazley
**** 9/25/2001: This feature is temporarily withdrawn due to some
parsing problems it has created.
Parser modified to ignore out-of-class constructor
and destructor declarations. For example:
inline Foo::Foo() :
Bar("foo")
{
}
inline Foo::~Foo() {
}
Suggested by Jason Stewart.
*** EXPERIMENTAL FEATURE ***
9/20/2001: beazley
Modified the parser to ignore forward template class
declarations. For example:
template <class V, long S> class MapIter;
Suggested by an email example from Irina Kotlova.
9/20/2001: beazley
Fixed problem with undeclared tcl_result variable in
the "out" typemap for Tcl. Reported by Shaun Lowry.
9/20/2001: beazley
Incorporated changes to make SWIG work with ActivePerl.
Contributed by Joel Reed.
9/20/2001: beazley
Slight change to the parsing of C++ constructor initializers.
For example:
class Foo : public Bar {
public:
Foo() : Bar(...) {...}
};
SWIG now discards the contents of the (...) regardless of
what might enclosed (even if syntactically wrong). SWIG
doesn't need this information and there is no reason to
needless add syntax rules to handle all of the possibilities
here.
9/20/2001: beazley
Change to typemaps for structure members. If you have a
structure like this:
struct Vector {
int *bar;
};
The member name 'bar' is now used in any accessor functions.
This allows the "in" typemap to be used when setting the value.
For example, this typemap
%typemap(python,in) int *bar {
...
}
now matches Vector::bar. It should be noted that this will also
match any function with an argument of "int *bar" (so you should
be careful).
*** NEW FEATURE. POTENTIAL INCOMPATIBILITY ***
9/20/2001: beazley
Fixed SF bug #462642 setting string values in structures
9/20/2001: beazley
Fixed SF bug #462398 problem with nested templates.
9/20/2001: beazley
Fixed SF bug #461626 problem with formatting and C++ comments.
9/20/2001: beazley
Fixed SF bug #462845 Wrong ownership of returned objects.
9/19/2001: beazley
Fixed SF bug #459367. Default constructors for classes
with pure virtual methods.
9/19/2001: beazley
Fixed problem with default arguments and class scope. For
example:
class Foo {
public:
enum bar { FOO, BAR };
void blah(bar b = FOO);
...
}
SWIG now correctly generates a default value of "Foo::FOO" for
the blah() method above. This used to work in 1.1, but was
broken in 1.3.7. Bug reported by Mike Romberg.
Version 1.3.7 (September 3, 2001)
==================================
9/02/2001: beazley
Added special %ignore directive to ignore declarations. This
feature works exactly like %rename. For example:
%ignore foo; // Ignore all declarations foo
%ignore ::foo; // Only ignore foo in global scope
%ignore Spam::foo; // Only ignore in class Spam
%ignore *::foo; // Ignore in all classes
%ignore can also be parameterized. For example:
%ignore foo(int);
%ignore ::foo(int);
%ignore Spam::foo(int);
%ignore *::foo(int);
*** NEW FEATURE ***
9/02/2001: cheetah (william fulton)
[Java] shadowcode pragma modified so that the code that is output
in the shadow file is placed relative to where it is placed in the
c/c++ code. This allows support for JavaDoc function comments.
9/01/2001: beazley
Fixed SF Patch [ #447791 ] Fix for python -interface option.
Submitted by Tarn Weisner Burton.
9/01/2001: beazley
SWIG no longer generates default constructors/destructors
for a class if it only defines a private/protected constructor
or destructor or if any one of its base classes only has
private constructors/destructors. This was reported in
SF Patch [ #444281 ] nonpublic/default/inhereted ctor/dtor
by Marcelo Matus.
9/01/2001: beazley
Added patch to Perl5 module that allows constants to be
wrapped as constants that don't require the leading $.
This feature is enabled using the -const option.
Patch contributed by Rich Wales.
*** NEW FEATURE ***
8/31/2001: beazley
Added parsing support for the 'volatile' type qualifier.
volatile doesn't mean anything to SWIG, but it is
needed to properly generate prototypes for declarations
that use it. It's also been added to make the SWIG type
system more complete.
*** NEW FEATURE ***
8/30/2001: beazley
Added support for parameterized %rename directive. *** This
new feature can be used to greatly simplify the task of
resolving overloaded methods and functions. ***
In prior versions of SWIG, the %rename directive was
used to consistently apply an identifier renaming. For
example, if you said this:
%rename foo bar;
Every occurrence of 'foo' would be renamed to 'bar'.
Although this works fine for resolving a conflict with a
target language reserved word, it is useless for
for dealing with overloaded methods. This is because
all methods are simply renamed to the same thing
(generating the same conflict as before).
Therefore, the only way to deal with overloaded methods
was to go through and individually rename them all using
%name. For example:
class Foo {
public:
virtual void bar(void);
%name(bar_i) virtual void bar(int);
...
};
To make matters worse, you had to do this for all
derived classes too.
class Spam : public Foo {
public:
virtual void bar(void);
%name(bar_i) virtual void bar(int);
...
};
Needless to say, this makes it extremely hard to resolve
overloading without a lot of work and makes it almost
impossible to use SWIG on raw C++ .h files.
To fix this, %rename now accepts parameter declarators.
The syntax has also been changed slightly. For example,
the following declaration renames all occurrences of 'bar(int)'
to 'bar_i', leaving any other occurrence of 'bar' alone.
%rename(bar_i) bar(int);
Using this feature, you can now selectively rename
certain declarations in advance. For example:
%rename(bar_i) bar(int);
%rename(bar_d) bar(double);
// Include raw C++ header
%include "header.h"
When %rename is used in this manner, all occurrence of bar(int)
are renamed wherever they might occur. More control is obtained
through explicit qualification. For example,
%rename(bar_i) ::bar(int);
only applies the renaming if bar(int) is defined in the global scope.
The declaration,
%rename(bar_i) Foo::bar(int);
applies the renaming if bar(int) is defined in a class Foo.
This latter form also supports inheritance. Therefore, if you
had a class like this:
class Spam : public Foo {
public:
void bar(int);
}
The Spam::bar(int) method would also be renamed (since Spam
is a subclass of Foo). This latter feature makes it easy
for SWIG to apply a consistent renaming across an entire
class hierarchy simply by specifying renaming rules for
the base class.
A class wildcard of * can be used if you want to renaming
all matching members of all classes. For example:
%rename(bar_i) *::bar(int);
will rename all members bar(int) that are defined in classes.
It will not renamed definitions of bar(int) in the global
scope.
The old use of %rename is still supported, but is somewhat
enhanced.
%rename(foo) bar; // Renames all occurrences of 'bar'.
%rename(foo) ::bar; // Rename all 'bar' in global scope only.
%rename(foo) *::bar; // Rename all 'bar' in classes only.
%rename(foo) Foo::bar; // Rename all 'bar' defined in class Foo.
*** NEW FEATURE ***
8/30/2001: beazley
Added support for data-member to member-function
transformation. For example, suppose you had a
structure like this:
struct Vector {
double x,y;
};
Now suppose that you wanted to access x and y
through a member function interface instead
of the usual SWIG behavior. For example:
f.set_x(3.4) # instead of f.x = 3.4
x = f.get_x() # instead of x = f.x
To do this, simply use the new %attributefunc
directive. For example:
%attributefunc(get_%s,set_%s)
struct Vector {
double x,y;
};
%noattributefunc
The arguments to %attributefunc are C-style printf
format strings that determine the naming convention
to use. %s is replaced with the actual name of the
data member. SWIG provides a number of printf
extensions that might help. For example, if you
wanted to title case all of the attributes, you
could do this:
%attributefunc(get%(title)s,set%(title)s);
This will turn an attribute 'bar' to 'getBar()' and 'setBar()'.
(someone requested this long ago, but I finally figured
how to implement it in a straightforward manner).
*** EXPERIMENTAL NEW FEATURE ***
8/30/2001: beazley
SWIG now automatically generates default constructors
and destructors if none are defined. This used to be
enabled with a command line switch -make_default, but
most people want these functions anyways. To turn
off this behavior use the -no_default option or include
the following pragma in the interface file:
%pragma no_default;
This may break certain interfaces that defined their
own constructors/destructors using the same naming
convention as SWIG. If so, you will get duplicate
symbols when compiling the SWIG wrapper file.
*** POTENTIAL INCOMPATIBILITY ***
8/29/2001: beazley
Changes to Perl5 shadow class code generation. Iterators
are no longer supported (FIRSTKEY, NEXTKEY). Also, attribute
access has been changed to rely on inheritance in order
to provide better behavior across modules.
8/28/2001: beazley
Various obscure improvements to the type system and classes.
Strange declarations like this are now wrapped correctly
(i.e., the generated wrapper code doesn't cause the C++
compiler to die with a type error).
class Foo {
public:
typedef double Real;
Real foo(Real (*op)(Real,Real), Real x, Real y);
};
Inheritance of types is also handled correctly.
8/28/2001: beazley
Changes to class wrappers. When SWIG sees two classes like this,
class X {
public:
void foo();
...
}
class Y : public X {
public:
void bar();
...
}
it now only generates two wrapper functions:
X_foo(X *x) { x->foo(); }
Y_bar(Y *y) { y->bar(); }
Unlike SWIG1.15, the foo() method does *not* propagate to a wrapper
function Y_foo(). Instead, the base class method X_foo() must be
used.
This change should not affect modules that use shadow classes, but
it might break modules that directly use the low-level C wrappers.
This change is being made for a number of reasons:
- It greatly simplifies the implementation of SWIG--especially
with anticipated future changes such as overloaded methods.
- It results in substantially less wrapper code--especially
for big C++ class hierarchies (inherited declarations
are no longer copied into every single derived class).
- It allows for better code generation across multiple
SWIG generated modules (code isn't replicated in
every single module).
*** POTENTIAL INCOMPATIBILITY ***
8/22/2001: cheetah (william fulton)
Provided some Windows documentation in the Win directory and some
Visual C++ project files for running examples on Windows.
8/28/2001: mkoeppe
[Guile] Handle renamed overloaded functions properly;
thanks to Marc Zonzon <Marc.Zonzon@univ-rennes1.fr> for the
patch. See the new test case name_cxx.
8/27/2001: mkoeppe
[Tcl] Removed lots of warnings issued by the Sun Forte
compilers, which were caused by mixing function pointers
of different linkages (C++/C).
8/23/2001: mkoeppe
Improved the MzScheme module by porting Guile's pointer
type checking system and making type dispatch
typemap-driven.
8/22/2001: beazley
Entirely new symbol table processing. SWIG should be able to
report much better error messages for multiple declarations.
Also, the new symbol table allows for overloaded functions
(although overloading isn't quite supported in the language
modules yet).
8/22/2001: cheetah (william fulton)
* [Java] %new support added.
* [Java] Package JNI name refixed!
8/19/2001: beazley
Python module modified to support pointers to C++ members. This
is an experimental feature.
*** NEW FEATURE ***
8/19/2001: beazley
Added limited parsing and full type-system support for pointers to
members. None of SWIG's language modules really know how to deal with
this so this is really only provided for completeness and future
expansion. Note: SWIG does not support pointers to members which
are themselves pointers to members, references to pointers to members,
or other complicated declarations like this.
*** NEW FEATURE ***
8/19/2001: beazley
SWIG is much better at parsing certain C++ declarations. Operators and
friends generally don't cause anymore syntax errors. However, neither
are really supported.
8/18/2001: beazley
Added *highly* experimental support for wrapping of C++
template declarations. Since C++ templates are essentially
glorified macros and SWIG has a fully operational C
preprocessor with macro support, the parser now converts
template declarations to macros. For example, a function
template like this
template<class T> T max(T a, T b);
is internally converted into a macro like this:
%define %_template_max(__name,T)
%name(__name) T max(T a, T b);
%enddef
To instantiate a version of the template, a special %template declaration
is used like this:
%template(maxint) max<int>;
%template(maxdouble) max<double>;
The parameter to the %template directive must be proper C identifier that's
used to uniquely name the resulting instantiation. When used, the
the expanded macro looks like this:
%name(maxint) int max(int a, int b);
%name(maxdouble) double max(double a, double b);
A similar technique is used for template classes. For instance:
template<class T> class vector {
T *data;
int sz;
public:
vector(int nitems);
T *get(int n);
...
};
Gets converted into a macro like this:
%define %_template_vector(__name, T)
%{
typedef vector<T> __name;
%}
class __name {
T *data;
int sz;
public:
__name(int nitems);
T *get(int n);
...
};
typedef __name vector<T>;
%enddef
An a specific instantiation is created in exactly the same way:
%template(intvec) vector<int>;
The resulting code parsed by SWIG is then:
%{
typedef vector<int> intvec;
%}
class intvec {
int *data;
int sz;
public:
intvec(int nitems);
int *get(int n);
...
};
typedef intvec vector<int>;
Note: the last typedef is non-standard C and is used by SWIG to provide
an association between the name "intvec" and the template type
"vector<int>".
CAUTION: This is an experimental feature and the first time SWIG has
supported C++ templates. Error reporting is essential non-existent.
It will probably break in certain cases.
*** EXPERIMENTAL NEW FEATURE ****
8/15/2001: beazley
Change to wrapping of multi-dimensional arrays. Arrays
are now properly mapped to a pointer to an array of
one less dimension. For example:
int [10]; --> int *
int [10][20]; --> int (*)[20];
int [10][20][30]; --> int (*)[20][30];
This change may break certain SWIG extensions because
older versions simply mapped all arrays into a single
pointer such as "int *". Although possibly unusual,
the new version is correct in terms of the C type system.
*** POTENTIAL INCOMPATIBILITY ***
8/06/2001: cheetah (william fulton)
* [Java] Array setters generated for struct/class array members.
8/13/2001: beazley
Many improvements to Tcl/Perl/Python modules to better
work with multiple interface files and the %import directive.
8/13/2001: beazley
Fixed up the behavior of %import in the Python module.
SWIG no longer pollutes the module namespace by using
'from module import *' to refer to the other module.
Instead, it does a proper 'import module'. Also, SWIG
may work a lot better when importing modules that include
references to other imported modules.
8/13/2001: mkoeppe
Added new typemap substitutions, generalizing those of the
Guile-specific 5/27/2001 changes:
* $descriptor is the same as SWIGTYPE$mangle, but also
ensures that the type descriptor of this name gets
defined.
* $*type, $*ltype, $*mangle, $*descriptor are the same as
the variants without star, but they REMOVE one level of
pointers from the type. (This is only valid for pointer
types.)
* $&type, $<ype, $&mangle, $&descriptor are the same as
the variants without ampersand, but they ADD one level of
pointers to the type.
The Guile-specific substitution $basedescriptor was removed
because it was useless.
8/12/2001: beazley
The %extern directive is now deprecated and withdrawn. The
purpose of this directive was to import selected definitions
from other interface files and headers. However, the same
functionality is better handled through %import. This
leaves SWIG with two file inclusion directives:
%include filename - Inserts into current interface
%import filename - Import types and classes from
another module
*** POTENTIAL INCOMPATIBILITY ***
8/09/2001: beazley
Added new support for wrapping C/C++ callback functions.
A common problem with some C libraries is that many
functions take a function pointer as an argument. For example:
int do_op(..., int (*op)(int,int), ...);
Unfortunately, the only way to call such a function is to
pass it a function pointer of some compatible type. In
previous versions of SWIG, you had to solve this problem
with some really gross hacks. For example, if you wanted to
use the following function as a callback,
int foo(int, int);
you had to install a pointer to it as a constant. For example:
%constant int (*FOO)(int,int) = foo;
or
const int (*FOO)(int,int) = foo;
or if you had a really old SWIG version:
typedef int (*OP_FUNC)(int,int);
int do_op(..., OP_FUNC, ...);
const OP_FUNC FOO = foo;
Now, you can do one of two things:
%constant int foo(int,int);
This creates a constant 'foo' of type int (*)(int,int).
Alternatively, you can do this:
%callback("%s")
int foo(int,int);
int bar(int,int);
%nocallback
In this case, the functions are installed as constants where
the name is defined by the format string given to %callback().
If the names generated by the format string differ from the
actual function name, both a function wrapper and a callback
constant are created. For example:
%callback("%(upper)s")
int foo(int,int);
int bar(int,int);
%nocallback
Creates two wrapper functions 'foo', 'bar' and additionally
creates two callback constants 'FOO', 'BAR'.
Note: SWIG still does not provide automatic support for
writing callback functions in the target language.
*** NEW FEATURE ***
8/06/2001: cheetah (william fulton)
* struct nesting fixes as per SF bug #447488.
8/03/2001: beazley
The %name directive now applies to constants created with
#define and %constant. However, most language modules
were never written to support this and will have to be
modified to make it work. Tcl, Python, and Perl modules
are working now.
*** NEW FEATURE ***
8/03/2001: beazley
Massive changes and simplification of C declaration parsing.
Although SWIG is still not a full C parser, its ability
to handle complex datatypes including pointers to functions
and pointers to arrays has been vastly improved.
8/03/2001: cheetah (william fulton)
* Distribution fixes: autoconf no longer needed to install SWIG.
8/02/2001: beazley
Removed two undocumented parsing features. SWIG no longer
supports out-of-class static function or variable
declarations. For example:
static int Foo::bar;
This feature may return if there is sufficient demand.
However, since SWIG is most often used with header files,
it is more likely for these definitions to be included
in the class definition.
*** POTENTIAL INCOMPATIBILITY ***
8/02/2001: cheetah (william fulton)
* Cleanup of the GIFPlot examples. Upgraded Java GIFPlot example.
8/01/2001: cheetah (william fulton)
* [Java] Efficiency changes: _cPtr used where possible rather than
getCPtr(). Bug fixes for inheritance - derived class sometimes
didn't delete the c memory when _delete() was called.
* [Java] Abstract c++ classes are wrapped with a java abstract shadow
class. Also a pure virtual function is mapped with an abstract method.
* The default output file has always been <module>_wrap.c. It is now
<module>_wrap.cxx if the -c++ commandline option is passed to swig.
This has been done as otherwise c++ code would appear in a c file.
*** POTENTIAL INCOMPATIBILITY ***
7/31/2001: beazley
Modified the %constant directive to be more C-like in syntax.
The syntax is now:
%constant NAME = VALUE;
%constant TYPE NAME = VALUE;
For example:
%constant Foo *Bar = &Spam;
A more subtle case is as follows:
%constant int (*FOO)(int,int) = blah;
*** POTENTIAL INCOMPATIBILITY *** Modules that were using
the %constant directive directly will need to be modified.
7/30/2001: beazley
Removed obscure and undocumented form of the %inline directive:
%inline int blah(int a, int b) {
...
}
*** POTENTIAL INCOMPATIBILITY ***
(note: this feature was never documented and is withdrawn)
7/30/2001: beazley
Removed support for functions with no explicitly declared
return type. For example:
foo(int);
In C, such functions were implicitly assumed to return an 'int'.
In C++, this is illegal. Either way, it's considered bad
style. Removing support for this in SWIG will simplify
certain issues in parsing.
*** POTENTIAL INCOMPATIBILITY ***
7/30/2001: mkoeppe
* Partial merge from the CVS trunk. The Source/DOH directory
and most of the Source/Swig directory is up-to-date now.
* [Guile] %scheme is now a macro for %insert("scheme").
New syntax: %scheme "FILENAME";
New syntax: %scheme %{ SCHEME-CODE %}
New macros %multiple_values, %values_as_list,
%values_as_vector.
7/29/2001: beazley
%readonly and %readwrite have been turned into SWIG pragmas.
%pragma(swig) readonly and %pragma(swig) readwrite. Macros
are used to provide backwards compatibility.
7/29/2001: beazley
Minor changes to %pragma directive. %pragma must always
be directed to a specific language. For example:
%pragma(swig) make_default;
%pragma(perl5) include = "blah.i";
Also extended the pragma directive to allow code blocks
%pragma(foo) code = %{
... some code ...
%}
*** POTENTIAL INCOMPATIBILITY ***
7/29/2001: beazley
Change to the way 'const' variables are wrapped. In
previous versions of SWIG, a 'const' variable was
wrapped as a constant. Now, 'const' variables are
wrapped as read-only variables. There are several
reasons for making this change, mostly pertaining to
subtle details of how 'const' actually works.
This will probably break old interfaces that used 'const'
to create constants. As a replacement, consider using this:
const int a = 4; ===> %constant(int) a = 4;
*** POTENTIAL INCOMPATIBILITY ***
7/29/2001: beazley
Reorganization and simplification of type parsing.
Types with 'const' should work correctly now.
7/29/2001: beazley
Most swig directives related to the documentation system
are now deprecated.
7/29/2001: beazley
Removed support for Objective-C in order to simplify
parser reconstruction. Will return if there is sufficient
demand.
*** POTENTIAL INCOMPATIBILITY ***
7/29/2001: beazley
Code inclusion has been modified in the parser. A common
directive %insert is now used for everything. This
inserts a file into the output:
%insert(header) "foo.swg"
This inserts some inline code into the output
%insert(header) %{
... some code ...
%}
There are five predefined targets for the insert directive:
"header" - Header section of wrapper file
"runtime" - Runtime section of wrapper file
"wrapper" - Wrapper section
"init" - Initialization function
"null" - Nothing. Discard.
The following directives are still supported, but are
now defined in terms of macros:
%{ ... %} -> %insert(header) %{ ... %}
%init %{ ... %} -> %insert(init) %{ ... %}
%wrapper %{ ... %} -> %insert(wrapper) %{ ... %}
%runtime %{ ... %} -> %insert(runtime) %{ ... %}
Language modules can define new named targets by using the
C API function Swig_register_filebyname() (see main.cxx).
For example, if you wanted to expose a shadow class file,
you could do this:
Swig_register_filebyname("shadow", f_shadow);
Then in the interface file:
%insert(shadow) %{ ... %}
Note: this change should not affect any old interfaces, but
does open up new possibilities for enhancements.
7/29/2001: beazley
SWIG now always includes a standard library file 'swig.swg'.
This file defines a large number of macro definitions
that define the behavior of various SWIG directives.
Previously, all SWIG directives were handled as special
cases in the parser. This made the parser a large
bloated mess. Now, the parser is stripped down to a few
simple directives and macros are used to handle everything else.
7/26/2001: cheetah (william fulton)
* Fixes for Sourceforge bug #444748 - new testcase cpp_static:
[TCL] Class with just static member variable/function fix
[Java] Fixed static variables support
[Ruby] Static variables workaround removed
7/27/2001: mkoeppe
* stype.c (SwigType_default): Strip qualifiers first. The
default type of "int * const" is now "SWIGPOINTER *".
* main.cxx: Define "__cplusplus" in SWIG's preprocessor if
in C++ mode.
* [Guile]: Added some support for arrays and C++
references, fixing the "constant_pointers" test case.
* Moved most tests from the old Guile-specific test-suite
to the new test-suite. Also moved perl5/pointer-cxx
example there.
7/26/2001: cheetah (william fulton)
* Test-suite added.
* Initial testcases: constant_pointers cpp_enum defines
sizeof_pointers unions virtual_destructor
* Make clean improvements.
7/24/2001: cheetah (william fulton)
* [Java] Underscores in the package name and/or module name
no longer give linking problems.
7/17/2001: cheetah (william fulton)
* More parser bug fixes for constant pointers
7/19/2001: mkoeppe
* [Guile] Aesthetic improvement in variable wrappers.
7/18/2001: beazley
* Fixed core-dump problem in pointer library when
freeing character arrays.
SF Bug [ #415837 ] pointer lib core dump
7/18/2001: beazley
* Fixed problem with default destructors and shadow
classes. SF bug #221128.
7/18/2001: beazley
* To provide better line-number tracking in interfaces
with lots of macros, special locator comments are
now generated by the SWIG preprocessor. For example:
/*@foo.i,42,BLAH@*/expanded macro/*@@*/
The first /*@...@*/ sequence sets the context
to point to the macro code. The /*@@*/ comment
terminates the context. The SWIG parser should
ignore all of the locator comments as should
the C compiler (should such comments end up
in generated wrapper code).
7/18/2001: mkoeppe
* The parser now handles severely constified types in
typemaps. This introduced a new shift/reduce conflict, but
only with a heuristic function-pointer catch-all rule.
* [Guile]: Added typemaps for severely constified types.
* Fixed the "template-whitespace" problem by canonicalizing
whitespace, especially around angle brackets and commas.
7/17/2001: mkoeppe
* [Guile]: A Scheme file is emitted if the -scmstub FILE.SCM
command-line option is used. The %scheme directive
(implemented as a macro for a pragma) allows to insert
arbitrary code here. In "simple" and "passive" linkage,
the file gets filled with define-module and export
declarations.
7/17/2001: cheetah (william fulton)
* Parser bug fix to support constant pointers, eg int* const ptr.
Fixed everywhere - variables, parameters, return types etc. Note that
when wrapping a constant pointer variable only the getter is generated.
7/17/2001: mkoeppe
* Fixed SF bug #441470 (#define X "//" would not be parsed,
see test-suite entry "preproc-1"), reported by T. W. Burton
<twburton@users.sf.net>.
* Changed the type of character constants to "char", rather
than "char *". Changed the individual language modules
to keep the old behaviour, except for the Guile module,
where it is desired to make them Scheme characters. This
fixes SF bug #231409, test-suite entry "char-constant".
* Applied patch for DOH/Doh/memory.c by Les Schaffer
<schaffer@optonline.net> (avoid required side effects in
assert).
7/17/2001: cheetah (william fulton)
* Bug fix in parser for virtual destructor with void as parameter
* Bug fix in parser #defines embedded within classes/structs/unions
Consequently %constant can now also be placed within a struct/class/union.
* Bug fix in parser to allow sizeof(*I_am_a_pointer) within a #define
7/16/2001: mkoeppe
* Added changes for the Macintosh contributed by Luigi
Ballabio <ballabio@mac.com>.
* Some "const" fixes in the code.
* [Guile]: Made the constant-wrapper functions much shorter.
7/13/2001: mkoeppe
* [Guile]: Some "const" fixes for Guile version 1.3.4.
* Handle anonymous arguments with default values and static
array members of classes. Both bugs reported by Annalisa Terracina
<annalisa.terracina@datamat.it>; see the files
Examples/guile/test-suite/static-array-member.i and
anonymous-arg.i.
Version 1.3.6 (July 9, 2001)
=============================
7/09/2001: cheetah (william fulton)
* GIFPlot examples: FOREGROUND and BACKGROUND definition missing
after TRANSPARENT #define fix in GIFPlot
7/03/2001: beazley
Fixed up the version numbers so that the release is known
as 1.3.6. All future releases should have a similar
version format.
7/02/2001: mkoeppe
* [Python]: Prevent the problem of self.thisown not being
defined if the C++ class constructor raised an exception.
Thanks to Luigi Ballabio <ballabio@mac.com>.
6/29/2001: mkoeppe
* More portability fixes; fixed "gcc -Wall" warnings.
6/29/2001: cheetah (william fulton)
* GIFPlot examples: TRANSPARENT #define multiple times on Solaris
(clashes with stream.h).
* Multiple definition bug fix for shadow classes. The perl and python
modules had workarounds which have been replaced with fixes in
the core. Many of the Language::cpp_xxxx functions now set a
flag which the derived classes can access through
is_multiple_definition() to see whether or not code should be
generated. The code below would have produced varying degrees
of incorrect shadow class code for the various modules:
class TestClass
{
public:
TestClass() {};
TestClass(int a) {};
~TestClass() {};
unsigned long xyz(short k) {};
unsigned long xyz(int n) {};
static void static_func() {};
static void static_func(int a) {};
};
void delete_TestClass(int a);
6/27/2001: mkoeppe
* [Perl] Another const-related portability fix.
6/26/2001: cheetah (william fulton)
* [Java] Added in cpp_pragma() support with a host of new pragmas - see
jswig.html. These are designed for better mixing of Java and c++. It
enables the user to specify pure Java classes as bases and/or interfaces
for the wrapped c/c++.
* [Java] Old pragmas renamed. Warning given for the moment if used.
*** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
6/25/2001: mkoeppe
* Incorporated more build changes contributed by Wyss Clemens
<WYS@helbling.ch> for swig/ruby on cygwin.
6/20/2001: cheetah (william fulton)
* Makefile mods so that 'make check' uses the swig options in the makefiles
* [Java] Removed Generating wrappers message
* [Java] NULL pointer bug fix
* [Java] Bug fix for Kaffe JVM
6/20/2001: mkoeppe
* SWIG_TypeQuery from common.swg now returns a
swig_type_info* rather than a void*. This fixes a problem
when using pointer.i and C++, as illustrated by the new
test-suite example perl5/pointer-cxx.
* Portability fixes (const char *).
* Incorporated build changes contributed by Wyss Clemens
<WYS@helbling.ch>, which make swig runnable on cygwin.
6/19/2001: cheetah (william fulton)
* [Java] Bug fix for SF bug #211144. This fix is a workaround
until fixed in the core.
6/19/2001: mkoeppe
* [Guile]: Portability fixes for use with the Sun Forte
compilers.
* [Tcl]: Portability fix (const char *).
* [Tcl]: Configure now first tries to find a tclConfig.sh
file in order to find the Tcl include directory, library
location and library name.
* [Python]: Added a few possible library locations.
6/18/2001: mkoeppe
* [Guile]: Don't call scm_c_export if nothing is to be
exported. Don't warn on %module if module has been set
already (this frequently occurs when %import is used).
6/16/2001: mkoeppe
* [Guile]: New "passive" linkage, which is appropriate for
multi-module extensions without Guile module magic.
6/15/2001: mkoeppe
* [Guile]: Fixed printing of smobs (space and angle were
missing).
* Properly generate type information for base classes
imported with the %import directive. Thanks to Marcelo
Matus <mmatus@acms.arizona.edu> for the report and the
patch; this closes SF bug #231619; see also
Examples/guile/test-suite/import*.
* [Guile]: Fix casting between class and base class; the
runtime type system had it the wrong way around; see
Examples/guile/test-suite/casts.i
* Make typemaps for SWIGPOINTER * with arg name take
precedence over those without arg name, to match normal
typemap precedence rules.
* Fixed the random-line-numbers problem reported as SF bug
#217310; thanks to Michael Scharf <scharf@users.sf.net>.
* [Guile]: Handle the %name and %rename directives.
* New syntax: %name and %rename now optionally take double
quotes around the scripting name. This is to allow scripting
names that aren't valid C identifiers.
6/14/2001: beazley
Made a minor change to the way files are loaded in
order to get file/line number reporting correct in
the preprocessor.
6/14/2001: mkoeppe
* The parser now understands the (non-standard) "long long"
types. It is up to the individual language modules to
provide typemaps if needed. Reported by Sam Steingold, SF
bug #429176.
* The parser now understands arguments like "const int *
const i". This fixes SF bug #215649.
* Fixed the Guile test-suite.
6/13/2001: mkoeppe
Partial merge from the CVS trunk at tag
"mkoeppe-merge-1". This covers the following changes:
| 01/16/01: ttn
| Wrote table of contents for Doc/engineering.html. Added section
| on CVS tagging conventions. Added copyright to other docs.
| 9/25/00 : beazley
| Modified the preprocessor so that macro names can start with a '%'.
| This may allow new SWIG "directives" to be defined as macros instead
| of having to be hard-coded into the parser.
|
| *** Also a yet-to-be-documented quoting mechanism with backquotes
| *** has been implemented?
6/13/2001: mkoeppe
* When configure does not find a language, don't use default
paths like /usr/local/include; this only causes build
problems.
* New directory: Examples/Guile/test-suite, where a few
bugs in 1.3a5 are demonstrated.
* Handle C++ methods that have both a "const" and a "throw"
directive (see Examples/Guile/test-suite/cplusplus-throw.i);
thanks to Scott B. Drummonds for the report and the fix.
* Handle C++ pointer-reference arguments (like "int *& arg")
(see Examples/Guile/test-suite/pointer-reference.i,
reported as SF bug #432224).
* [Ruby] Fixed typo in rubydec.swg; thanks to Lyle Johnson!
* Don't stop testing when one test fails.
* [Guile, MzScheme] Don't print "Generating wrappers...".
6/12/2001: mkoeppe
[Guile] VECTORLENINPUT and LISTLENINPUT now have separate
list length variables. TYPEMAP_POINTER_INPUT_OUTPUT
attaches argument documentation involving SCM_TYPE to the
standard pointer typemaps. INOUT is now an alias for BOTH.
6/12/2001: cheetah (william fulton)
Some Java documentation added.
[Java] Fixed bugs in import pragma and shadow pragma.
6/12/2001: mkoeppe
Fix declarations of SWIG_define_class
(Lib/ruby/rubydec.swg) and SWIG_TypeQuery
(Lib/common.swg). Thanks to Lyle Johnson
<ljohnson@resgen.com> for the patches.
6/11/2001: mkoeppe
[Guile] Use long instead of scm_bits_t; this makes the
generated wrapper code compatible with Guile 1.3.4
again. Thanks to Masaki Fukushima for pointing this out.
6/11/2001: cheetah (william fulton)
The generic INSTALL file from autoconf added. Few changes to README file.
6/11/2001: mkoeppe
Fixed typo in Makefile.in; thanks to Greg Troxel
<gdt@ir.bbn.com>.
6/08/2001: cheetah (william fulton)
make check works again. Examples/GIFPlot configure generated by
top level autoconf now.
6/08/2001: mkoeppe
Another build change: The new script autogen.sh runs
autoconf in the appropriate directories. The top-level
configure also configures in Examples/GIFPlot.
6/07/2001: mkoeppe
Made the Makefile work with non-GNU make again.
6/07/2001: cheetah (william fulton)
[Java] Class/struct members that are arrays of pointers to classes/structs -
Shadow class's get/set accessors now use Java classes instead of longs (pointers).
[Java] Shadow classes will now clean up memory if function return type
is a class/struct.
[Java] New example called reference based on the same example from other modules.
6/06/2001: mkoeppe
New configure option --with-release-suffix allows for
attaching a suffix to the swig binary and the swig runtime
libraries. Minor changes to the build system. "swig
-swiglib" works again. If invoked with the new option
"-ldflags", SWIG prints a line of linker flags needed to
link with the runtime library of the selected language
module.
6/06/2001: mkoeppe
[Guile] gswig_list_p is an int, not a SCM. This typo
caused warnings when compiling with a Guile configured with
strict C type checking. In INPUT and BOTH typemaps
generated by the SIMPLE_MAP macro, use the SCM_TO_C
function to convert from Guile to C (rather than C_TO_SCM).
Use scm_intprint to print pointers (rather than
sprintf). Allow using "-linkage" instead of "-Linkage".
6/05/2001: cheetah (william fulton)
[Java] Mods for using inherited c++ classes from Java
[Java] New example called class based on the same example from other modules
6/05/2001: cheetah (william fulton)
[Java] destructor (_delete()) was not aware of %name renaming
[Java] extends baseclass did not know about %name renaming
[Java] extends baseclass did extend even when the baseclass was not known to swig
[Java] sometimes enum-declarations occured before the Java class declaration
[Java] unrelated enum initialisations no longer appear in Java class
[Java] if module ends in '_' correct JNI names are now produced
6/04/2001: cheetah (william fulton)
[Java] Shadow class mods - Modified constructor replaces
newInstance(). _delete() now thread safe. getCPtr() replaces
_self. _selfClass() removed as now redundant.
*** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
[Java] Not all output java files had SWIG banner. New banner.
[Java] Shadow class finalizers are output by default: Command
line option -finalize deprecated and replaced with -nofinalize.
*** POTENTIAL INCOMPATIBILITY FOR JAVA MODULE ***
6/ 1/2001: mkoeppe
[Guile] Cast SCM_CAR() to scm_bits_t before shifting it.
This is required for compiling with a Guile configured with
strict C type checking.
6/ 1/2001: mkoeppe
Added configure option "--with-swiglibdir".
5/31/2001: mkoeppe
[Guile] Support multiple parallel lists or vectors in
the typemaps provided by list-vector.i. New typemaps file,
pointer-in-out.i.
5/25/2001: cheetah (william fulton)
[Java] HTML update for examples.
5/28/2001: mkoeppe
Minor changes to the build system. Added subdirectory for
Debian package control files.
5/28/2001: mkoeppe
[Guile] Build a runtime library, libswigguile.
5/28/2001: mkoeppe
[Guile] New typemap substitution $*descriptor. Use the {}
syntax, rather than the "" syntax for the standard
typemaps, in order to work around strange macro-expansion
behavior of the SWIG preprocessor. This introduces some
extra braces.
5/27/2001: mkoeppe
[Guile] Handle pointer types with typemaps, rather than
hard-coded. New typemap substitutions $descriptor,
$basedescriptor; see documentation. Some clean-up in the
variable/constants wrapper generator code. New convenience
macro SWIG_Guile_MustGetPtr, which allows getting pointers
from smobs in a functional style. New typemap file
"list-vector.i", providing macros that define typemaps for
converting between C arrays and Scheme lists and vectors.
5/25/2001: cheetah (william fulton)
[Java] STL string moved into its own typemap as it is c++ code and
it break any c code using the typemaps.i file.
- Fixes for wrappers around global variables - applies to primitive
types and user types (class/struct) and pointers to these.
- Structure member variables and class public member variables getters
and setters pass a pointer to the member as was in 1.3a3 and 1.1
(1.3a5 was passing by value)
- Parameters that were arrays and return types were incorrectly
being passed to create_function() as pointers.
- Fix for arrays of enums.
[Java] Updated java examples and added two more.
[Java] Java module updated from SWIG1.3a3 including code cleanup etc.
[Java] enum support added.
[Java] Array support implemented
[Java] Shadow classes improved - Java objects used rather than
longs holding the c pointer to the wrapped structure/c++class
5/22/2001: mkoeppe
[Guile] Fixed extern "C" declarations in C++ mode. Thanks
to Greg Troxel <gdt@ir.bbn.com>.
5/21/2001: mkoeppe
[Guile] New linkage "module" for creating Guile modules for
Guile versions >= 1.5.0.
4/18/2001: mkoeppe
[MzScheme] Added typemaps for passing through Scheme_Object
pointers.
4/9/2001 : mkoeppe
[MzScheme] Added typemaps for `bool'. Inclusion of headers
and support routines is now data-driven via mzscheme.i.
Headers come from the new file mzschemdec.swg. Don't abort
immediately when a type-handling error is reported. When
searching for typemaps for enums, fall back to using int,
like the Guile backend does. Support char constants. Emit
correct wrapper code for variables.
3/12/2001: mkoeppe
[Guile] Fixed typemaps for char **OUTPUT, char **BOTH.
3/2/2001 : mkoeppe
[Guile] Every wrapper function now gets a boolean variable
gswig_list_p which indicates whether multiple values are
present. The macros GUILE_APPEND_RESULT, GUILE_MAYBE_VALUES
and GUILE_MAYBE_VECTOR use this variable, rather than
checking whether the current return value is a list. This
allows for typemaps returning a list as a single value (a
list was erroneously converted into a vector or a
multiple-value object in this case).
3/1/2001 : mkoeppe
[Guile] Added support for returning multiple values as
vectors, or passing them to a muliple-value
continuation. By default, multiple values still get
returned as a list.
3/1/2001 : mkoeppe
[Guile] Added a "beforereturn" pragma. The value of this
pragma is inserted just before every return statement.
3/1/2001 : mkoeppe
[Guile] Added support for Guile 1.4.1 procedure
documentation formats, see internals.html.
2/26/2001: mkoeppe
[Guile] Made the wrapper code compile with C++ if the
"-c++" command-line switch is given. Thanks to
<monkeyiq@dingoblue.net.au>.
2/26/2001: mkoeppe
[Guile] Now two type tables, swig_types and
swig_types_initial, are used, as all other SWIG language
modules do. This removes the need for the tricky
construction used before that the broken Redhat 7.0 gcc
doesn't parse. Reported by <monkeyiq@dingoblue.net.au>.
2/26/2001: mkoeppe
[Guile] Fixed typemaps for char *OUTPUT, char *BOTH; a bad
free() would be emitted. Added typemap for SCM.
Version 1.3 Alpha 5
===================
9/19/00 : beazley
[Python] Python module generates more efficient code for
creating the return value of a wrapper function. Modification
suggested by Jon Travis.
9/19/00 : beazley
Library files specified with the -l option are now included at the
end of the interface file (reverting to the old behavior).
9/19/00 : beazley
Fixed some problems with enum handling. enums are now manipulated as
'int', but cast into the enum type when values are passed to the
corresponding C function.
9/19/00 : mkoeppe
[Guile] Removed "-with-smobs" command-line option, as this is the
default now. Added "-emit-setters" command-line option,
which turns on generating procedures-with-setters; see
internals.html.
9/18/00 : mkoeppe
Incorporated patch #101430, fixing bugs in the Guile module:
1. Some arguments were erroneously taken as *optional* arguments when
ignored arguments were present.
2. Guile 1.3.4 was not supported since functions introduced in Guile
1.4 were used.
3. Added handling of `const char *'.
9/17/00 : beazley
Fixed problem with failed assertion and large files.
9/17/00 : beazley
Fixed problem with the '%' character appearing in added methods
and function bodies. Preprocessor bug.
Version 1.3 Alpha 4 (September 4, 2000)
======================================
9/3/00 : ttn
Added instructions for maintainers in Examples/README on how
to make examples also be useful in the testing framework.
Also, "make check" now uses ./Lib by via env var `SWIG_LIB'.
This is overridable like so:
make chk-swiglib=/my/experimental/swig/Lib check
9/3/00 : beazley
Added $typemap variable to typemaps. This gets replaced with
a string indicating the typemap that is applied. Feature
request from rsalz.
9/3/00 : beazley
Experimental optimization to code generation for virtual
member functions. If you have two classes like this:
class A() {
virtual void foo();
}
class B() : public A {
virtual void foo();
}
Swig now will generate a single wrapper function for this
A_foo(A *a) {
a->foo();
}
and use it as the implementation of both A_foo() and B_foo().
This optimization only takes place if both methods are declared
as virtual and both take identical parameters.
*** EXPERIMENTAL FEATURE ***
9/3/00 : beazley
Restored the "memberin" typemap for setting structure members.
Unlike the old version, the new version is expanded inline in the
wrapper function allowing access to scripting language
internals (a sometimes requested feature). The "memberout" typemap
is gone. Use the "out" typemaps instead.
*** POTENTIAL INCOMPATIBILITY ***
9/3/00 : beazley
Attribute set methods no longer return the value of a member.
For example:
struct Foo {
int x;
...
}
now gets set as follows:
void Foo_x_set(Foo *f, int x) {
f->x = x;
}
In SWIG1.1 it used to be this:
int Foo_x_set(Foo *f, int x) {
return (f->x = x);
}
This has been changed due to the complexity created by trying
to do this with more exotic datatypes such as arrays. It also
complicates inlining and handling of the "memberin" typemap.
*** POTENTIAL INCOMPATIBILITY ***
9/2/00 : beazley
Removed the ptrcast() and ptrmap() functions from the
pointer.i library file. Old implementation is incompatible
with new type system.
*** POTENTIAL INCOMPATIBILITY ***
9/2/00 : beazley
New runtime function SWIG_TypeQuery(const char *name) added.
This function can be used to extract the type info structure
that is used for type-checking. It works with either the
nice C name or mangled version of a datatype. For example:
swig_type_info *ty = Swig_TypeQuery("int *");
swig_type_info *ty = Swig_TypeQuery("_p_int");
This is an advanced feature that has been added to support some
exotic extension modules that need to directly manipulate
scripting language objects.
*** NEW FEATURE ***
9/2/00 : beazley
New directive %types() added. This is used to
explicitly list datatypes that should be included in
the runtime type-checking code. Normally it is never
necessary to use this but sometimes advanced extensions
(such as the pointer.i library) may need to manually
add types to the type-checker.
*** NEW FEATURE ***
8/31/00 : beazley
Improved handling of string array variables. For example,
a global variable of the form "char name[64]" is automatically
managed as a 64 character string. Previously this didn't
work at all or required the use of a special typemap.
*** NEW FEATURE (Tcl, Perl, Python) ***
8/31/00 : ttn
Added Makefile target `check-c++-examples', which uses new
files under Examples/C++ contributed by Tal Shalif. Now "make
check" also does "make check-c++-examples". Also, expanded
actions in `check-gifplot-example' and `check-aliveness'.
8/30/00 : mkoeppe
Major clean-up in the Guile module. Added typemap-driven
documentation system. Changed to handle more than 10
args. Updated and extended examples.
*** NEW FEATURE ***
8/29/00 : beazley
Added new %insert directive that inserts the contents of a file
into a portion of the output wrapper file. This is only intended
for use by writers of language modules. Works as follows:
%insert(headers) "file.swg";
%insert(runtime) "file.swg";
%insert(wrappers) "file.swg";
%insert(init) "file.swg";
*** NEW FEATURE ***
8/29/00 : beazley
Added new %runtime directive which includes code into the runtime
portion of the wrapper code. For example:
%runtime %{
... some internal runtime code ...
%}
There is no practical reason for ordinary users to use this
feature (almost everything can be done using %{ ... %}
instead). However, writers of language modules may want to
use this in language configuration files.
*** NEW FEATURE ***
8/28/00 : beazley
Typemaps can now be specified using string literals like
this:
%typemap(in) int "$target = SvIV($source);";
When code is specified like this, it is *NOT* enclosed
inside a local scope (as with older typemap declarations).
Note: character escape sequences are interpreted in the
code string so if you want to include a quote or some
other special character, make sure you use a (\).
*** NEW FEATURE ***
8/27/00 : beazley
Typemaps have been modified to follow typedef declarations.
For example, if you have this:
typedef int Number;
%typemap(in) int {
... get an integer ...
}
void foo(Number a);
The typemap for 'int' will be applied to the argument 'Number a'.
Of course, if you specify a typemap for 'Number' it will take
precedence (nor will it ever be applied to an 'int').
*** POTENTIAL INCOMPATIBILITY ***
8/27/00 : beazley
Default typemap specification has changed. In older
versions of swig, you could do this:
%typemap(in) int SWIG_DEFAULT_TYPE {
...
}
To specify the default handling of a datatype. Now that
SWIG follows typedef declarations, this is unnecessary.
Simply specifying a typemap for 'int' will work for all
variations of integers that are typedef'd to 'int'.
Caveat, specifying the default behavior for pointers,
references, arrays, and user defined types is a little
different. This must be done as follows:
%typemap() SWIGPOINTER * {
... a pointer ...
}
%typemap() SWIGREFERENCE & {
... a reference ...
}
%typemap() SWIGARRAY [] {
... an array ...
}
%typemap() SWIGTYPE {
... a user-defined type (by value) ...
}
*** POTENTIAL INCOMPATIBILITY ***
8/15/00 : dustin
The file swig-1.3a1-1.spec has been added to the Tools directory.
It can be used to build a redhat package for SWIG, although it
will need to be updated for the next public release.
8/15/00 : beazley
Typemaps have been completely rewritten. Eventually they may be
replaced with something better, but for now they stay. However,
there are a number of a significant changes that may trip some
people up:
1. Typemap scoping is currently broken. Because of this, the
following code won't work.
%typemap(in) blah * {
...
}
class Foo {
...
int bar(blah *x);
}
%typemap(in) blah *; /* Clear typemap */
(this breaks because the code for the class Foo is actually
generated after the entire interface file has been processed).
This is only a temporary bug.
2. In SWIG1.1, the %apply directive worked by performing a
very complex type-aliasing procedure. From this point on,
%apply is simply a generalized typemap copy operation.
For example,
%apply double *OUTPUT { double *x, double *y };
Copies *ALL* currently defined typemaps for 'double *OUTPUT' and
copies them to 'double *x' and 'double *y'.
Most people probably won't even notice this change in
%apply. However, where it will break things is in code like
this:
%apply double *OUTPUT { double *x };
%typemap(in) double *OUTPUT {
... whatever ...
}
void foo(double *x);
In SWIG1.1, you will find that 'foo' uses the 'double *OUTPUT' rule
even though it was defined after the %apply directive (this is
the weird aliasing scheme at work). In SWIG1.3 and later,
the 'double *OUTPUT' rule is ignored because it is defined
after the %apply directive.
3. The %clear directive has been modified to erase all currently
defined typemaps for a particular type. This differs from
SWIG1.1 where %clear only removed rules that were added using
the %apply directive.
4. Typemap matching is now performed using *exact* types.
This means that things like this
%typemap(in) char * { }
%typemap(in) const char * { }
are different typemaps. A similar rule applies for pointers,
arrays, and references. For example:
%typemap(in) double * { }
used to apply to 'double &', 'double []', Now, it only applies
to 'double *'. If you want a 'double &', you'll need to handle
that separately.
5. Array matching has been simplfied. In SWIG1.1, array matching
was performed by trying various combinations of dimensions.
For example, 'double a[10][20]' was matched as follows:
double [10][20]
double [ANY][20]
double [10][ANY]
double [ANY][ANY]
In SWIG1.3, only the following matches are attempted:
double [10][20]
double [ANY][ANY]
On the positive side, typemap matching is now *significantly* faster
than before.
*** POTENTIAL INCOMPATIBILITY ***
8/15/00 : beazley
Secret developer feature. Since datatypes are now represented as
strings internally, you can bypass limitations of the parser and
create a wild datatype by simply enclosing the raw string encoding
in backticks (``) and sticking it in the interface file anywhere a
type is expected. For example, `a(20).a(10).p.f(int,int)`. This
feature is only intended for testing (i.e., you want to see what
happens to your language module if it gets a reference to a pointer
to an array of pointers to functions or something).
*** SICK HACK ***
8/14/00 : beazley
Completely new type-system added to the implementation.
More details later.
8/11/00 : beazley
Cleaned up some of the I/O handling. SWIG no longer generates
any temporary files such as _wrap.wrap, _wrap.ii, _wrap.init.
Instead, these "files" are kept around in memory as strings
(although this is transparent to language modules).
8/4/00 : ttn
Added Makefile target "check" and variants.
This can be used like "make check" or, to explicitly skip a
language LANG: "make skip-LANG=true check". LANG is skipped
automatically if ./configure determines that LANG support is
insufficient.
Currently, the check is limited to doing the equivalent of
"make all" in some of the Examples directories. This should
be expanded both horizontally (different types of tests) and
vertically (after "make all" in an Examples subdir succeeds,
do some additional tests with the resulting interpreter, etc).
8/4/00 : ttn
Added Makefile target "distclean", which deletes all the
files ./configure creates, including config.status and friends.
8/3/00 : harcoh
java changes??? [todo: document changes]
7/23/00 : beazley
Typemaps have been modified to key off of the real datatypes
used in the interface file. This means that typemaps for
"const char *" and "char *" will be difference as will typemaps
for "Vector" and "Vector *."
*** POTENTIAL INCOMPATIBILITY ***
This is likely to break interfaces that rely on the odd type
handling behavior of typemaps in SWIG1.1--especially with
respect to interfaces involving pass-by-value.
7/23/00 : beazley
New %constant directive. This directive can be used to
create true constants in the target scripting language.
It's most simple form is something like this:
%constant FOO 42;
In this case, the type is inferred from the syntax of the
value (in reality, all #define macros are translated into
directives of this form).
An expanded version is as follows:
%constant(Foo *) FOO = &FooObj;
In this case, an explicit type can be specified. This
latter form may be useful for creating constants that
used to be specified as
const Foo *FOO = &FooObj;
(which are now treated as variables).
*** EXPERIMENTAL FEATURE *** The syntax may change in
the final release.
7/23/00 : beazley
Modified the parser so that variable declarations of the form
"const type *a" are handled as variables, not constants.
Note: SWIG1.1 handled this case erroneously because
const char *a is a pointer variable that can be reassigned.
*** POTENTIAL INCOMPATIBILITY ***
Note: just because this is the "right" way to do things,
doesn't mean it's the most appropriate interpretation.
I suspect that many C programmers might use 'const char *'
with the intent of creating a constant, without realizing
that they've created a reassignable global variable.
7/23/00 : beazley
The C/C++ wrapping layer has been completely redesigned and
reimplemented. This change should iron out a few rough
spots with the handling of datatypes. In addition, the
wrapper code is somewhat cleaner.
*** POTENTIAL INCOMPATIBILITY ***
This change may break interfaces that involve
subtle corner-cases with typemaps and the %addmethods
directive since some of these features had somewhat
type handling behavior in SWIG1.1.
7/23/00 : beazley
The "memberin" and "memberout" typemaps are gone for the
moment, but they might return as soon as I figure out
how to integrate them with some of the streamlined C wrapper
functions.
*** POTENTIAL INCOMPATIBILITY ***
7/22/00 : beazley
A variety of old type handling functions such as print_type(),
print_full(), print_mangle(), etc... are gone and have been
replaced with a smaller set of functions. See the file
Doc/internals.html for details. This will break all third
party language modules.
*** POTENTIAL INCOMPATIBILITY ***
7/20/00 : beazley
Deprecated the %val and %out directives. These directives
shouldn't really be necessary since typemaps can be used
to achieve similar results. This also cleans up the
handling of types and parameters quite a bit.
*** POTENTIAL INCOMPATIBILITY ***
7/20/00 : ttn
Fixed unspecified-module bug in Guile support and removed
more non-"with-smobs" functionality using patches submitted
by Matthias Koeppe.
Re-enable recognition of "-with-smobs" (with no effect since
we use smobs by default now) for the time being. After the
1.3a4 release, this option will signal an error.
7/17/00 : ttn
Fixed NULL-input bug in parameter list handling.
Reported by Matthias Koeppe.
7/12/00 : beazley
Fixed memory leak in Python type-checking code. Reported by
Keith Davidson. Bug #109379.
7/10/00 : beazley
Changed internal data structures related to function parameters.
7/10/00 : beazley
Fixed some bugs related to the handling of the %name() directive
and classes in the Tcl module. Problem reported by James Bailey.
7/10/00 : beazley
Fixed parsing and enum handling problems with character constants.
Reported by Greg Kochanski.
7/10/00 : beazley
Removed WrapperFunction class from the core and updated the language
module. This will break third party modules.
*** POTENTIAL INCOMPATIBILITY ***
7/9/00 : beazley
Implementation of SWIG no longer makes use of C++ operator overloading.
This will almost certainly break *all* third party language modules
that are not part of the main SWIG CVS tree. Sorry.
*** POTENTIAL INCOMPATIBILITY ***
7/8/00 : beazley
Removed the experimental and undocumented "build" typemap that
was intended to work with multiple arguments. Simply too weird
to keep around. Besides, a better replacement is in the works.
7/6/00 : ttn
Removed non-"with-smobs" functionality (Guile support), i.e.,
"-with-smobs" is now the default and no longer needs to be
specified on the command-line.
7/5/00 : ttn
Incorporated Ruby support contributed by Masaki Fukushima.
6/28/00 : ttn
Applied more-than-10-args bugfix patch contributed
by Matthias Koeppe.
6/27/00 : beazley
Rewrote some of the string handling and eliminated the C++
implementation (which is now just a wrapper).
6/27/00 : ttn
Added Doc/index.html and Doc/internals.html. The target
audience for the latter is new SWIG developers.
Version 1.3 Alpha 3 (June 18, 2000)
===================================
6/18/00 : beazley
Removed the naming.cxx, hash.cxx, and symbol.cxx files from
the SWIG1.1 directory. Continued to migrate things away
from the C++ base (although there's still a lot of work to do).
6/17/00 : beazley
Added a few more examples to the Examples directory. Still
need to do a lot of work on this.
6/16/00 : beazley
Added -includeall to follow all #include statements in the
preprocessor.
6/15/00 : beazley
Tried to fix as many C++ warnings as possible when compiling
with the Sun Workshop C++ compiler. Unfortunately, this means
that there are a lot of statements that contain string literals
of the form (char*)"Blah".
6/15/00: beazley
A variety of cleanup and performance optimization in the
low-level DOH library. This seems to result in a speedup
of 50-100% for preprocessing and other related tasks.
5/10/00 : ttn
Applied variable-wrapping bugfix patch contributed
by Matthias Koeppe.
4/17/00 : ttn
Updated MzScheme support contributed by Oleg Tolmatcev.
We now use a `Scheme_Type'-based structure to wrap pointers.
4/11/00 : ttn
Incorporated further Guile-support patch by Matthias Koeppe.
Typemaps previously deleted have been re-added. There is now
exception handling (see Doc/engineering.html). `SWIG_init' is now
declared extern only for simple linkage. Some bugs were fixed.
4/06/00 : ttn
Incorporated MzScheme support contributed by Oleg Tolmatcev.
This includes new directories Lib/mzscheme and Examples/mzscheme.
4/03/00 : ttn
Added Examples/guile and children. This is an adaptation of
the same-named directory from the SWIG-1.1p5 distribution.
Added Guile-specific section to Doc/engineering.html.
4/02/00 : ttn
Incorporated new guilemain.i by Martin Froehlich.
Incorporated Guile-support rewrite patch by Matthias Koeppe.
The command line option "-with-smobs" enables implementation of
pointer type handling using smobs, the canonical mechanism for
defining new types in Guile. Previous implementation (using
strings) is at the moment still supported but deprecated. At
some point, "-with-smobs" will be the default and no longer
required.
3/13/00 : beazley
Added purify patches submitted by Ram Bhamidipaty.
3/02/00 : ttn
Added support for different Guile "linkage" schemes.
Currently, "-Linkage hobbit" works.
Version 1.3 Alpha 2 (March 1, 2000)
===================================
2/29/00 : beazley
Made SWIG ignore the 'mutable' keyword.
2/29/00 : beazley
Incorporated some patches to the Perl5 module related to
the -hide option and the destruction of objects.
Patch submitted by Karl Forner.
2/27/00 : ttn
Incorporated Guile support contributed by Matthias Koeppe.
This includes a cpp macro in Lib/guile/guile.swg and the
entire file Lib/guile/typemaps.i.
2/25/00 : ttn
Modified configure.in and Makefile.in files to support
non-local build (useful in multi-arch environments).
2/24/00 : ttn
Incorporated Guile support contributed by Clark McGrew.
This works with Guile 1.3, but since it depends heavily
on the gh_ interface, it should work for all later versions.
It has not been tested with versions before 1.3.
WARNING: Code is unstable due to experimentation by ttn.
2/16/00 : beazley
A variety of performance improvements to the Python shadow
class code generation. Many of these result in substantial
runtime performance gains. However, these have come at
a cost of requiring the use of Python 1.5.2. For older
versions, use 'swig -noopt -python' to turn off these
optimization features.
Version 1.3 Alpha 1 (February 11, 2000)
=======================================
2/11/00 : Added 'void' to prototype of Python module initializer.
Reported by Mark Howson (1/20/00).
2/11/00 : beazley
Modified the Python shadow class code to discard ownership of an
object whenever it is assigned to a member of another object.
This problem has been around for awhile, but was most recently
reported by Burkhard Kloss (12/30/99).
2/11/00 : beazley
Added braces around macros in the exception.i library. Reported
by Buck Hodges (12/19/99)
2/11/00 : beazley
Fixed bug in the constraints.i library. Reported by Buck
Hodges (12/14/99)
2/11/00 : beazley
The %native directive now generates Tcl8 object-style command calls.
A full solution for Tcl7 and Tcl8 is still needed. Patch suggested
by Mike Weiblen (11/29/99)
2/11/00 : beazley
Modified the typemap code to include the $ndim variable for arrays.
Patch provided by Michel Sanner (11/12/99).
2/11/00 : beazley
Modified the Python module to raise a Runtime error if an attempt
is made to set a read-only member of a shadow class. Reported by
Michel Sanner (11/5/99).
2/10/00 : The documentation system has been removed. However, it is likely
to return at some point in the future.
2/1/00 : Added a number of performance enhancements to the Python shadow
classing and type-checking code. Contributed by Vadim Chugunov.
1. Remove _kwargs argument from the shadow wrappers when -keyword
option is not specified. This saves us a construction of keyword
dictionary on each method call.
def method1(self, *_args, **_kwargs):
val = apply(test2c.PyClass1_method1, (self,) + _args, _kwargs)
return val
becomes
def method1(self, *_args):
val = apply(test2c.PyClass1_method1, (self,) + _args)
return val
2. Incorporate self into the _args tuple. This saves at least one tuple
allocation per method call.
def method1(self, *_args):
val = apply(test2c.PyClass1_method1, (self,) + _args)
return val
becomes
def method1(*_args):
val = apply(test2c.PyClass1_method1, _args)
return val
3. Remove *Ptr classes.
Assume that we are SWIGging a c++ class CppClass.
Currently SWIG will generate both CppClassPtr class
that hosts all methods and also CppClass that is derived
from the former and contains just the constructor.
When CppClass method is called, the interpreter will try
to find it in the CppClass's dictionary first, and only then
check the base class.
CppClassPtr functionality may be emulated with:
import new
_new_instance = new.instance
def CppClassPtr(this):
return _new_instance(CppClass, {"this":this,"thisown":0})
This saves us one dictionary lookup per call.
<DB>The new module was first added in Python-1.5.2 so it
won't work with older versions. I've implemented an
alternative that achieves the same thing</DB>
4. Use CObjects instead of strings for pointers.
Dave: This enhancements result in speedups of up to 50% in some
of the preliminary tests I ran.
2/1/00 : Upgraded the Python module to use a new type-checking scheme that
is more memory efficient, provides better performance, and
is less error prone. Unfortunately, it will break all code that
depends on the SWIG_GetPtr() function call in typemaps.
These functions should be changed as follows:
if (SWIG_GetPtr(string,&ptr,"_Foo_p")) {
return NULL;
}
becomes
if (SWIG_ConvertPtr(pyobj, &ptr, SWIG_TYPE_Foo_p) == -1) {
return NULL;
}
Note: In the new implementation SWIG_TYPE_Foo_p is no longer
a type-signature string, but rather an index into a type
encoding table that contains type information.
*** POTENTIAL INCOMPATIBILITY ***
1/30/00 : loic
Conditionaly compile experimental code with --enable-experiment
configure flag.
Fix .cvsignore to ignore configrue & yacc generated files
1/28/00 : loic
Apply automake everywhere
Keep configure scripts so that people are not *forced* to autoconf
Keep sources generated by yacc so that compilation without yacc
is possible.
Source/LParse/cscanner.c: change lyacc.h into parser.h to please
default yacc generation rules.
Use AC_CONFIG_SUBDIRS in configure.in instead of hand made script.
Update all relevant .cvsignore to include .deps
Fixed missing ; line 136 Source/Swig/swig.h
1/13/00 : beazley
Fixed a number of minor end-of-file parsing problems in the
preprocessor.
1/13/00 : beazley
Added -freeze option that forces SWIG to freeze upon exit.
This is only used as a debugging tool so that I can more
easily examine SWIG's memory footprint.
1/13/00 : beazley
Added patch to guile module for supporting optional arguments
Patch contributed by Dieter Baron.
1/13/00 : loic
Added .cvsignore, Examples/.cvsignore, Source/DOH/Doh/.cvsignore
Source/SWIG1.1/main.cxx: Fixed -I handling bug
Source/Modules1.1/java.cxx: fixed char* -> const char* warnings that are
errors when compiling with gcc-2.95.2
Source/SWIG1.1/main.cxx: cast const char* to char* for String_replace
token and rep should really be const.
1/12/00 : beazley
Added Harco's Java modules.
1/12/00 : beazley
Revoked the %ifdef, %ifndef, %endif, %if, %elif, and %else
directives. These are no longer needed as SWIG now has a real
preprocessor.
*** POTENTIAL INCOMPATIBILITY ***
1/12/00 : beazley
Moved the documentation modules from the SWIG directory
to the Modules directory (where they really should have been
to begin with).
1/12/00 : beazley
Removed the -stat option for printing statistics. The
statistics reporting was inadequate and mostly broken
anyway.
*** POTENTIAL INCOMPATIBILITY ***
1/12/00 : beazley
Removed the -t option for reading a typemap file. More
trouble than it's worth. Just include typemaps at the top
of the interface file.
*** POTENTIAL INCOMPATIBILITY ***
1/12/00 : beazley
Removed the %checkout directive.
*** POTENTIAL INCOMPATIBILITY ***
1/12/00 : beazley
Removed the -ci option for file checkin. Too problematic
to implement. Probably better to just put your SWIG library
under CVS instead.
*** POTENTIAL INCOMPATIBILITY ***.
1/11/00 : beazley
Deleted the LATEX module. Sorry... Didn't know anyone
who was using it. Besides, I'm looking to simplify
the documentation system.
*** POTENTIAL INCOMPATIBILITY ***
1/11/00 : beazley
Modified the ASCII documentation module to use a .txt
suffix for its output file instead of .doc.
1/11/00 : beazley
Added the long-lost SWIG preprocessor back to the system.
It should be enabled by default. Raw preprocessed output
can be viewed using swig -E file.i.
*** NEW FEATURE ***
1/11/00 : beazley and djmitche
Completely reorganized the SWIG directory structure. The
basic organization is now:
Source/ SWIG source code
Lib/ SWIG library files (swig_lib)
Doc/ Documentation
Examples/ Examples
More directories will be added as needed.
12/08/99: Loic Dachary (loic@senga.org)
Enhanced package handling for perl5 and c++.
With new option -hide Foo::Bar, every perl5 object (Frob) is
qualified by Foo::Bar::Frob. The package name is solely used
to encapsulate C/C++ wrappers output in <module>_wrap.c and the
corresponding perl package in <module>.pm. Note that a package
name may contain :: (Frob::Nitz) and will be relative to the
package name provided by -hide (Foo::Bar::Frob::Nitz).
In *_wrap.c, SWIG_init macro is used. Was previously defined
but not used and simplifies code.
Added typemap(perl5,perl5in) and typemap(perl5,perl5out) that
do the equivalent of typemap(perl5,in) and typemap(perl5,out)
but contain perl code and applies to wrappers generated by
-shadow.
Lacking proper regression tests I used
Examples/perl5/{c++,constraint,defarg,except,
graph/graph[1234],multinherit,nested,shadow,simple,tree,
typemaps/{argv,argv2,arraymember,database,file,ignore,integer,
output,passref,reference,return}}/. I ran swig with and without
the patches, diff the generatedsources, run the .pl files
and checked that the results are identical. In all those examples
I had no error.
11/21/99: Modified the Tcl module to provide full variable linking capabilities
to all datatypes. In previous versions, a pair of accessor functions
were created for datatypes incompatible with the Tcl_LinkVar() function.
Now, we simply use variable traces to support everything. This may
break scripts that rely upon the older behavior.
*** POTENTIAL INCOMPATIBILITY ***
11/21/99: Added slight tweak to wrapper generator to collect local variables
of similar type. Produces somewhat more compact wrapper code.
11/20/99: Modified the Tcl module to use SWIG_GetArgs() to parse
arguments. This is a technique borrowed from Python in which
arguments are converted using a format string convention similiar
to fprintf(). This results in a *substantial* reduction in the
size of the resulting wrapper code with only a modest runtime overhead
in going through the extra conversion function.
11/13/99: Completely rewrote the class/structure generation code for the
Tcl module. Now, a small set of runtime functions are used
to implement the functionality for all classes (instead of a
massive amount of runtime code being generated for each class).
Class specific information is simply encoded in a series of
static tables. This results in a *HUGE* reduction in wrapper
code size--especially for C++.
11/13/99: Removed the -tcl (Tcl 7.x) module. Tcl 8.0 is now several
years old and the defacto standard--no real reason to keep
supporting the old version at this point.
11/13/99: Cleaned up -c option for Python module. The pyexp.swg file
is now gone.
11/13/99: Fixed external declarations to work better with static linking
on Windows. Static linking should now be possible by defining
the -DSTATIC_LINK option on the command line. Patch contributed
by Alberto Fonseca.
11/5/99 : Fixed an obscure code generation bug related to the generation
of default constructors. Bug reported by Brad Clements.
11/5/99 : Fixed a few memory problems found by purify.
11/5/99 : Officially deprecated the -htcl, -htk, and -plugin options
from the Tcl and Tcl8 modules.
10/26/99: Removed unused variable from python/typemaps.i. Patch
contributed by Keith Davidson.
8/16/99 : Added _WIN32 symbol to libraries to better support Windows.
8/16/99 : Deprecated the Perl4 module. It is no longer included in the
distribution and no longer supported. In the entire 3 years SWIG
has been around I never received a single comment about it so I'm
assuming no one will miss it...
8/16/99 : Modified the type-checking code to register type mappings using a
table instead of repeated calls to SWIG_RegisterMapping(). This
reduces the size of the module initialization function somewhat.
8/15/99 : Cleaned up the pointer type-checking code in the Tcl module.
8/15/99 : Many changes to the libraries to support runtime libraries.
8/13/99 : Eliminated C++ compiler warning messages about extern "C" linkage.
8/13/99 : Some cleanup of Python .swg files to better support runtime libraries
on Windows.
8/13/99 : Modified the %pragma directive to attach pragmas declared inside
a class definition to the class itself. For example:
class foo {
...
%pragma(python) addtomethod = "insert:print `hello world'"
...
}
Most people don't need to worry about how this works. For people
writing backend modules, class-based pragmas work like this:
lang->cpp_open_class() // Open a class
lang->cpp_pragma() // Supply pragmas
... // Emit members
lang->cpp_close_class() // Close the class
All of the pragmas are passed first since they might be used to
affect the code generation of other members. Please see
the Python module for an example. Patches contributed
by Robin Dunn.
8/13/99 : Patch to Python shadow classes to eliminate ignored
exception errors in destructors. Patch contributed
by Robin Dunn.
8/11/99 : Minor patch to swig_lib/python/swigptr.swg (added SWIGSTATIC
declaration). Patch contributed by Lyle Johnson.
8/11/99 : Added FIRSTKEY/NEXTKEY methods to Perl5 shadow classes
Patch contributed by Dennis Marsa.
8/11/99 : Modified Python module so that NULL pointers are returned
and passed as 'None.' Patch contributed by Tal Shalif.
8/10/99 : Fixed missing 'int' specifiers in various places.
8/10/99 : Added Windows makefile for Runtime libraries. Contributed
by Bob Techentin.
8/10/99 : Fixed minor problem in Python runtime makefile introduced
by keyword arguments.
8/8/99 : Changed $target of perl5(out) typemap from ST(0) to
ST(argvi). Patch contributed by Geoffrey Hort.
8/8/99 : Fixed bug in typemap checking related to the ANY keyword
in arrays and ignored arguments. Error reported by
Geoffrey Hort.
8/8/99 : %enabledoc and %disabledoc directives can now be used
inside class/structure definitions. However, no check
is made to see if they are balanced (i.e., a %disabledoc
directive inside a class does not have to have a matching
%enabledoc in the same class).
8/8/99 : Keyword argument handling is now supported in the Python
module. For example:
int foo(char *bar, int spam, double x);
Can be called from Python as
foo(x = 3.4, bar="hello", spam=42)
To enable this feature, run SWIG with the '-keyword' command
line option. Mixing keyword and default arguments
should work as well. Unnamed arguments are assigned names
such as "arg1", "arg2", etc...
*** POTENTIAL INCOMPATIBILITY ***
Functions with duplicate argument names such as
bar(int *OUTPUT, int *OUTPUT) will likely cause problematic
wrapper code to be generated. To fix this, use different
names or use %apply to map typemaps to alternate names.
8/8/99 : Handling of the 'this' pointer has been changed in Python shadow
classes. Previously, dereferencing of '.this' occured in the
Python shadow class itself. Now, this step occurs in the C
wrappers using the following function:
SWIG_GetPtrObj(PyObject *, void **ptr, char *type)
This function can accept either a string containing a pointer
or a shadow class instance with a '.this' attribute of
appropriate type. This change allows the following:
1. The real shadow class instance for an object is
passed to the C wrappers where it can be examined/modified
by typemaps.
2. Handling of default/keyword arguments is now greatly
simplified.
3. The Python wrapper code is much more simple.
Plus, it eliminated more than 300 lines of C++ code in the
Python module.
*** CAVEAT : This requires the abstract object interface.
It should work with Python 1.4, but probably nothing older
than that.
8/8/99 : Fixed handling of "const" and pointers in classes. In particular,
declarations such as
class foo {
...
const char *msg;
const int *iptr;
}
are handled as assignable variables as opposed to constant
values (this is the correct behavior in C/C++). Note:
declarations such as "char *const msg" are still unsupported.
Constants declared at the global level using const are also
broken (because I have a number of interfaces that rely upon
this behavior).
*** POTENTIAL INCOMPATIBILITY *** This may break interfaces that
mistakenly treat 'const char *' types as constant values.
8/8/99 : Modified the parser to support bit-fields. For example:
typedef struct {
unsigned int is_keyword : 1;
unsigned int is_extern : 1;
unsigned int is_static : 1;
} flags;
Bit-fields can only be applied to integer types and their
are other restrictions. SWIG performs no such type-checking
(although the C compiler will catch problems when it tries to
compile the wrapper code).
8/8/99 : Removed trailing space of $basetype substitution in typemaps.
This is to allow things like this:
%typemap(python, argout) spam** OUTPUT{
...
char* a = "$basetype_p";
...
}
(Patch suggested by Nathan Dunfield).
6/22/99 : Made a very slight tweak to the Perl5 shadow class
code that allows typemaps to alter the return type
of objects (to support polymorphic types). Patch
contributed by Drake Diedrich.
4/8/99 : Fixed null pointer handling bug in Perl module.
Patch contributed by Junio Hamano.
3/17/99 : Fixed bug in perl5ptr.swg for ActiveState Perl.
Patch contributed by Greg Anderson.
2/27/99 : Eliminated segmentation fault when Swig runs on
empty files.
2/27/99 : Added patch to Guile module to eliminate unused
variables. Contributed by Mike Simons.
2/27/99 : Fixed problem with %addmethods returning references.
2/27/99 : Fixed Runtime/Makefile. Patch contributed by
Mike Romberg.
2/27/99 : Incorporated patches to the type-checker.
2/27/99 : Fixed problem with -exportall switch and shadow classes
in Perl5 module. Patch contributed by Dennis Marsa.
2/27/99 : Modified Perl5 module to recognize 'undef' as a NULL char *.
Patch contributed by Junio Hamano.
2/27/99 : Fixed the Perl5 module to support the newer versions of
ActiveState Perl for Win32.
2/27/99 : Fixed the include order of files specified with the
-I option.
2/5/98- : Dave finishes his dissertation, goes job hunting, moves to
2/5/99 Chicago and generally thrashes about.
Version 1.1 Patch 5 (February 5, 1998)
======================================
2/4/98 : Fixed a bug in the configure script when different package
locations are specified (--with-tclincl, etc...).
2/2/98 : Fixed name-clash bug related to the switch to C macros for accessor
functions. The new scheme did not work correctly for objects
with members such as 'obj', 'val', etc... Fixed the bug by
appending the word 'swig' to macro argument names. Patch
contributed by Rudy Albachten.
2/2/98 : Slight fix to the Perl5 module to eliminate warning messages
about 'varname used only once : possible typo'. Fix
contributed by Rudy Albachten.
1/9/98 : Fixed a bug in the Perl 5 module related to the creation of
constants and shadow classes.
1/9/98 : Fixed linking bug with Python 1.5 embed.i library file.
Version 1.1 Patch 4 (January 4, 1998)
=====================================
1/4/98 : Changed structured of the Examples directory to be more friendly
to Borland C++.
1/4/98 : Added the function Makefile.win.bc for compiling the examples
under Borland 5.2.
1/4/98 : Slight change to the perl5 module and C++ compilation. The
<math.h> library is now included before any Perl headers
because Perl the extern "C" linkage of math.h screws alot
of things up (especially on Windows).
1/2/98 : Change to the Python module that reduces the number of constants
created by C++ classes, inheritance, and shadow classes. This
modification may introduce a few slight incompatibilities if
you attempt to use the non-shadow class interface with shadow
classes enabled. Patch contributed by Mike Romberg.
1/2/98 : Support for Tcl 8.0 namespaces has been added. This *replaces*
the original SWIG mechanism that assumed [incr Tcl] namespaces.
To use namespaces, simply run SWIG with the following options
swig -tcl -namespace foo.i
This places everything in a namespace that matches
the module name
swig -tcl -namespace -prefix bar foo.i
This places everything in the namespace 'bar'
The use of namespaces is new in Tcl 8.0. However, the wrapper code
generated by SWIG will still work with all versions of Tcl newer
than and including Tcl 7.3/Tk3.6 even if the -namespace option is
used.
*** POTENTIAL INCOMPATIBILITY ***
This change may break existing applications that relied on the
-prefix and -namespace options.
1/2/98 : Added the following constants to the Tcl wrapper code
SWIG_name - Name of the SWIG module
SWIG_prefix - Prefix/namespace appended to command names
SWIG_namespace - Name of the namespace
SWIG library writers can use these to their advantages.
1/2/98 : Fixed a bug in the Tcl8 module related to the creation of
pointer constants (the function SWIG_MakePtr was missing from
the wrapper code).
1/2/98 : Added the consthash.i library file to the Tcl and Tcl8 modules.
1/1/98 : Changed and cleaned up the Python typemaps.i file. The following
significant changes were made :
1. The OUTPUT typemap now returns Python tuples instead of
lists. Lists can be returned as before by using the
L_OUTPUT type. If compatibility with older versions
is needed, run SWIG with the -DOUTPUT_LIST option.
2. The BOTH typemap has been renamed to INOUT. For backwards
compatibility, the "BOTH" method still exists however.
3. Output typemaps now generate less code than before.
Changes to typemaps.i may break existing Python scripts that assume
output in the form of a list.
*** POTENTIAL INCOMPATIBILITY ***
12/31/97: Fixed long overdue problems with the testing scripts and certain
makefiles that required the use of the bash shell. Everything should
work properly with the standard Bourne shell (sh) now.
12/31/97: Modified typemaps to allow $basetype as a valid local variable.
This allows for all sorts of bizarre hackish typemaps that
do cool things. Patch contributed by Dominique Dumont.
12/31/97: Switched accessor functions generated for member data to
C preprocessor macros (except in cases involving typemaps
or char *).
12/31/97: Fixed a bug related to C++ member data involving references.
12/31/97: Changed accessor functions for C++ member functions to
preprocessor macros. This cleans up the wrapper code
and results in fewer function definitions.
12/31/97: Changed the default C constructor to use calloc() instead
of malloc()
12/30/97: Changed the creation of constants in the Perl5 module.
For all practical purposes, they should work in exactly the
same way as before except that they now require much less
wrapper code. Modules containing large numbers of
constants may see greater than a 50% reduction in wrapper
code size.
12/30/97: Modified the Python module to be more intelligent about the
creation of constants. SWIG no longer generates redundant
global variables and the size of the module initialization
function should be reduced. (Many thanks to Jim Fulton).
12/29/97: Fixed a bug in C++ code generation related to member functions,
default arguments, and references.
12/29/97: Fixed configure script and a few makefiles to support Python 1.5
12/29/97: Added 'embed15.i' library file. This file should be used to
staticly link versions of Python 1.5. To make it the default,
simply copy 'swig_lib/python/embed15.i' to 'swig_lib/python/embed.i'
Version 1.1 Patch 3 (November 24, 1997)
========================================
11/23/97: Fixed a bug in the Perl5 module with shadow classes and
static class functions that return class instances.
Note : The fix for this bug requires a slight restructuring of
of the .pm files created by SWIG.
11/23/97: Fixed a bug in the Tcl/Tcl8 modules related to variable linking
of character arrays. If you declared a global variable 'char foo[10]',
the generated wrapper code would either cause a segmentation fault
immediately upon loading or weird memory corruption elsewhere.
This should now be fixed although character arrays can only be
read-only.
11/23/97: Fixed a bug with the %import directive that caused it to
fail if files were imported from directories other than
the current working directory.
11/23/97: Fixed incorrect diagnostic message in the ASCII documentation
module.
11/23/97: Changed the behavior of the -o option when used with shadow
classes. If -o was used to specify both the pathname and filename
of SWIG's output such as
swig -o /home/swig/wrapper.c -shadow -perl5 foo.i
The wrapper code would be placed the file specified with -o,
but the .pm file and documentation would be placed in the
directory where SWIG was run. Now, these files are placed
in the same directory as the file specified with the -o option.
This change is also needed for proper operation on the
Macintosh.
11/23/97: Added a 'this()' method to Perl5 shadow classes. This can
be used to return the normal pointer value from a shadow
class that is represented as a tied hash. To use just
invoke as a method like this :
$l = new List; # Create an object
$ptr = $l->this(); # Get the normal pointer value
*** NEW FEATURE ***
11/23/97: Fixed the Tcl 8 pointer.i library file (which was completely
broken in 1.1p2).
11/23/97: Modified the Perl5 type-checker to fix a few problems
with global variables of pointer types and to allow
tied hashes to be used interchangably with normal
pointer values.
11/23/97: Modified the typemap mechanism to allow output
typemaps of type 'void'. These were ignored previously,
but now if you specify,
%typemap(lang,out) void {
... return a void ...
}
You can change or assign a return value to the function.
11/23/97: Fixed processing of 'bool' datatypes in the Python module.
11/23/97: Fixed minor parsing error with C++ initializers. For example,
class B : public A {
public:
B() : A() { ... };
...
}
11/23/97: Fixed the Tcl8 module so that C functions that call back into
Tcl don't corrupt the return result object (SWIG was gathering
the result object too early which leads to problems if subsequent
Tcl calls are made).
11/23/97: Fixed a code generation bug in the Python module when two or
more output parameters were used as the first arguments of a
function. For example :
%include typemaps.i
void foo(double *OUTPUT, double *OUTPUT, double a);
Previously, doing this resulted in the creation of an
extraneous comma in the output, resulting in a C syntax error.
11/22/97: Fixed a bug when template handling that was stripping whitespace
around nested templates. For example :
Foo<Bar<double> >
was getting munged into Foo<Bar>> which is a syntax error in
in the C++ compiler.
11/22/97: Fixed bugs in the Borland C++ makefiles.
11/22/97: Fixed memory corruption bug when processing integer
arguments in Tcl8 module.
11/21/97: Fixed a bug in the Runtime/Makefile related to Tcl 8.
11/21/97: Fixed a bug with the %new directive and Perl5 shadow classes.
No longer generates a perl syntax error.
11/9/97 : Changed a strncpy() to strcpy() in the pointer type-checker.
This results in a substantial performance improvement in
type-checking.
10/29/97: Fixed a bug in the code generation of default arguments and
user-defined types. For example :
void foo(Vector a, Vector b = d);
should now work properly.
Version 1.1 Patch 2 (September 4, 1997)
=======================================
9/4/97 : Fixed problem with handling of virtual functions that
was introduced by some changes in the C++ module.
Version 1.1 Patch 1 (August 27, 1997)
=====================================
8/26/97 : Fixed compilation and run-time bugs with Tcl 8.0 final.
8/21/97 : Fixed code generation bug with arrays appearing as arguments
to C++ member functions. For example :
class Foo {
public:
void Bar(int a[20][20]);
};
There is still a bug using arrays with added methods
however.
8/20/97 : Fixed a bug with generating the code for added methods
involving pass-by-value.
8/19/97 : Modified the typemapper to substitute the '$arg' value
when declaring local variables. For example :
%typemap(in) double * (double temp_$arg) {
... do something ...
}
When applied to a real function such as the following :
void foo(double *a, double *b, double *result);
three local variables will be created as follows :
double temp_a;
double temp_b;
double temp_result;
This can be used when writing multiple typemaps that need
to access the same local variables.
7/27/97 : Fixed a variety of problems with the %apply directive and arrays.
The following types of declarations should now work :
%apply double [ANY] { Real [ANY] };
%apply double [4] { double [10] };
A generic version of apply like this :
%apply double { Real };
should now work--even if arrays involving doubles and Reals are
used later.
7/27/97 : Changed warning message about "Array X has been converted to Y" to
only appear if running SWIG in verbose mode.
7/27/97 : Added the variables $parmname and $basemangle to the typemap
generator. $parmname is the name of the parameter used
when the typemap was matched. It may be "" if no parameter
was used. $basemangle is a mangled version of the base
datatype. Sometimes used for array handling.
7/27/97 : Changed the behavior of output arguments with Python shadow classes.
Originally, if a function returned an object 'Foo', the shadow class
mechanism would create code like this :
def return_foo():
val = FooPtr(shadowc.return_foo())
val.this = 1
return val
The problem with this is that typemaps allow a user to redefine
the output behavior of a function--as a result, we can no longer
make any assumptions about the return type being a pointer or
even being a single value for that matter (it could be a list,
tuple, etc...). If SWIG detects the use of output typemaps
(either "out" or "argout") it returns the result unmodified like
this :
def return_foo():
val = shadowc.return_foo()
return val
In this case, it is up to the user to figure out what to do
with the return value (including the possibility of converting it
into a Python class).
7/26/97 : Fixed a parsing problem with types like 'unsigned long int',
'unsigned short int', etc...
7/24/97 : Minor bug fix to Tcl 8 module to parse enums properly. Also
fixed a memory corruption problem in the type-checker.
(patch contributed by Henry Rowley.
7/24/97 : Added Python-tuple typemaps contributed by Robin Dunn.
7/24/97 : Incorporated some changes to the Python module in support of
Mark Hammond's COM support. I'm not entirely sure they
work yet however. Needs documentation and testing.
7/24/97 : Fixed code generation bugs when structures had array members
and typemaps were used. For example :
%typemap(memberin) double [20][20] {
... get a double [20][20] ...
}
struct Foo {
double a[20][20];
}
Originally, this would generate a compiler-type error when
the wrapper code was compiled. Now, a helper function like
this is generated :
double *Foo_a_set(Foo *a, double val[20][20]) {
... memberin typemap here ...
return (double *) val;
}
When writing typemaps, one can assume that the source variable
is an array of the *same* type as the structure member. This
may break some codes that managed to work around the array bug.
*** POTENTIAL INCOMPATIBILITY ***
7/13/97 : Fixed bug in Perl5 module when using C global variables that
are pointers. When used in function calls and other operations,
the value of the pointer would be invalid---causing core
dumps and other problems. SWIG implements global variables
using Perl magic variables. As it turns out, the error
was caused by the fact that the pointer-extraction code
was somehow bypassing the procedure used to resolve magical
variables (hence, leaving the value undefined). To fix
the problem, SWIG now explicitly resolves magic before
extracting pointer values.
7/12/97 : Eliminated the last remnants of free() and malloc() from
the SWIG compiler.
7/12/97 : Fixed parsing problems with typemaps involving arrays and
temporary variables of arrays. Also made it possible for
SWIG to handle typemaps like this :
%typemap(in) double [ANY] (double temp[$dim0]) {
... store data in temp[$dim0] ...
}
Not only does this typemap match any double [] array, it
creates a local variable with precisely the right dimensions.
(ie. $dim0 gets filled in with the real number of dimensions).
Of course, off the record, this will be a way to add more
functionality to the typemaps.i libraries.
7/9/97 : Fixed some problems with Perl5, static linking, and shadow
classes. When statically linking multiple modules together, write
a top-level interface file like this when shadow classes are not
used :
%module swig, foo, bar, glob;
%include perlmain.i
When shadow classes are used, the module names have an extra 'c'
appended so it should read as :
%module swig, fooc, barc, globc;
%include perlmain.i
When linking multiple modules, consider using the SWIG runtime
library.
7/8/97 : Incorporated fixed versions of the Borland C++ Makefiles.
7/8/97 : First cut at trying to eliminate excessive compiler warnings.
As it turns out, alot of warnings go away if you just make
declarations like this
clientData = clientData;
in the resulting wrapper code. Most compilers should just
ignore this code (at least would can hope).
7/8/97 : Fixed bizarre code generation bug with typemaps and C++ classes.
In some cases, typemaps containing printf formatting strings such as
%typemap(memberout) int * {
printf("%d",42);
}
Would generate completely bogus code with garbage replacing
the '%d'. Caused by one faulty use of printf (wasn't able to find
any other occurences).
7/7/97 : Fixed bug in Python shadow class generation with non-member
functions that are returning more than one value.
7/7/97 : Incorporated modifications to make SWIG work with Guile 1.2.
Still need to test it out, but it is rumored to work.
7/2/97 : Fixed some bugs related to output arguments and Python shadow
classes. If an output argument is detected, SWIG assumes
that the result is a list and handles it appropriately.
If the normal return type of an function is an object,
it will be converted into a shadow class as before, but
with the assumption that it is the first element of a
list. *** NOTE : This behavior has been subsequently changed ***
6/29/97 : Changed EXPORT to SWIGEXPORT in all of the language modules.
Should provide better compatibility with Windows.
6/29/97 : Modified Python shadow classes so that output arguments
work correctly (when typemaps are used).
Version 1.1 (June 24, 1997)
===========================
6/24/97 : Fixed Objective-C constructor bug when working with Perl5
shadow classes.
6/23/97 : Fixed some parsing problems with Objective-C. Declarations
such as the following should work now :
- foo : (int) a with: (int) b;
6/22/97 : Added SWIG Runtime library. This library contains
the SWIG pointer type-checker and support functions
that are normally included in every module. By using
the library, it is easier to work with multiple SWIG
generated modules.
6/22/97 : Fixed minor bug in Perl5 module related to static linking
of multiple modules.
6/22/97 : Fixed some bugs with the %import directive. When used with
Perl5 shadow classes, this generates a 'require' statement
to load in external modules.
6/22/97 : Added -swiglib option. This prints out the location of the
SWIG library and exits. This option is only really useful to
configuration tools that are looking for SWIG and its library
location (e.g. autoconf, configure, etc...).
6/21/97 : Fixed export bug with Perl5.004 on Windows-NT.
6/20/97 : Minor change to code generation of class/structure members in
order to work better with typemaps. Should have no noticable
impact on existing SWIG modules.
6/19/97 : Added -t option. This allows SWIG to load a typemap file before
processing any declarations. For example :
swig -t typemaps.i -python example.i
At most, only one typemap file can be specified in this manner.
*** NEW FEATURE ***
6/18/97 : Need a Makefile fast? Type
swig [-tcl, -perl5, -python] -co Makefile
and you will get a Makefile specific to that target language.
You just need to modify it for your application and you're
ready to run.
6/18/97 : Completed the -ci option. This option checks a file into the
SWIG library. It should be used in conjunction with a
language option. For example :
swig -tcl -ci foobar.i
Checks the file foobar.i into the Tcl part of the library.
In order to check a file into the general library (accessible
to all languages modules), do the following
swig -ci -o ../foobar.i foobar.i
(Admittedly this looks a little strange but is unavoidable).
The check-in option is primarily designed for SWIG maintenance
and library development. The command will fail if the user does
not have write permission to the SWIG library. Third party library
extensions can easily install themselves by simply providing
a shell script that uses 'swig -ci' to install the appropriate
library files. It is not necessary to know where the SWIG library
is located if you use this mechanism.
*** NEW FEATURE ***
6/16/97 : Fixed a bug in shadow class generation when %name() was applied
to a class definition. Unfortunately, fixing the bug required
a change in the Language C API by adding an extra argument to
the Language::cpp_class_decl() function. This may break
SWIG C++ extensions.
*** POTENTIAL INCOMPATIBILITY ***
6/15/97 : Added a warning message if no module name is specified with the
%module directive or -module option.
6/15/97 : Fixed line number bug when reporting errors for undefined
base classes.
6/15/97 : Added new %rename directive. This allows the forward declaration
of a renaming. For example :
%rename OldName NewName;
.... later ...
int OldName(int);
Unlike %name, %rename will rename any occurence of the old name.
This applies to functions, variables, class members and so forth.
There is no way to disable %rename once set, but you can change the
name by redeclaring it to something else.
*** NEW FEATURE ***
6/15/97 : Improved the implementation of the %name directive so that it
could be used with conditional compilation :
#ifdef SWIG
%name(NewName)
#endif
int OldName(int);
6/15/97 : Added support for functions with no return datatype. In this case,
SWIG assumes a return type of 'int'.
6/11/97 : Improved error reporting in the parser. It should be a little
less sensitive to errors that occur inside class definitions
now. Also reports errors for function pointers.
6/11/97 : Made '$' a legal symbol in identifiers. This is to support
some Objective-C libraries. Some compilers (such as gcc) may also
allow identifiers to contain a $ in C/C++ code as well (this is
an obscure feature of C). When '$' appears in identifier, SWIG
remaps it to the string '_S_' when creating the scripting language
function. Thus a function 'foo$bar' would be called 'foo_S_bar'.
6/11/97 : Fixed bug in Python shadow classes with __repr__ method. If
supplied by the user, it was ignored, but now it should work.
6/9/97 : Fixed the Tcl 8.0 module to work with Tcl 8.0b1. SWIG is no
longer compatible with *any* alpha release of Tcl 8.0.
*** POTENTIAL INCOMPATIBILITY ***
6/7/97 : Put a maximal error count in (currently set to 20). SWIG will bail out
if it generates more errors than this (useful for preventing SWIG
from printing 4000 syntax errors when it gets confused).
6/7/97 : Fixed segmentation fault when parsing variable length arguments.
6/7/97 : Minor change to Perl5 module. C++ static functions are now
put in the same package as their class when using shadow classes.
6/7/97 : Centralized the naming of functions, members, wrappers etc... By
centralizing the naming scheme, it should be possible to make
some multi-file optimizations. Also, it should be possible to
change SWIG's naming scheme (perhaps a new feature to be added
later).
6/2/97 : Added 'arginit' typemap. This can be used to assign initial values
to function arguments. Doing so makes it somewhat easier to detect
improper argument passing when working with other typemaps.
6/2/97 : Fixed code generation bug when read-only variables were inherited
into other classes. Under inheritance, the variables would
become writable, but this has now been corrected.
5/30/97 : An empty %name() directive is no longer allowed or supported.
This directive was originally used to strip the prefix
off of a class or structure. Unfortunately, this never really
seemed to work right and it complicated the C++ code generator
significantly. As far as I can tell no one uses it, so it
is now history. *** POTENTIAL INCOMPATIBILITY ***
5/28/97 : Fixed a parsing bug with #define and C++ comments. Declarations
such as the following now work properly :
#define CONST 4 // A Comment
5/28/97 : Made some performance improvements to the SWIG String class.
(only affects the SWIG compiler itself).
5/28/97 : Modified the parser to skip template definitions and issue a
warning message.
5/28/97 : Preliminary support for parameterized types added (ie. templates).
Types such as the following should pass through the SWIG compiler
void foo(vector<complex> *a, vector<double> *b);
When used, the entire name 'vector<complex>' becomes the name
of the datatype. Due to space limitations in datatype
representations, the name should not exceed 96 characters.
Note : This is only part of what is needed for template support.
Template class definitions are not yet supported by SWIG.
The template notation above may also be used when specifying
Objective-C protocol lists.
*** NEW FEATURE ***
5/24/97 : First cut at Objective-C support added. As it turns out, almost
everything can be handled with only a few minor modifications to
the C++ module.
*** NEW FEATURE ***
5/23/97 : Fixed repeated definition bug in multiple inheritance handling
when multiple base classes share a common base class (ie.
the evil diamond).
5/21/97 : Fixed rather embarrassing typo that worked its way into the
Tests/Build directory.
5/19/97 : Fixed code generation bug when using native methods and
shadow classes with Python and Perl5 modules.
5/19/97 : Modified the %apply directive slightly so that it would work
with pointers a little better. For example :
%apply unsigned long { DWORD };
Applies *all* typemaps associated with "unsigned long" to
"DWORD". This now includes pointers to the two datatypes.
For example, a typemap applied to "unsigned long **" would
also be applied to any occurrence of "DWORD **" as well.
5/19/97 : Fixed an ownership assignment bug in the Perl5 module when
class members were returning new objects belonging to
different classes.
5/17/97 : Added a few more typemap variables.
$name - Name of function/variable/member
$basetype - Base datatype (type without pointers)
$argnum - Argument number
5/16/97 : Fixed embarrassing underscore error in local variable
allocator.
5/16/97 : Fixed namespace clash bug in parameterized typemaps
when creating arrays as new local variables.
5/15/97 : Fixed some bugs with inheritance of added methods across
multiple files. SWIG now uses names of base classes
when generating such functions.
5/14/97 : Finished support for default typemaps. Primarily used
internally, they can be used to match the basic
built-in datatypes used inside of SWIG. You can
specify them in interface files as well like this :
%typemap(tcl,in) int SWIG_DEFAULT_TYPE {
$target = atoi($target);
}
Unlike normal typemaps, this default map will get applied
to *all* integer datatypes encountered, including those
renamed with typedef, etc...
5/13/97 : Fixed substring bug in type checker.
5/12/97 : Fixed bug in parameterized typemaps when declaring local
variables of structures.
Version 1.1 Beta6 (May 9, 1997)
===============================
5/9/97 : Fixed bizarre NULL pointer handling bug in Perl5 module.
5/8/97 : Fixed mysterious segmentation fault when running SWIG on an
empty file.
5/7/97 : The code generator will now replace the special symbol "$cleanup"
with the cleanup code specified with the "freearg" typemap.
This change needed to properly manage memory and exceptions.
5/5/97 : Added the 'typemaps.i' library file. This contains a
variety of common typemaps for input values, pointers,
and so on.
5/5/97 : Changed behavior of "argout" typemap in Python module.
Old versions automatically turned the result into a
Python list. The new version does nothing, leaving the
implementation up to the user. This provides more flexibility
but may break older codes that rely on typemaps.
*** POTENTIAL INCOMPATIBILITY ***
5/5/97 : Fixed bug in Python module related to the interaction of
"argout" and "ignore" typemaps.
5/5/97 : Fixed bug in Python module that would generate incorrect code
if all function arguments are "ignored".
5/4/97 : Added %apply and %clear directives. These form a higher level
interface to the typemap mechanism. In a nutshell, they
can be used to change the processing of various datatypes without
ever having to write a typemap. See the SWIG documentation
for more details. ** NEW FEATURE **
5/4/97 : Added a local variable extension to the typemap handler.
For example :
%typemap(tcl,in) double *(double temp) {
temp = atof($source);
$target = &temp;
}
In this case, 'temp' is a local variable that exists
in the entire wrapper function (not just the typemap
code). This mechanism provides better support for
certain types of argument handling and also makes it
possible to write thread-safe typemaps. Any number
local variables can be declared by supplying a comma
separated list. Local variables are guaranteed to be
unique, even if the same typemap is applied many times
in a given function.
** Not currently supported in Perl4 or Guile modules.
5/2/97 : Fixed processing of %ifdef, %endif, %if, etc... (These are
SWIG equivalents of the C preprocessor directives that
can pass through the C preprocessor without modification).
5/2/97 : Fixed major (but subtle) bug in the run-time type checker
related to searching and type-checking for C++ inheritance.
To make a long story short, if you had two classes named
"Foo" and "FooObject" the type checker would sometimes
get confused and be unable to locate "Foo" in an internal
table.
5/2/97 : Fixed some bugs in the -co option.
4/24/97 : Pointer library added to the SWIG library.
4/19/97 : Added the %new directive. This is a "hint" that can be used
to tell SWIG that a function is returning a new object. For
example :
%new Foo *create_foo();
This tells SWIG that create_foo() is creating a new object
and returning a pointer to it. Many language modules may
choose to ignore the hint, but when working with shadow classes,
the %new is used to handle proper ownership of objects.
%new can also be used with dynamically allocated strings.
For example :
%new char *create_string();
When used, all of the language modules will automatically cleanup
the returned string--eliminating memory leaks.
** NEW FEATURE **
4/19/97 : Added a new typemap "newfree". This is used in conjunction with
the %new directive and can be used to change the method by which
a new object returned by a function is deleted.
4/19/97 : The symbol "__cplusplus" is now defined in the SWIG interpreter
when running with the -c++ option.
4/17/97 : Added support for static member functions when used inside the
%addmethods directive.
4/15/97 : Added a special typemap symbol PREVIOUS that can be used to
restore a previous typemap. For example :
%typemap(tcl,in) int * = PREVIOUS;
This is primarily used in library files.
4/13/97 : Added %pragma directive for Perl5 module. Two new pragmas are
available :
%pragma(perl5) code = "string"
%pragma(perl5) include = "file.pl"
Both insert code into the .pm file created by SWIG. This can
be used to automatically customize the .pm file created by SWIG.
4/13/97 : Scanner modified to only recognize C++ keywords when the -c++
option has been specified. This provides support for C programs
that make use of these keywords for identifiers.
SWIG may need to be explicitly run with the -c++ option when
compiling C++ code (this was allowed, but not recommended in
previous versions). **POTENTIAL INCOMPATIBILITY**
4/11/97 : Fixed a rather nasty bug in the Perl5 module related to using
variable linking with complex datatypes and pointers. On Unix,
code would work (somehow), but would cause an access violation
under Windows-NT. The fix should correct the problem,
but there may still be a problem using global variables of
complex datatypes in conjunction with shadow classes. Fortunately,
this sort of thing seems to be relatively rare (considering
that the bug has been around for more than a year - yikes!).
4/11/97 : Fixed bizarre constant evaluation bug in Perl5 code generation
when running under Windows-NT.
4/8/97 : Bug when using default arguments and C++ references fixed.
4/8/97 : Fixed code generation bugs in Python and Perl5 modules related to
using class renaming (applying the %name directive to a class
definition) and shadow classes.
4/7/97 : Fixed minor bugs in swigptr.swg, tcl8ptr.swg, and perl5ptr.swg to
prevent infinite loops when weird datatypes are passed.
3/29/97 : 'Makefile.win' added. This is used to build most of the examples
in the Examples directory under Windows NT/95.
3/27/97 : Fixes to SWIG's error return codes. SWIG now returns non-zero
exit codes for certain kinds of errors (which makes it more
friendly to makefiles). An overhaul of the error handling
is on the to-do list and will probably show up in a later release.
3/25/97 : Bug fix. "freearg" and "argout" typemaps have been fixed in
the Perl5 module. In previous versions, function input parameters
and function output parameters shared the same memory space--causing
all sorts of nasty problems when trying to pass perl values by
reference. SWIG now internally makes a "copy" (which is really
just a pointer) of affected parameters and uses that. This
is done transparently so there is no noticable impact on any
SWIG generated modules. This change is probably only noticable
to expert users.
3/25/97 : Added type-check to verbose and stat mode. SWIG will now generate a list
of all datatypes that were used but undefined (useful for tracking
down weird bugs). This is enabled with the -v option (which
is now officially known as "overly verbose" mode) or the -stat option.
3/25/97 : Slight change to the parser to make include guards work correctly.
For example :
#ifndef INTERFACE_I
#define INTERFACE_I
%module foobar.i
... declarations ...
#endif
3/24/97 : %checkout directive added. This allows an interface file to
extract files from the SWIG library and place them in the
current directory. This can be used to extract scripts and
other helper code that might be associated with library files.
For example :
%checkout array.tcl
Will look for a file "array.tcl" in the library and copy it
to the current directory. If the file already exists in the
directory, this directive does nothing (it will not overwrite an
existing file). This only an experimental feature for now.
3/24/97 : SWIG will now look in the SWIG Library for a file if it can't
find it in the current directory. As a result, it is easy to
make modules from SWIG library files. For example, if you
want to make a Python module from the SWIG timers library, just
type this in any directory :
swig -python timers.i
You will get the files timers_wrap.c and timers_wrap.doc in
the current directory that you can now compile. The file
remains in the SWIG library (although you can check it out
using the -co option). *** New Feature ***
3/24/97 : -co option added to SWIG to allow easy access to the SWIG library.
When used, this instructs SWIG to check out a library file and
place it in the current directory. For example :
unix > swig -co array.i
array.i checked out from the SWIG library
unix >
Once in your directory you can customize the file to suit your
particular purposes. The checkout option makes it easy to
grab library files without knowing anything about the SWIG
installation, but it also makes it possible to start
including scripts, C code, and other miscellaneous files
in the library. For example, you could put a cool script
in the library and check it out whenever you wanted to use it.
*** New Feature ***
3/24/97 : #pragma export directives added to Tcl output for compiling
shared libraries on the Mac.
3/24/97 : Minor changes to wish.i and tclsh.i library files to provide
support for the Macintosh.
3/19/97 : SWIG's policy towards NULL pointers has been relaxed. The
policy of requiring a special compiler directive -DALLOW_NULL
to use NULL pointers is no longer supported. While this may
seem "unsafe", it turns out that you can use a "check"
typemap to achieve some safety. For example :
%typemap(perl5,check) Node * {
if (!$target)
croak("NULL Pointers not allowed.");
}
This prevents any NULL value of a "Node *" pointer to be
passed to a function. (I think this is much cleaner
than the old -DALLOW_NULL hack anyways).
3/19/97 : Fixed pointer handling errors in Perl5 module. Modules no
longer core dump when a Perl reference is inadvertently
passed in as a C pointer.
3/18/97 : Added a "check" typemap. This can be used to check the
validity of function input values. For example :
%typemap(perl5,check) int posint {
if ($target < 0)
croak("Argument is not a positive integer");
}
3/18/97 : Added an $arg variable to Tcl typemaps. This makes it easier
to return argument values by "reference".
3/18/97 : Fixed a code generation bug when using C++ references and
the %addmethods directive.
3/18/97 : Fixed a few glitches in the typemap module with respect to
chaining. For example :
%typemap(tcl,in) int {
$in // Inserts prexisting typemap
printf("Received a %d\n", $target);
}
This has been allowed for quite some time, but didn't work
if no existing typemap was defined. Now, it still doesn't
work if no existing typemap is defined, but it issues a
warning message. There is some support using default typemaps,
but none of the language modules take advantage of it. This
should be considered experimental at this time.
Version 1.1b5 Patch 1 (March 16, 1997)
======================================
3/16/97 : Fixed references bug with C++ code generation.
3/16/97 : Fixed initialization bug in the documentation system that
was causing weird problems.
3/16/97 : Fixed fatal bug with -c option in the Python module.
3/13/97 : Fixed bug in the documentation system involving the %text directive
and sorting. In the old system, %text entries would float to the
top of a section because they were "nameless". Now they are
attached to the previous declaration and will stay in the proper
location relative to the previous entry.
Version 1.1b5 (March 12, 1997)
==============================
3/11/97 : Fixed compilation problems introduced by Tcl/Tk 8.0a2.
*** INCOMPATIBILITY *** SWIG no longer works with Tcl/Tk 8.0a1.
3/10/97 : Fixed bug with ignored arguments and C++ member functions in
the Python module.
3/9/97 : Parsing bugs with nested class definitions and privately
declared nested class definitions fixed.
3/9/97 : Fixed a few minor code generation bugs with C++ classes and
constructors. In some cases, the resulting wrapper code
would not compile properly. SWIG now attempts to use
the default copy constructor instead.
3/8/97 : Added a -l option to SWIG that allows additional SWIG library files
to be grabbed without having them specified in the interface file.
This makes it easier to keep the interface file clean and move certain
options into a Makefile. For example :
swig -tcl example.i # Build a normal Tcl extension
swig -tcl -lwish.i example.i # Build it as a wish extension
# by including the 'wish.i' file.
swig -python example.i # Build a dynamically loaded extension
swig -python -lembed.i example.i # Build a static extension
These kinds of options could previously be accomplished with
conditional compilation such as :
%module example
...
#ifdef STATIC
%include embed.i
#endif
3/8/97 : Incorporated changes to Guile module to use the new gh interface
in FSF Guile 1.0. The older gscm interface used in Cygnus
Guile releases is no longer supported by SWIG.
3/8/97 : Cleaned up the Tcl Netscape plugin example. It should work with
version 1.1 of the plugin now.
3/8/97 : Added better array support to the typemap module. The keyword
ANY can now be used to match any array dimension. For example :
%typemap(tcl,in) double [ANY] {
... get an array ...
}
This will match any single-dimensional double array. The array
dimension is passed in the variables $dim0, $dim1, ... $dim9. For
example :
%typemap(tcl,in) double [ANY][ANY][ANY] {
printf("Received a double[%d][%d][%d]\n",$dim0,$dim1,$dim2);
}
Any typemap involving a specific array dimension will override any
specified with the ANY tag. Thus, a %typemap(tcl,in) double [5][4][ANY] {}
would override a double [ANY][ANY][ANY]. However, overuse of the ANY
tag in arrays of high-dimensions may not work as you expect due to
the pattern matching rule used. For example, which of the following
typemaps has precedence?
%typemap(in) double [ANY][5] {} // Avoid this!
%typemap(in) double [5][ANY] {}
3/7/97 : Fixed a number of bugs related to multi-dimensional array handling.
Typedefs involving multi-dimensional arrays now works correctly.
For example :
typedef double MATRIX[4][4];
...
extern double foo(MATRIX a);
Typecasting of pointers into multi-dimensional arrays is now
implemented properly when making C/C++ function calls.
3/6/97 : Fixed potentially dangerous bug in the Tcl Object-oriented
interface. Well, actually, didn't fix it but issued a
Tcl error instead. The bug would manifest itself as follows:
% set l [List] # Create an object
...
% set m [List -this $l] # Make $m into an object assuming $l
# contains a pointer.
# Since $m == $l, $l gets destroyed
# (since its the same command name)
% $m insert Foo
Segmentation fault # Note : the list no longer exists!
Now, an error will be generated instead of redefining the command.
As in :
% set l [List]
...
% set m [List -this $l]
Object name already exists!
Use catch{} to ignore the error.
3/3/97 : Better support for enums added. Datatypes of 'enum MyEnum'
and typedefs such as 'typedef enum MyEnum Foo;' now work.
3/3/97 : Parser modified to ignore constructor initializers such as :
class Foo : public Bar {
int a,b;
public:
Foo(int i) : a(0), b(i), Bar(i,0) { };
};
3/3/97 : Modified parser to ignore C++ exception specifications such as :
int foo(double) throw(X,Y);
3/3/97 : Added %import directive. This works exactly like %extern
except it tells the language module that the declarations are
coming from a separate module. This is usually only
needed when working with shadow classes.
3/2/97 : Changed pointer type-checker to be significantly more
efficient when working with derived datatypes. This
has been accomplished by storing type-mappings in sorted
order, using binary search schemes, and caching recently
used datatypes. For SWIG generated C++ modules that
make a large number of C function calls with derived types,
this could result in speedups of between 100 and 50000 percent.
However, due to the required sorting operation, module
loading time may increased slightly when there are lots of
datatypes.
3/2/97 : Fixed some C++ compilation problems with Python
embed.i library files.
2/27/97 : Slight change to C++ code generation to use copy constructors
when returning complex data type by value.
2/26/97 : Fixed bug in Python module with -c option.
2/26/97 : Slight tweak of parser to allow trailing comma in enumerations
such as
enum Value (ALE, STOUT, LAGER, };
2/25/97 : Fixed code generation bug in Tcl module when using the
%name() directive on a classname.
2/25/97 : Finished code-size optimization of C++ code generation with
inheritance of attributes. Inherited attributes now
only generate one set of wrapper functions that are re-used
in any derived classes. This could provide big code
size improvements in some scripting language interfaces.
2/25/97 : Perl5 module modified to support both the Unix and Windows
versions. The windows version has been tested with the
Activeware port of Perl 5.003 running under Windows 95.
The C source generated by SWIG should compile without
modification under both versions of Perl, but is now
even more hideous than before.
2/25/97 : Modified parser to allow scope resolution operation to
appear in expressions and default arguments as in :
void foo(int a = Bar::defvalue);
2/25/97 : Fixed bug when resolving symbols inside C++ classes.
For example :
class Foo {
public:
enum Value {ALE, STOUT, LAGER};
...
void defarg(Value v = STOUT);
};
2/24/97 : Fixed bug with member functions returning void *.
2/23/97 : Modified Python module to be better behaved under Windows
- Module initialization function is now properly exported.
It should not be neccessary to explicitly export this function
yourself.
- Bizarre compilation problems when compiling the SWIG wrapper
code as ANSI C under Visual C++ 4.x fixed.
- Tested with both the stock Python-1.4 distribution and Pythonwin
running under Win95.
2/19/97 : Fixed typedef handling bug in Perl5 shadow classes.
2/19/97 : Added exception support. To use it, do the following :
%except(lang) {
... try part of the exception ...
$function
... catch part of exception ...
}
$function is a SWIG variable that will be replaced by the
actual C/C++ function call in a wrapper function. Thus,
a real exception specification might look like this :
%except(perl5) {
try {
$function
} catch (char *& sz) {
... process an exception ...
} catch(...) {
croak("Unknown exception. Bailing out...");
}
}
2/19/97 : Added support for managing generic code fragments (needed
for exceptions).
2/19/97 : Fixed some really obscure typemap scoping bugs in the C++
handler.
2/18/97 : Cleaned up perlmain.i file by removing some problematic,
but seemingly unnecessary declarations.
2/18/97 : Optimized handling of member functions under inheritance.
SWIG can now use wrapper functions generated for a
base class instead of regenerating wrappers for
the same functions in a derived class. This could
make a drastic reduction in wrapper code size for C++
applications with deep inheritance hierarchies and
lots of functions.
2/18/97 : Additional methods specified with %addmethods can now
be inherited along with normal C++ member functions.
2/18/97 : Minor internal fixes to make SWIG's string handling a little
safer.
2/16/97 : Moved some code generation of Tcl shadow classes to
library files.
2/16/97 : Fixed documentation error of '-configure' method in
Tcl modules.
2/16/97 : Modified Perl5 module slightly to allow typemaps
to use Perl references.
2/12/97 : Fixed argument checking bug that was introduced by
default arguments (function calls with too many
arguments would still be executed). Functions now
must have the same number of arguments as C version
(with possibility of default/optional arguments
still supported).
2/12/97 : Fixed default argument bug in Perl5 module when
generating wrapper functions involving default
arguments of complex datatypes.
2/12/97 : Fixed typemap scoping problems. For example :
%typemap(tcl,in) double {
.. get a double ..
}
class Foo {
public:
double bar(double);
}
%typemap(tcl,in) double {
.. new get double ..
}
Would apply the second typemap to all functions in Foo
due to delayed generation of C++ wrapper code (clearly this
is not the desired effect). Problem has been fixed by
assigning unique numerical identifiers to every datatype in
an interface file and recording the "range of effect" of each
typemap.
2/11/97 : Added support for "ignore" and "default" typemaps. Only use
if you absolutely know what you're doing.
2/9/97 : Added automatic creation of constructors and destructors for
C structs and C++ classes that do not specify any sort of
constructor or destructor. This feature can be enabled by
running SWIG with the '-make_default' option or by inserting
the following pragma into an interface file :
%pragma make_default
The following pragma disables automatic constructor generation
%pragma no_default
2/9/97 : Added -make_default option for producing default constructors
and destructors for classes without them.
2/9/97 : Changed the syntax of the SWIG %pragma directive to
%pragma option=value or %pragma(lang) option=value.
This change makes the syntax a little more consistent
between general pragmas and language-specific pragmas.
The old syntax still works, but will probably be phased
out (a warning message is currently printed).
2/9/97 : Improved Tcl support of global variables that are of
structures, classes, and unions.
2/9/97 : Fixed C++ compilation problem in Python 'embed.i' library file.
2/9/97 : Fixed missing return value in perlmain.i library file.
2/9/97 : Fixed Python shadow classes to return an AttributeError when
undefined attributes are accessed (older versions returned
a NameError).
2/9/97 : Fixed bug when %addmethods is used after a class definition whose
last section is protected or private.
2/8/97 : Made slight changes in include file processing to support
the Macintosh.
2/8/97 : Extended swigmain.cxx to provide a rudimentary Macintosh interface.
It's a really bad interface, but works until something better
is written.
1/29/97 : Fixed type-casting bug introduced by 1.1b4 when setting/getting the
value of global variables involving complex data types.
1/29/97 : Removed erroneous white space before an #endif in the code generated
by the Python module (was causing errors on DEC Alpha compilers).
1/26/97 : Fixed errors when using default/optional arguments in Python shadow
shadow classes.
1/23/97 : Fixed bug with nested %extern declarations.
1/21/97 : Fixed problem with typedef involving const datatypes.
1/21/97 : Somewhat obscure, but serious bug with having multiple levels
of typedefs fixed. For example :
typedef char *String;
typedef String Name;
Version 1.1 Beta4 (January 16, 1997)
====================================
Note : SWIG 1.1b3 crashed and burned shortly after take off due
to a few major run-time problems that surfaced after release.
This release should fix most, if not all, of those problems.
1/16/97 : Fixed major memory management bug on Linux
1/14/97 : Fixed bug in functions returning constant C++ references.
1/14/97 : Modified C++ module to handle datatypes better.
1/14/97 : Modified parser to allow a *single* scope resolution
operator in datatypes. Ie : Foo::bar. SWIG doesn't
yet handle nested classes, so this should be
sufficient for now.
1/14/97 : Modified parser to allow typedef inside a C++ class.
1/14/97 : Fixed some problems related to datatypes defined inside
a C++ class. SWIG was not generating correct code,
but a new scoping mechanism and method for handling
datatypes inside a C++ class have been added.
1/14/97 : Changed enumerations to use the value name instead
of any values that might have appeared in the interface
file. This makes the code a little more friendly to
C++ compilers.
1/14/97 : Removed typedef bug that made all enumerations
equivalent to each other in the type checker (since
it generated alot of unnecessary code).
Version 1.1 Beta3 (January 9, 1997)
====================================
Note : A *huge* number of changes related to ongoing modifications.
1. Support for C++ multiple inheritance added.
2. Typemaps added.
3. Some support for nested structure definitions added.
4. Default argument handling added.
5. -c option added for building bare wrapper code modules.
6. Rewrote Pointer type-checking to support multiple inheritance
correctly.
7. Tcl 8.0 module added.
8. Perl4 and Guile modules resurrected from the dead (well, they
at least work again).
9. New Object Oriented Tcl interface added.
10. Bug fixes to Perl5 shadow classes.
11. Cleaned up many of the internal modules of the parser.
12. Tons of examples and testing modules added.
13. Fixed bugs related to use of "const" return values.
14. Fixed bug with C++ member functions returning void *.
15. Changed SWIG configuration script.
Version 1.1 Beta2 (December 3, 1996)
====================================
1. Completely rewrote the SWIG documentation system. The changes
involved are too numerous to mention. Basically, take everything
you knew about the old system, throw them out, and read the
file Doc/doc.ps.
2. Limited support for #if defined() added.
3. Type casts are now allowed in constant expressions. ie
#define A (int) 3
4. Added support for typedef lists. For example :
typedef struct {
double x,y,z;
} Vector, *VectorPtr;
5. New SWIG directives (related to documentation system)
%style
%localstyle
%subsection
%subsubsection
6. Reorganized the C++ handling and made it a little easier to
work with internally.
7. Fixed problem with inheriting data members in Python
shadow classes.
8. Fixed symbol table problems with shadow classes in both
Python and Perl.
9. Fixed annoying segmentation fault bug in wrapper code
generated for Perl5.
10. Fixed bug with %addmethods directive. Now it can be placed
anywhere in a class.
11. More test cases added to the SWIG self-test. Documentation
tests are now performed along with other things.
12. Reorganized the SWIG library a little bit and set it up to
self-document itself using SWIG.
13. Lots and lots of minor bug fixes (mostly obscure, but bugs
nonetheless).
Version 1.1 Beta1 (October 30, 1996)
====================================
1. Added new %extern directive for handling multiple files
2. Perl5 shadow classes added
3. Rewrote conditional compilation to work better
4. Added 'bool' datatype
5. %{,%} block is now optional.
6. Fixed some bugs in the Python shadow class module
7. Rewrote all of the SWIG tests to be more informative
(and less scary).
8. Rewrote parameter list handling to be more memory
efficient and flexible.
9. Changed parser to ignore 'static' declarations.
10. Initializers are now ignored. For example :
struct FooBar a = {3,4,5};
11. Somewhat better parsing of arrays (although it's
usually just a better error message now).
12. Lot's of minor bug fixes.
Version 1.0 Final (August 31, 1996)
===================================
1. Fixed minor bug in C++ module
2. Fixed minor bug in pointer type-checker when using
-DALLOW_NULL.
3. Fixed configure script to work with Python 1.4beta3
4. Changed configure script to allow compilation without
yacc or bison.
Version 1.0 Final (August 28, 1996)
===================================
1. Changed parser to support more C/C++ datatypes (well,
more variants). Types like "unsigned", "short int",
"long int", etc... now work.
2. "unions" added to parser.
3. Use of "typedef" as in :
typedef struct {
double x,y,z;
} Vector;
Now works correctly. The name of the typedef is used as
the structure name.
4. Conditional compilation with #ifdef, #else, #endif, etc...
added.
5. New %disabledoc, %enabledoc directives allow documentation
to selectively be disabled for certain parts of a wrapper
file.
6. New Python module supports better variable linking, constants,
and shadow classes.
7. Perl5 module improved with better compatibility with XS
and xsubpp. SWIG pointers and now created so that they
are compatible with xsubpp pointers.
8. Support for [incr Tcl] namespaces added to Tcl module.
9. %pragma directive added.
10. %addmethods directive added.
11. %native directive added to allow pre-existing wrapper functions
to be used.
12. Wrote configure script for SWIG installation.
13. Function pointers now allowed with typedef statements.
14. %typedef modified to insert a corresponding C typedef into
the output file.
15. Fixed some problems related to C++ references.
16. New String and WrapperFunction classes add to make generating
wrapper code easier.
17. Fixed command line option processing to eliminate core dumps
and to allow help messages.
18. Lot's of minor bug fixes to almost all code modules
Version 1.0 Beta 3 (Patch 1) July 17, 1996
==========================================
1.0 Final is not quite ready yet, but this release fixes a
number of immediate problems :
1. Compiler errors when using -strict 1 type checking have been fixed.
2. Pointer type checker now recognizes pointers of the form
_0_Type correctly.
3. A few minor fixes were made in the Makefile
Version 1.0 Beta 3 (June 14, 1996)
===================================
There are lots of changes in this release :
1. SWIG is now invoked using the "swig" command instead of "wrap".
Hey, swig sounds cooler.
2. The SWIG_LIB environment variable can be set to change the
location where SWIG looks for library files.
3. C++ support has been added. You should use the -c++ option
to enable it.
4. The %init directive has been replaced by the %module directive.
%module constructs a valid name for the initialization function
for whatever target language you're using (actually this makes
SWIG files a little cleaner). The old %init directive still works.
5. The syntax of the %name directive has been changed. Use of the
old one should generate a warning message, but may still work.
6. To support Tcl/Tk on non-unix platforms, SWIG imports a file called
swigtcl.cfg from the $(SWIG_LIB)/tcl directory. I don't have access
to an NT machine, but this file is supposedly allows SWIG to
produce wrapper code that compiles on both UNIX and non UNIX machines.
If this doesn't work, you'll have to edit the file swigtcl.cfg. Please
let me know if this doesn't work so I can update the file as
necessary.
7. The SWIG run-time typechecker has been improved. You can also
now redefine how it works by supplying a file called "swigptr.cfg"
in the same directory as your SWIG interface files. By default,
SWIG reads this file from $(SWIG_LIB)/config.
8. The documentation system has been changed to support the following :
- Documentation order is printed in interface file order by
default. This can be overridden by putting an %alpha
directive in the beginning of the interface file.
- You can supply additional documentation text using
%text %{ put your text here %}
- A few minor bugs were fixed.
9. A few improvements have been made to the handling of command line
options (but it's still not finished).
10. Lots of minor bug fixes in most of the language modules have been
made.
11. Filenames have been changed to 8.3 for compatibility with a SWIG
port to non-unix platforms (work in progress).
12. C++ file suffix is now .cxx (for same reason).
13. The documentation has been upgraded significantly and is now
around 100 pages. I added new examples and a section on
C++. The documentation now includes a Table of Contents.
14. The SWIG Examples directory is still woefully sparse, but is
getting better.
Special notice about C++
------------------------
This is the first version of SWIG to support C++ parsing. Currently
the C++ is far from complete, but seems to work for simple cases.
No work has been done to add special C++ processing to any of
the target languages. See the user manual for details about how
C++ is handled. If you find problems with the C++ implementation,
please let me know. Expect major improvements in this area.
Note : I have only successfully used SWIG and C++ with Tcl and
Python.
Notice about Version 1.0Final
-----------------------------
Version 1.0B3 is the last Beta release before version 1.0 Final is
released. I have frozen the list of features supported in version 1.0
and will only fix bugs as they show up. Work on SWIG version 2.0 is
already in progress, but is going to result in rather significant
changes to SWIG's internal structure (hopefully for the better). No
anticipated date for version 2.0 is set, but if you've got an idea,
let me know.
Version 1.0 Beta 2 (April 26, 1996)
===================================
This release is identical to Beta1 except a few minor bugs are
fixed and the SWIG library has been updated to work with Tcl 7.5/Tk 4.1.
A tcl7.5 examples directory is now included.
- Fixed a bug in the Makefile that didn't install the libraries
correctly.
- SWIG Library files are now updated to work with Tcl 7.5 and Tk 4.1.
- Minor bug fixes in other modules.
Version 1.0 Beta 1 (April 10, 1996).
=====================================
This is the first "semi-official" release of SWIG. It has a
number of substantial improvements over the Alpha release. These
notes are in no particular order--hope I remembered everything....
1. Tcl/Tk
SWIG is known to work with Tcl7.3, Tk3.6 and later versions.
I've also tested SWIG with expect-5.19.
Normally SWIG expects to use the header files "tcl.h" and "tk.h".
Newer versions of Tcl/Tk use version numbers. You can specify these
in SWIG as follows :
% wrap -htcl tcl7.4.h -htk tk4.0.h example.i
Of course, I prefer to simply set up symbolic links between "tcl.h" and
the most recent stable version on the machine.
2. Perl4
This implementation has been based on Perl-4.035. SWIG's interface to
Perl4 is based on the documentation provided in the "Programming Perl"
book by Larry Wall, and files located in the "usub" directory of the
Perl4 distribution.
In order to compile with Perl4, you'll need to link with the uperl.o
file found in the Perl4 source directory. You may want to move this
file to a more convenient location.
3. Perl5
This is a somewhat experimental implementation, but is alot less
buggy than the alpha release. SWIG operates independently of
the XS language and xsubpp supplied with Perl5. Currently SWIG
produces the necessary C code and .pm file needed to dynamically
load a module into Perl5.
To support Perl5's notion of modules and packages (as with xsubpp),
you can use the following command line options :
% wrap -perl5 -module MyModule -package MyPackage example.i
Note : In order for dynamic loading to be effective, you need to be
careful about naming. For a module named "MyModule", you'll need to
create a shared object file called "MyModule.so" using something like
% ld -shared my_obj.o -o MyModule.so
The use of the %init directive must match the module name since Perl5
calls a function "boot_ModuleName" in order to initialize things.
See the Examples directory for some examples of how to get things
to work.
4. Python1.3
This is the first release supporting Python. The Python port is
experimental and may be rewritten. Variable linkage is done through
functions which is sort of a kludge. I also think it would be nice
to import SWIG pointers into Python as a new object (instead of strings).
Of course, this needs a little more work.
5. Guile3
If you really want to live on the edge, pick up a copy of Guile-iii and
play around with this. This is highly experimental---especially since
I'm not sure what the official state of Guile is these days. This
implementation may change at any time should I suddenly figure out better
ways to do things.
6. Extending SWIG
SWIG is written in C++ although I tend to think of the code as mostly
being ANSI C with a little inheritance thrown in. Each target language
is implemented as a C++ class that can be plugged into the system.
If you want to add your own modifications, see Appendix C of the user
manual. Then take a look at the "user" directory which contains some
code for building your own extenions.
7. The SWIG library
The SWIG library is still incomplete. Some of the files mentioned in
the user manual are unavailable. These files will be made available
when they are ready. Subscribe to the SWIG mailing list for announcements
and updates.
8. SWIG Documentation
I have sometimes experienced problems viewing the SWIG documentation in
some postscript viewers. However, the documentation seems to print
normally. I'm working on making much of the documentation online,
but this takes time.
Version 0.1 Alpha (February 9, 1996)
====================================
1. Run-time type-checking of SWIG pointers. Pointers are now represented
as strings with both numeric and encoded type information. This makes
it a little harder to shoot yourself in the foot (and it eliminates
some segmentation faults and other oddities).
2. Python 1.3 now supported.
3. #define and enum can be used to install constants.
4. Completely rewrote the %include directive and made it alot more powerful.
5. Restructured the SWIG library to make it work better.
6. Various bug fixes to Tcl, Perl4, Perl5, and Guile implementations.
7. Better implementation of %typedef directive.
8. Made some changes to SWIG's class structure to make it easier to expand.
SWIG is now built into a library file that you can use to make your
own extenions.
9. Made extensive changes to the documentation.
10. Minor changes to the SWIG parser to make it use less memory.
Also took out some extraneous rules that were undocumented and
didn't work in the first place.
11. The SWIG library files "tclsh", "wish", "expect", etc... in the first
release have been restructured and renamed to "tclsh.i", "wish.i",
and so on.
