SWIG TO-DO

Release: SWIG-1.3.20

$Header: /cvsroot/SWIG/TODO,v 1.37 2003/12/28 21:49:16 cheetah Exp $
-----------------------------------------------------------------------------

****    = High Priority
***     = Implement if possible.
**      = Will implement if time.
*       = Implement if bored (or deemed necessary).

defer   = Implement in next version

CORE:

****   Add support for nested classes.   The type system should be
defer  ready to go.  The primary obstacle lies in the target language
       modules (which were never programmed with nested classes in
       mind).  There are also issues with nested C structures.  For
       example:

             struct Foo {
                 struct {
                     int x,y;
                 } z;
             };

       This is one of the last remaining "hard" problems in the SWIG
       core, but it is important that we solve it.

****   Typemap environments.  Stay tuned.

[DONE] Merge "in" and "ignore" typemaps into a single "in" typemap.
       This would solve a variety of subtle problems with multiple
       argument typemaps and other typemap code.   I propose to merge
       the typemaps by making "ignore" a typemap attribute.
       For example:

           %typemap(in,ignore="1") int *OUTPUT (int temp) {
                $1 = &temp;
           }

       This merging makes a lot of sense because "in" and "ignore"
       typemaps both deal with input argument handling and they are
       meant to be mutually exclusive of each other.   By unifying
       into a single typemap, you fix the mutual exclusion problem
       (since there is only one typemap).  I also think it makes
       more sense to think of an "ignored" argument as a input value
       property.

       Update: Matthias proposes a generalization in which the
       number of input arguments could be specified.  For example:

           %typemap(in,numinputs="0") int *OUTPUT (int temp) {
                $1 = &temp;
           }

       This seems to be a better solution.


****   Implement "throws" typemaps for all of the target languages.
       Partly implemented for Tcl, Perl, Python, Ruby, Java.

***    "Nested" typemaps. The basic idea is similar to allowing one to 
       use $descriptor(T) for any T, rather than just $descriptor
       for the type currently being typemapped.

       In short (ha!), given a previously defined typemap:

       %typemap(in) Foo {
           // whatever it takes to initialize $1 from $input
       }

       it would be possible to inline its code inside another typemap. 
       While the syntax is still to be defined, the use would be
       along the lines of:

       template <class T> class vector {
           %typemap(in) vector<T> {
               ...
               for (int i=0; i<N; i++) {
                   PyObject* x = ... // i-th element
                   $typemap(in, T, x, $1[i]);
               }
               ...
           }
           ...
       }

       i.e., when $typemap(in,Foo,x,y) is encountered, it will
       be replaced by the code for %typemap(in) Foo; in the latter,
       x will be replaced for $input and y will be replaced for $1. 
       As in the case above, x and y themselves might need to be 
       expanded before or after being substituted in the typemap code.
       Also, $typemap(what,Foo,x,y,z,...) will be used in case of 
       multi-arguments typemaps. The same will hold for "out" typemaps
       and all the others.

       Comment by mkoeppe:  

	  I think we need to be careful to keep the syntax readable.
	  I would like to get a syntax that is close to that of
	  typemap definitions.  So consider this typemap:

		 %typemap(in) int { ... }

	  I would like to refer to this typemap like this:

		 $typemap(in, input=x) int = foo;

	  Here $input would be replaced by the given keyword argument
	  x, and $1 would be replaced by foo.

	  This syntax would extend easily to multi-typemaps:

		 %typemap(in) ( int FIRST, double SECOND ) { ... }

	      -> $typemap(in, input=x) 
	      	    ( int FIRST = foo, double SECOND = bar );

	  The advantage of this syntax would be that the formal
	  arguments (int FIRST, double SECOND) are close to the
	  actual arguments (foo, bar).

	Comment by beazley

               $typemap(in, input=x) int = foo;

        is a little bit hard to parse in terms of variable substitution.
        I'm considering something like this:

               $typemap(in,1=int foo, input=x)

***    Add attributes to the %feature directive. Something like:

       %feature("except", throws="OutOfMemoryException")

***    Implement $fail special variable substitution in wrappers. Used
       to properly transfer control out of a wrapper function while
       reclaiming resources.

***    Better targeting of output typemaps. For example:
       It is not possible to target an output typemap for function
       Foo::func() and not Bar::func(). Output typemaps need to support
       syntax something along the lines of:

             %typemap(out) int *Foo::func { ... }

***    Rewrite declaration annotation to better unify %rename and related
       directives.  Add a selector mechanism that allows specific parse tree
       nodes to be identified.  For example:

             %feature("foo", nodetype="class") Foo { ... some code ... };

       Also desirable for the Java module to specify the classes to go in the
       throw clause:

             %feature("except", throws="OutOfMemoryException") Foo {
                ... code which throws the OutOfMemoryException ...
             };

       Consider use of wildcards.   Namespace/nested scope support in
       %feature is currently weak.  It works, but is fragile.  Consider
       an implementation that is better integrated with symbol table
       management.  Continue to consolidate SWIG directives to %feature.

***    Bring Aquinas' contract/assertion checking code online.

***    Add more intelligent information related to object ownership.
       SWIG should be able to automatically strip ownership from
       objects when they are assigned to pointer variables and structure
       members as well as stored in a container (i.e., an array of pointers).

       [ Partially finished for Tcl/Python. ]

[DONE] Modify smart pointer handling to properly handle inheritance.  For
       example:

            %ignore Foo;

            class Foo {
            public:
                Blah *operator->();
            };

            class Bar : public Foo {
            }

       Bar should still allow access to Blah * through operator->().

[DONE] Virtual function optimization.  If you have two classes like this:

          class Foo {
          public:
                virtual int blah(int);
          };

          class Bar : public Foo {
          public:
                virtual int blah(int);
          };

       Then SWIG ought to be able to reuse the wrapper for Foo::blah as
       Bar::blah.   This should result in much smaller extension modules.

       This feature is now enabled using the -fvirtual option.

**     Restoration of the documentation system.

**     Restoration of Objective-C support.

**     Unification of symbol tables and type system scopes.  In a sense
       they capture the same information so it is not necessary to have
       both.  The existence of two symbol management systems is mostly
       historical.

**     Add a warning for uninstantiated templates.  For example, if a function
       using a template type, but that type hasn't been instantiated using
       %template.

*      Fix template partial specialization matching rules.   SWIG does not
       implement the proper C++ type deduction rules, but it does handle
       the most common cases.   This is likely to be hard and implementing
       it would really only be for completeness.

Build
-----

****   Make sure there are tests for *ALL* library files in the test-suite.
       A number of files appear to be broken in SWIG-1.3.13.

[DONE] Move the Source/Modules1.1 directory into the Source/Modules directory
       and deprecate Modules1.1.

Library
-------

****   Add more support for the C++ standard library.  std::complex and other
       core datatypes.   Refine support for STL vector.   Add more STL objects.

****   Continue to expand the set of recognized typemaps.

Windows
-------

[DONE] Visual C++ Project files / Makefiles for building the runtime libraries.
       Will require libtool mods to work under Cygwin.

All language modules
--------------------

Python
------

***    Ability to wrap certain classes as Python built-in types.

Perl
----

****   Rewrite runtime pointer type checking to better integrate
       shadow classes.   Creation of shadow classes should be done
       in C instead of Perl.   This will fix a number of problems
       related to typemaps and reduce the amount of Perl wrapper code.

****   Create tests for existing support for operator overloading

Tcl
---

Ruby
----

****   Add Ruby support for Mark Rose's polymorphism code.

****   The "Resource Management in Proxies" section of the "SWIG and C++"
       chapter discusses how proxies' ownership of their associated C++
       object can change, and the use of the special disown() and
       acquire() methods to change this ownership status. Need to
       address this for Ruby as well.

[DONE] Investigate the new object allocation framework that has been
       implemented for Ruby 1.8 and determine what (if anything) needs
       to be changed for the wrapper code generated by SWIG. For background
       see ruby-talk messages 23358 and 38856 (and related threads).

***    Add support for keyword arguments (by collecting them in a hash?).

[DONE] Add support for defining nested modules. This should work like it does
       for the SWIG Perl module.

[DONE] In a post to the SWIG users' mailing list (June 5: "Multiple Inheritance
       and Ruby"), Brett Williams suggested a workaround for supporting
       multiple inheritance in the Ruby module. I'm quoting it here since
       the idea may be best implemented at the core level for reuse by other
       language modules that have limited support for MI:

       """
       While it makes for longer generated wrapper code, you can easily
       generate wrappers as Ruby methods on the derived class in these cases,
       i.e.:

	   class Base1;
	   class Base2;
	   class Derived : public Base1, public Base2;
	   class OtherDerived : public Base2;

       This would mean that for class Derived, the methods for Base2 would be
       generated as methods on class Derived as opposed to a superclass. For
       class OtherDerived, things work as normal, and any other derived class
       from Base2 would still work as they currently are, unless other derived
       classes also use MI. The exception and extra wrapper generation would
       only kick in with the use of multiple inheritance where the base class
       information is available to SWIG.

       The feature could be turned on and off, and doesn't have to be default
       if necessary.

       I was under the impression that the Tcl module, until a few releases ago,
       did all inheritance this way (generating wrappers for superclass methods
       in all derived classes). It does bloat the wrapper code, but in this case
       it would only be causing more bloat in cases where the alternative is
       no support.

       What is missing with this? Hmmmm... if Base2 implements a method that is
       overridden by Derived, then you could not get at Base2::Method() via the
       super keyword... what else am I missing? Again, the alternative is no
       support for MI at all unless you want to get fancy with mixins. I'm not
       sure how good of an idea that is or even if it is workable.
       """

       Another problem (which we can't really get around anyways) is that
       basic inheritance relationships wouldn't be true at the Ruby level,
       e.g. Derived#is_a?(Base1) would return true but Derived#is_a?(Base2)
       would return false.

*      Add some special directives to automatically rename declarations to
       or from CamelCase.

[DONE] Consider adding a switch to define everything in the global (Kernel)
       module instead of nested in a user-defined module, but only if
       it comes up.

Java
----

****   Default argument support. Default arguments are effectively ignored 
       at present. An overridden method for each default argument could be 
       generated thereby enabling one to call methods with default arguments.

[DONE] Implement idea from Dave Dribin email to the swig mailing list, 2 April 2003, 
       where the global enums and constants are placed in an interface so that they 
       can be implemented by other Java classes. This will allow improved syntax when
       referring to the enums/constants:
         int foo = enumname;
       instead of
         int foo = ModuleName.enumname;

C#
--

[DONE] Need a way to throw a C# exception from the PINVOKE C/C++ code.

[DONE] The correct override/virtual keywords not always emitted for polymorphic
       methods. It currently works with 'virtual' is specified in a derived 
       C++ class function. A polymorphic method need not specify 'virtual' in C++.

****   Wrap C/C++ enums with C# enums, currently they are wrapped with a C# int.

****   Implement director support for C# so that virtual methods work seemlessly
       when mixing C# and C++ code.

PHP
---

**     When returning wrapped objects via alternate constructors if that
       pointer value already exists "out there" as a resource we should
       use the same resource, we can't have multiple ref-counted resources
       mapping to the same object in case it gets twice destroyed.  And check
       if ref count destroying is even working, see smart_pointer_rename

*      Work out how classes without even inherited constructors should
       interact with the php "new <class>" notation.
       See: abstract_inherit_wrap.cpptest

**     Look at pass by point and passby ref,
       Make sometype** to be auto allocated
       Make sometype& and sometype* to be autoallocated IF THEY ARE NOT
       ALREADY swigtype wrapped.

*      Overloading, callbacks, really review to see what else is missed

Guile
-----

**     Maybe rename slot setters from CLASS-SLOT-set to CLASS-SLOT-set!
       to match Scheme convention for naming of mutators.

**     Support keyword args.

[DONE] Support GOOPS shadow classes.

**     Director Support!

**     Cleaner handling of multiple values.
       Use a typemap keyword argument "numoutputs" of "out" and
       "argout" to indicate how many values are returned.

[DONE] Support garbage collection.

**     Make SWIG's types first-class by using a separate smob type for
       SWIG type descriptors; enable reflection on types.  (Maybe
       GOOPS metaclasses?)

**     Maybe communicate the type system between object modules via Scheme
       variables, rather than a shared object.  This would remove the
       need of a shared SWIG runtime library.

**     Provide a clean way to construct type predicates.

**     In GOOPS mode, maybe make overloaded functions methods. 

**     Increase the safety of destructor functions.  John Lenz suggests:

	  I think the best way of doing this would be to use %feature to mark  
	  which classes allow for "normal" <swig> smobs to be deleted explicitly.

	  We separate pointers into two classes, those that can be deleted from  
	  scheme and those that can't.  The pointers that can be deleted use the
	  <collectable-swig> smob and those that can not be deleted use the  
	  <swig> smob.  A user can specify which type of each object they want  
	  with %newobject and the CONSUMED typemap.

	  By default, the exported destructor will only accept <collectable-swig>  
	  smobs, because by definition, collectable-swig smobs are those that can  
	  be deleted from scheme.  This allows for the user to implement  
	  protection.  In the interface file, the user has complete control over  
	  which objects can and can not be deleted, and can guarantee that  
	  objects that should not be deleted can not be deleted, and that objects  
	  that should eventually be deleted will be garbage collected.

	  This protection can then be overridden with a %feature directive,  
	  something like

	  %feature("guile_allow_destroy_all","1") Foo::~Foo;

	  I don't know what word we want to use, guile_allow_destroy_all is kinda  
	  bad.  This feature would then allow for a <swig Foo *> smob to be  
	  deleted by passing it to the destructor.  This would allow users to  
	  maintain the protection on other classes, only manually overriding the  
	  protection on the classes that need it.


Mzscheme
--------

**     Port list-vector.i and pointer-in-out.i from Guile.

**     Add shadow class support for the Swindle system. 

Pike
----

*      Decide how to handle global variables (probably using something
       like the Python module's cvar). Affects Examples/pike/simple.

*      Decide how to handle static class member functions and member
       variables.

*      Should investigate the possibility of generating .cmod files
       in addition to straight C/C++ code for extensions.

Common Lisp
-----------

*      Random thoughts by mkoeppe on supporting Common Lisp implementations:

       There are many different Foreign Function Interfaces (FFI) for
       the various CL implementations.  Probably SWIG should interface
       to UFFI, a least-common-denominator FFI that supports many
       implementations.

       Via the s-expression SWIG module we can export SWIG's parse
       tree and import it into CL.  It remains to check if all
       relevant information is dumped (for instance, the type
       information).  Experimental code is available to generate
       low-level UFFI declarations from this parse tree.

       However, for wrapping C++, we also need to create C wrappers
       because most FFIs cannot directly import C++.  A CL SWIG module
       could be exporting both these wrappers and UFFI declarations.
       I have experimental code (not checked in yet) that does this.

       This is fine for generating low-level wrappers. But how do we
       support user typemaps (like converting lists and vectors to C
       arrays on input)?  We have to generate Lisp code that does the
       conversion and then calls the low-level wrapper.  If we
       generate Lisp code, it should be beautiful and readable.
       Therefore, we need at least a Lisp pretty printer.  A Lisp
       pretty printer works best when the Lisp program is represented
       not as text but as Lisp data.  Moreover, typemap writers will
       feel very much constrained by SWIG's capabilities for
       generating wrapper code, when compared to writing Lisp macros.
       Thus we would need half a re-implementation of Lisp in SWIG to
       make users happy.

       The solution could be the following:

**     Build a SWIG library (again) and load it into a Common Lisp
       implementation.

       The FFI declarations could be written manually, or this could
       be bootstrapped via the s-expression module or the primitive
       UFFI wrappers.  This should be easy because SWIG's API is quite
       simple. 

       The embedded SWIG would be driven by a CL program.  High-level
       typemaps would be written as Lisp programs that generate Lisp
       code.

Ocaml
-----
**     I've been working with my camlp4 module and type information
       from the compiler.  When I'm done, the user will have access
       to type inference when writing code, when the inference is
       unambiguous.  This allows the user to write x = _foo 1.0
       instead of x = get_float (_foo (C_float 1.0)).  It's not as
       easy as it sounds, because O'caml doesn't keep type information
       at run time, and doesn't really have a mechanism for doing what
       I need.  However, it's possible to write a preprocessor that
       inserts correct type info at compile time.

       That having been said, the program must compile for type info
       to be available, so I need to attend to a lot of details;  The
       program must compile both with and without type augmentation.
       
Xml
---


Documentation
-------------

****   Extending SWIG (and internals).

***    Perl, Python, Tcl modules.

***    add section for Perl module support for operator overloading

**     Add section on WAD.

Other
-----

*****  Learn more wicked Jazz chords.
       (in progress)

