diff --git a/ANNOUNCE b/ANNOUNCE index 1a13e074f..6f0247f56 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -1,8 +1,8 @@ -*** ANNOUNCE: SWIG 2.0.4 (29 March 2011) *** +*** ANNOUNCE: SWIG 2.0.5 (in progress) *** http://www.swig.org -We're pleased to announce SWIG-2.0.4, the latest SWIG release. +We're pleased to announce SWIG-2.0.5, the latest SWIG release. What is SWIG? ============= @@ -21,11 +21,11 @@ Availability ============ The release is available for download on Sourceforge at - http://prdownloads.sourceforge.net/swig/swig-2.0.4.tar.gz + http://prdownloads.sourceforge.net/swig/swig-2.0.5.tar.gz A Windows version is also available at - http://prdownloads.sourceforge.net/swig/swigwin-2.0.4.zip + http://prdownloads.sourceforge.net/swig/swigwin-2.0.5.zip Please report problems with this release to the swig-devel mailing list, details at http://www.swig.org/mail.html. diff --git a/CHANGES b/CHANGES index 7e930159e..185d57d45 100644 --- a/CHANGES +++ b/CHANGES @@ -3,6 +3,123 @@ SWIG (Simplified Wrapper and Interface Generator) See the CHANGES.current file for changes in the current version. See the RELEASENOTES file for a summary of changes in each release. +Version 2.0.4 (21 May 2011) +=========================== + +2011-05-19: wsfulton + [Guile] Patch #3191625 fixing overloading of integer types. + +2011-05-19: wsfulton + [Perl] Patch #3260265 fixing overloading of non-primitive types and integers in + Perl 5.12 and later. + +2011-05-19: wsfulton + [Ruby] Fix %import where one of the imported files %include one of the STL include + files such as std_vector.i. + +2011-05-17: wsfulton + [Java] Apply #3289851 from Alan Harder to fix memory leak in directors when checking + for pending exceptions. + +2011-05-17: wsfulton + [Tcl] Apply #3300072 from Christian Delbaere to fix multiple module loading not + always sharing variables across modules. + +2011-05-16: xavier98 + [octave] Fix an incompatibility with never versions of Octave. Case on Octave + API >= 40 to handle rename of Octave_map to octave_map. + [octave] Add support for y.__rop__(x) operators when x.__op__(y) doesn't exist. + [octave] Allow global operators to be defined by SWIG-wrapped functions. + [octave] Fix several bugs around module namespaces; add -global, -noglobal, + -globals command line options to the module. + +2011-05-14: wsfulton + %varargs when used with a numeric argument used to create an additional argument + which was intended to provide a guaranteed sentinel value. This never worked and now + the additional argument is not generated. + +2011-05-13: wsfulton + [python] Additional fixes for python3.2 support. + +2011-05-07: szager + [python] Fixed PyGetSetDescr for python3.2. + +2011-05-05: wsfulton + [Lua, Python, Tcl] C/C++ prototypes shown in error message when calling an overloaded + method with incorrect arguments improved to show always show fully qualified name + and if a const method. + + Also fixed other Lua error messages in generated code which weren't consistently + using the fully qualified C++ name - requested by Gedalia Pasternak. + +2011-04-29: szager + Bug 2635919: Convenience method to convert std::map to a python dict. + +2011-04-29: szager + [Python] Fixed bug 2811549: return non-const iterators from STL + methods begin(), end(), rbegin(), rend(). + +2011-04-25: szager + [Python] Fixed bug 1498929: Access to member fields in map elements + +2011-04-23: klickverbot + [D] nspace: Correctly generate identifiers for base classes when + not in split proxy mode. + +2011-04-13: szager + Fixed bug 3286333: infinite recursion with mutual 'using namespace' clauses. + +2011-04-12: szager + Fixed bug 1163440: vararg typemaps. + +2011-04-12: szager + Fixed bug #3285386: parse error from 'operator T*&()'. Added operator_pointer_ref + test case to demonstrate. + +2011-04-11: szager + [Python] Fixed PyVarObject_HEAD_INIT to eliminate VC++ compiler errors about + static initialization of struct members with pointers. + +2011-04-11: wsfulton + [Tcl] Apply patch #3284326 from Colin McDonald to fix some compiler warnings. + +2011-04-11: szager + [Python] Fixed PyVarObject_HEAD_INIT to eliminate VC++ compiler errors about + static initialization of struct members with pointers. + +2011-04-10: klickverbot + [D] Fixed wrapping of enums that are type char, for example: + enum { X = 'X'; } (this was already in 2.0.3 for C# and Java) + +2011-04-10: klickverbot + [D] nspace: Fixed referencing types in the root namespace when + not in split proxy mode. + +2011-04-09: szager + [Python] Applied patch #1932484: migrate PyCObject to PyCapsule. + +2011-04-09: szager + [Python] Added preprocessor guards for python functions PyUnicode_AsWideChar and + PySlice_GetIndices, which changed signatures in python3.2. + +2011-04-07: wsfulton + Fix wrapping of const array typedefs which were generating uncompileable code as + reported by Karl Wette. + +2011-04-03: szager + [Python] Fixed the behavior of %pythonnondynamic to conform to the spec in Lib/pyuserdir.swg. + +2011-04-03: szager + [Python] Merged in the szager-python-builtin branch, adding the -builtin feature + for python. The -builtin option may provide a significant performance gain + in python wrappers. For full details and limitations, refer to Doc/Manual/Python.html. + A small test suite designed to demonstrate the performance gain is in + Examples/python/performance. + +2011-04-01: wsfulton + Add in missing wrappers for friend functions for some target languages, mostly + the non-scripting languages like Java and C#. + Version 2.0.3 (29 March 2011) ============================= diff --git a/CHANGES.current b/CHANGES.current index f928203d8..3fab761b8 100644 --- a/CHANGES.current +++ b/CHANGES.current @@ -1,81 +1,13 @@ -This file contains the changes for the current release. +Below are the changes for the current release. See the CHANGES file for changes in older releases. See the RELEASENOTES file for a summary of changes in each release. -Version 2.0.4 (in progress) +Version 2.0.5 (in progress) =========================== -2011-05-05: wsfulton - [Lua, Python, Tcl] C/C++ prototypes shown in error message when calling an overloaded - method with incorrect arguments improved to show always show fully qualified name - and if a const method. - Also fixed other Lua error messages in generated code which weren't consistently - using the fully qualified C++ name - requested by Gedalia Pasternak. +2011-05-30: olly + [PHP] Fix handling of directors when -prefix is used. -2011-04-29: szager - Bug 2635919: Convenience method to convert std::map to a python dict. +2011-05-24: olly + [PHP] Fix handling of methods of classes with a virtual base class (SF#3124665). -2011-04-29: szager - Fixed bug 2811549: return non-const iterators from STL - methods begin(), end(), rbegin(), rend(). - -2011-04-25: szager - Fixed bug 1498929: Access to member fields in map elements - -2011-04-23: klickverbot - [D] nspace: Correctly generate identifiers for base classes when - not in split proxy mode. - -2011-04-13: szager - Fixed bug 3286333: infite recursion with mutual 'using namespace' clauses. - -2011-04-12: szager - Fixed bug 1163440: vararg typemaps. - -2011-04-12: szager - Fixed bug #3285386: parse error from 'operator T*&()'. Added operator_pointer_ref - test case to demonstrate. - -2011-04-11: szager - Fixed PyVarObject_HEAD_INIT to eliminate VC++ compiler errors about - static initialization of struct members with pointers. - -2011-04-11: wsfulton - [Tcl] Apply patch #3284326 from Colin McDonald to fix some compiler warnings. - -2011-04-11: szager - Fixed PyVarObject_HEAD_INIT to eliminate VC++ compiler errors about - static initialization of struct members with pointers. - -2011-04-10: klickverbot - [D] Fixed wrapping of enums that are type char, for example: - enum { X = 'X'; } (this was already in 2.0.3 for C# and Java) - -2011-04-10: klickverbot - [D] nspace: Fixed referencing types in the root namespace when - not in split proxy mode. - -2011-04-09: szager - Applied patch #1932484: migrate PyCObject to PyCapsule. - -2011-04-09: szager - Added preprocessor guards for python functions PyUnicode_AsWideChar and - PySlice_GetIndices, which changed signatures in python3.2. - -2011-04-07: wsfulton - Fix wrapping of const array typedefs which were generating uncompileable code as - reported by Karl Wette. - -2011-04-03: szager - Fixed the behavior of %pythonnondynamic to conform to the spec in Lib/pyuserdir.swg. - -2011-04-03: szager - Merged in the szager-python-builtin branch, adding the -builtin feature - for python. The -builtin option may provide a significant performance gain - in python wrappers. For full details and limitations, refer to Doc/Manual/Python.html. - A small test suite designed to demonstrate the performance gain is in - Examples/python/performance. - -2011-04-01: wsfulton - Add in missing wrappers for friend functions for some target languages, mostly - the non-scripting languages like Java and C#. diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 74a201bc6..b53923c17 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -764,6 +764,8 @@
  • Go Templates
  • Go Director Classes
  • Default Go primitive type mappings +
  • Output arguments +
  • Adding additional go code @@ -1332,6 +1334,11 @@
  • Further details on the Python class interface @@ -1684,4 +1691,3 @@ - diff --git a/Doc/Manual/Extending.html b/Doc/Manual/Extending.html index c6e006033..ff666791c 100644 --- a/Doc/Manual/Extending.html +++ b/Doc/Manual/Extending.html @@ -2754,15 +2754,16 @@ int Python::top(Node *n) {

    -Within SWIG wrappers, there are four main sections. These are (in order) +Within SWIG wrappers, there are five main sections. These are (in order)

    Different parts of the SWIG code will fill different sections, diff --git a/Doc/Manual/Go.html b/Doc/Manual/Go.html index 8681927c3..8c072e00a 100644 --- a/Doc/Manual/Go.html +++ b/Doc/Manual/Go.html @@ -28,6 +28,8 @@

  • Go Templates
  • Go Director Classes
  • Default Go primitive type mappings +
  • Output arguments +
  • Adding additional go code @@ -273,7 +275,7 @@ class.

    SWIG will represent static methods of C++ classes as ordinary Go -functions. SWIG will use names like ClassName_MethodName. +functions. SWIG will use names like ClassNameMethodName. SWIG will give static members getter and setter functions with names like GetClassName_VarName.

    @@ -289,6 +291,37 @@ to reinterpret_cast. This should only be used for very special cases, such as where C++ would use a dynamic_cast.

    +

    Note that C++ pointers to compound objects are represented in go as objects +themselves, not as go pointers. So, for example, if you wrap the following +function:

    +
    +
    +class MyClass {
+  int MyMethod();
+  static MyClass *MyFactoryFunction();
+};
+
+
    +
    +

    You will get go code that looks like this:

    +
    +
    +type MyClass interface {
+  Swigcptr() uintptr
+  SwigIsMyClass()
+  MyMethod() int
+}
+
+MyClassMyFactoryFunction() MyClass {
+  // swig magic here
+}
+
    +
    +

    Note that the factory function does not return a go pointer; it actually +returns a go interface. If the returned pointer can be null, you can check +for this by calling the Swigcptr() method. +

    +

    21.3.5.1 Go Class Inheritance

    @@ -459,5 +492,130 @@ that typemap, or add new values, to control how C/C++ types are mapped into Go types.

    +

    21.3.9 Output arguments

    + + +

    Because of limitations in the way output arguments are processed in swig, +a function with output arguments will not have multiple return values. +Instead, you must pass a pointer into the C++ function to tell it where to +store the ouput value. In go, you supply a slice in the place of the output +argument.

    + +

    For example, suppose you were trying to wrap the modf() function in the +C math library which splits x into integral and fractional parts (and +returns the integer part in one of its parameters):

    +

    +
    +double modf(double x, double *ip);
+
    +
    +

    You could wrap it with SWIG as follows:

    +
    +
    +%include <typemaps.i>
+double modf(double x, double *OUTPUT);
+
    +
    +

    or you can use the %apply directive:

    +
    +
    +%include <typemaps.i>
+%apply double *OUTPUT { double *ip };
+double modf(double x, double *ip);
+
    +
    +

    In Go you would use it like this:

    +
    +
    +ptr := []float64{0.0}
+fraction := modulename.Modf(5.0, ptr)
+
    +
    +

    Since this is ugly, you may want to wrap the swig-generated API with +some additional functions written in go that +hide the ugly details.

    + +

    There are no char *OUTPUT typemaps. However you can +apply the signed char * typemaps instead:

    +

    +
    +%include <typemaps.i>
+%apply signed char *OUTPUT {char *output};
+void f(char *output);
+
    +
    + +

    21.3.10 Adding additional go code

    + +

    Often the APIs generated by swig are not very natural in go, especially if +there are output arguments. You can +insert additional go wrapping code to add new APIs +with %insert(go_wrapper), like this:

    +
    +
    +%include <typemaps.i>
+// Change name of what swig generates to Wrapped_modf.  This function will
+// have the following signature in go:
+//   func Wrapped_modf(float64, []float64) float64
+%rename(wrapped_modf) modf(double x, double *ip);
+
+%apply double *OUTPUT { double *ip };
+double modf(double x, double *ip);
+
+%insert(go_wrapper) %{
+
+// The improved go interface to this function, which has two return values,
+// in the more natural go idiom:
+func Modf(x float64) (fracPart float64, intPart float64) {
+  ip := []float64{0.0}
+  fracPart = Wrapped_modf(x, ip)
+  intPart = ip[0]
+  return
+}
+
+%}
+
    +
    + +

    For classes, since swig generates an interface, you can add additional +methods by defining another interface that includes the swig-generated +interface. For example,

    +
    +
    +%rename(Wrapped_MyClass) MyClass;
+%rename(Wrapped_GetAValue) MyClass::GetAValue(int *x);
+%apply int *OUTPUT { int *x };
+
+class MyClass {
+ public:
+  MyClass();
+  int AFineMethod(const char *arg); // Swig's wrapping is fine for this one.
+  bool GetAValue(int *x);
+};
+
+%insert(go_wrapper) %{
+
+type MyClass interface {
+  Wrapped_MyClass
+  GetAValue() (int, bool)
+}
+
+func (arg SwigcptrWrapped_MyClass) GetAValue() (int, bool) {
+  ip := []int{0}
+  ok := arg.Wrapped_GetAValue(ip)
+  return ip[0], ok
+}
+
+%}
+
    +
    +

    Of course, if you have to rewrite most of the methods, instead of just a +few, then you might as well define your own struct that includes the +swig-wrapped object, instead of adding methods to the swig-generated object.

    + +

    This only works if your wrappers do not need to import other go modules. +There is at present no way to insert import statements in the correct place +in swig-generated go. If you need to do that, you must put your go code +in a separate file.

    diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index fac680825..07f9e87d7 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -43,7 +43,11 @@
  • Further details on the Python class interface @@ -2210,7 +2214,7 @@ unacceptable for a high-performance library. The new -builtin option instructs SWIG to forego the use of proxy classes, and instead create wrapped types as new built-in Python types. When this option is used, the following section ("Proxy classes") does not apply. Details on the use of -the -builtin option are in the Built-in Classes +the -builtin option are in the Built-in Types section.

    @@ -2303,7 +2307,8 @@ you can attach new Python methods to the class and you can even inherit from it by Python built-in types until Python 2.2).

    -

    33.4.2 Built-in Classes

    +

    33.4.2 Built-in Types

    +

    The -builtin option provides a significant performance improvement @@ -2346,23 +2351,26 @@ please refer to the python documentation:

    http://docs.python.org/extending/newtypes.html

    -

    33.4.2.1 Limitations

    +

    33.4.2.1 Limitations

    +

    Use of the -builtin option implies a couple of limitations:

    -

    - -

    -To illustrate the last point, if you have a wrapped class called MyString, +

  • Reverse binary operators (e.g., __radd__) are not supported.

    +

    To illustrate this point, if you have a wrapped class called MyString, and you want to use instances of MyString interchangeably with native python -strings, you can define an 'operator+ (const char*)' method : -

    +strings, you can define an 'operator+ (const char*)' method :

    @@ -2472,8 +2475,52 @@ episode = "Dead " + mystr
 The above code fails, because the first operand -- a native python string --
 doesn't know how to add an instance of MyString to itself.
 
    
+
    • + +

  • If you have multiple SWIG modules that share type information (more info), +the -builtin option requiress a bit of extra discipline to ensure that base classes are initialized before derived classes. Specifically:

    + + +

    As an example, suppose module A has this interface in A.i :

    + +
    +%module "A";
+
+class Base {
+...
+};
+
    + +

    If you want to wrap another module containing a class that inherits from A, this is how it would look :

    + +
    +%module "B";
+
+%import "A.i"
+
+class Derived : public Base {
+...
+};
+
    + +

    The import "A.i" statement is required, because module B depends on module A.

    + +

    As long as you obey these requirements, your python code may import the modules in any order :

    + +
    +import B
+import A
+
+assert(issubclass(B.Derived, A.Base))
+
    +
    • + + +

    33.4.2.2 Operator overloads -- use them!

    -

    33.4.2.2 Operator overloads -- use them!

    The entire justification for the -builtin option is improved performance. To that end, the best way to squeeze maximum performance out @@ -2491,10 +2538,10 @@ slot entries. For example, suppose you have this class: 

     class Twit {
 public:
-    Twit operator+ (const Twit& twit) const;
+    Twit operator+ (const Twit& twit) const;
 
     // Forward to operator+
-    Twit add (const Twit& twit) const
+    Twit add (const Twit& twit) const
     { return *this + twit; }
 };
    @@ -2575,6 +2622,7 @@ structs.

    33.4.3 Memory management

    +

    NOTE: Although this section refers to proxy objects, everything here also applies when the -builtin option is used.

    @@ -5257,7 +5305,8 @@ all overloaded functions share the same function in SWIG generated proxy class.

    -For detailed usage of function annotation, see PEP 3107. +For detailed usage of function annotation, see +PEP 3107.

    33.12.2 Buffer interface

    @@ -5449,7 +5498,8 @@ used to define an abstract base class for your own C++ class:

    -For details of abstract base class, please see PEP 3119. +For details of abstract base class, please see +PEP 3119.

    diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index fd510f2a4..bcfcc60f5 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -3034,14 +3034,15 @@ output of SWIG is structured first.

    -When SWIG creates its output file, it is broken up into four sections +When SWIG creates its output file, it is broken up into five sections corresponding to runtime code, headers, wrapper functions, and module initialization code (in that order).