TODO

   1 SWIG TO-DO
   2
   3 -----------------------------------------------------------------------------
   4
   5 ****    = High Priority
   6 ***     = Implement if possible.
   7 **      = Will implement if time.
   8 *       = Implement if bored (or deemed necessary).
   9
  10 defer   = Implement in next version
  11
  12 CORE:
  13
  14 ****   Add support for nested classes.   The type system should be
  15 defer  ready to go.  The primary obstacle lies in the target language
  16        modules (which were never programmed with nested classes in
  17        mind).  There are also issues with nested C structures.  For
  18        example:
  19
  20              struct Foo {
  21                  struct {
  22                      int x,y;
  23                  } z;
  24              };
  25
  26        This is one of the last remaining "hard" problems in the SWIG
  27        core, but it is important that we solve it.
  28
  29 ***    "Nested" typemaps. The basic idea is similar to allowing one to
  30        use $descriptor(T) for any T, rather than just $descriptor
  31        for the type currently being typemapped.
  32
  33        In short (ha!), given a previously defined typemap:
  34
  35        %typemap(in) Foo {
  36            // whatever it takes to initialize $1 from $input
  37        }
  38
  39        it would be possible to inline its code inside another typemap.
  40        While the syntax is still to be defined, the use would be
  41        along the lines of:
  42
  43        template <class T> class vector {
  44            %typemap(in) vector<T> {
  45                ...
  46                for (int i=0; i<N; i++) {
  47                    PyObject* x = ... // i-th element
  48                    $typemap(in, T, x, $1[i]);
  49                }
  50                ...
  51            }
  52            ...
  53        }
  54
  55        i.e., when $typemap(in,Foo,x,y) is encountered, it will
  56        be replaced by the code for %typemap(in) Foo; in the latter,
  57        x will be replaced for $input and y will be replaced for $1.
  58        As in the case above, x and y themselves might need to be
  59        expanded before or after being substituted in the typemap code.
  60        Also, $typemap(what,Foo,x,y,z,...) will be used in case of
  61        multi-arguments typemaps. The same will hold for "out" typemaps
  62        and all the others.
  63
  64        Comment by mkoeppe:
  65
  66           I think we need to be careful to keep the syntax readable.
  67           I would like to get a syntax that is close to that of
  68           typemap definitions.  So consider this typemap:
  69
  70                  %typemap(in) int { ... }
  71
  72           I would like to refer to this typemap like this:
  73
  74                  $typemap(in, input=x) int = foo;
  75
  76           Here $input would be replaced by the given keyword argument
  77           x, and $1 would be replaced by foo.
  78
  79           This syntax would extend easily to multi-typemaps:
  80
  81                  %typemap(in) ( int FIRST, double SECOND ) { ... }
  82
  83               -> $typemap(in, input=x)
  84                     ( int FIRST = foo, double SECOND = bar );
  85
  86           The advantage of this syntax would be that the formal
  87           arguments (int FIRST, double SECOND) are close to the
  88           actual arguments (foo, bar).
  89
  90         Comment by beazley
  91
  92                $typemap(in, input=x) int = foo;
  93
  94         is a little bit hard to parse in terms of variable substitution.
  95         I'm considering something like this:
  96
  97                $typemap(in,1=int foo, input=x)
  98
  99        Note: This is partially implemented in the new Unified Typemap
 100        Library(python,tcl,ruby and perl) via %fragments and the
 101        SWIG_From/SWIG_AsVal methdos.
 102
 103 ***    Implement $fail special variable substitution in wrappers. Used
 104        to properly transfer control out of a wrapper function while
 105        reclaiming resources.
 106
 107        Note: Implemented in languages that uses the UTL via the
 108        'SWIG_fail' macro.
 109
 110 ***    Rewrite declaration annotation to better unify %rename and related
 111        directives.  Add a selector mechanism that allows specific parse tree
 112        nodes to be identified.  For example:
 113
 114              %feature("foo", nodetype="class") Foo { ... some code ... };
 115
 116        Consider use of wildcards.   Namespace/nested scope support in
 117        %feature is currently weak.  It works, but is fragile.  Consider
 118        an implementation that is better integrated with symbol table
 119        management.  Continue to consolidate SWIG directives to %feature.
 120
 121        Note: Initial implementation in the %rename directive.
 122
 123 ***    Add more intelligent information related to object ownership.
 124        SWIG should be able to automatically strip ownership from
 125        objects when they are assigned to pointer variables and structure
 126        members as well as stored in a container (i.e., an array of pointers).
 127
 128        [ Partially finished for Ruby/Perl/Tcl/Python. ]
 129
 130 **     Restoration of the documentation system.
 131        [ Partially done for Python. ]
 132
 133
 134 **     Restoration of Objective-C support.
 135
 136 **     Unification of symbol tables and type system scopes.  In a sense
 137        they capture the same information so it is not necessary to have
 138        both.  The existence of two symbol management systems is mostly
 139        historical.
 140
 141 Build
 142 -----
 143
 144 Library
 145 -------
 146
 147 ****   Add more support for the C++ standard library.  std::complex and other
 148        core datatypes.   Refine support for STL vector.   Add more STL objects.
 149
 150        [ Partially finished for Python. ]
 151
 152 ****   Continue to expand the set of recognized typemaps.
 153
 154 Windows
 155 -------
 156
 157 All language modules
 158 --------------------
 159
 160 Python
 161 ------
 162
 163 ***    Ability to wrap certain classes as Python built-in types.
 164
 165 Perl
 166 ----
 167
 168 ****   Rewrite runtime pointer type checking to better integrate
 169        shadow classes.   Creation of shadow classes should be done
 170        in C instead of Perl.   This will fix a number of problems
 171        related to typemaps and reduce the amount of Perl wrapper code.
 172
 173 ****   Create tests for existing support for operator overloading
 174
 175 Tcl
 176 ---
 177
 178 Ruby
 179 ----
 180
 181 ****   The "Resource Management in Proxies" section of the "SWIG and C++"
 182        chapter discusses how proxies' ownership of their associated C++
 183        object can change, and the use of the special disown() and
 184        acquire() methods to change this ownership status. Need to
 185        address this for Ruby as well.
 186
 187 ***    Add support for keyword arguments (by collecting them in a hash?).
 188
 189 Java
 190 ----
 191
 192
 193 C#
 194 --
 195
 196 PHP
 197 ---
 198
 199 ****   Look at moving to using the UTL.
 200
 201 ***    Director support.
 202
 203 **     When returning wrapped objects via alternate constructors if that
 204        pointer value already exists "out there" as a resource we should
 205        use the same resource, we can't have multiple ref-counted resources
 206        mapping to the same object in case it gets twice destroyed.  And check
 207        if ref count destroying is even working, see smart_pointer_rename
 208
 209 *      Work out how classes without even inherited constructors should
 210        interact with the php "new <class>" notation.
 211        See: abstract_inherit_wrap.cpptest
 212
 213 **     Look at pass by point and passby ref,
 214        Make sometype** to be auto allocated
 215        Make sometype& and sometype* to be autoallocated IF THEY ARE NOT
 216        ALREADY swigtype wrapped.
 217
 218 *      Review to see what else is missing!
 219
 220 Guile
 221 -----
 222
 223 **     Maybe rename slot setters from CLASS-SLOT-set to CLASS-SLOT-set!
 224        to match Scheme convention for naming of mutators.
 225
 226 **     Support keyword args.
 227
 228 **     Director Support!
 229
 230 **     Cleaner handling of multiple values.
 231        Use a typemap keyword argument "numoutputs" of "out" and
 232        "argout" to indicate how many values are returned.
 233
 234 **     Make SWIG's types first-class by using a separate smob type for
 235        SWIG type descriptors; enable reflection on types.  (Maybe
 236        GOOPS metaclasses?)
 237
 238 **     Provide a clean way to construct type predicates.
 239
 240 **     In GOOPS mode, maybe make overloaded functions methods.
 241
 242 **     Increase the safety of destructor functions.  John Lenz suggests:
 243
 244           I think the best way of doing this would be to use %feature to mark
 245           which classes allow for "normal" <swig> smobs to be deleted explicitly.
 246
 247           We separate pointers into two classes, those that can be deleted from
 248           scheme and those that can't.  The pointers that can be deleted use the
 249           <collectable-swig> smob and those that can not be deleted use the
 250           <swig> smob.  A user can specify which type of each object they want
 251           with %newobject and the CONSUMED typemap.
 252
 253           By default, the exported destructor will only accept <collectable-swig>
 254           smobs, because by definition, collectable-swig smobs are those that can
 255           be deleted from scheme.  This allows for the user to implement
 256           protection.  In the interface file, the user has complete control over
 257           which objects can and can not be deleted, and can guarantee that
 258           objects that should not be deleted can not be deleted, and that objects
 259           that should eventually be deleted will be garbage collected.
 260
 261           This protection can then be overridden with a %feature directive,
 262           something like
 263
 264           %feature("guile_allow_destroy_all","1") Foo::~Foo;
 265
 266           I don't know what word we want to use, guile_allow_destroy_all is kinda
 267           bad.  This feature would then allow for a <swig Foo *> smob to be
 268           deleted by passing it to the destructor.  This would allow users to
 269           maintain the protection on other classes, only manually overriding the
 270           protection on the classes that need it.
 271
 272
 273 Mzscheme
 274 --------
 275
 276 **     Port list-vector.i and pointer-in-out.i from Guile.
 277
 278 **     Add shadow class support for the Swindle system.
 279
 280 Pike
 281 ----
 282
 283 *      Decide how to handle global variables (probably using something
 284        like the Python module's cvar). Affects Examples/pike/simple.
 285
 286 *      Decide how to handle static class member functions and member
 287        variables.
 288
 289 *      Should investigate the possibility of generating .cmod files
 290        in addition to straight C/C++ code for extensions.
 291
 292 Common Lisp
 293 -----------
 294
 295 *      Random thoughts by mkoeppe on supporting Common Lisp implementations:
 296
 297        There are many different Foreign Function Interfaces (FFI) for
 298        the various CL implementations.  Probably SWIG should interface
 299        to UFFI, a least-common-denominator FFI that supports many
 300        implementations.
 301
 302        Via the s-expression SWIG module we can export SWIG's parse
 303        tree and import it into CL.  It remains to check if all
 304        relevant information is dumped (for instance, the type
 305        information).  Experimental code is available to generate
 306        low-level UFFI declarations from this parse tree.
 307
 308        However, for wrapping C++, we also need to create C wrappers
 309        because most FFIs cannot directly import C++.  A CL SWIG module
 310        could be exporting both these wrappers and UFFI declarations.
 311        I have experimental code (not checked in yet) that does this.
 312
 313        This is fine for generating low-level wrappers. But how do we
 314        support user typemaps (like converting lists and vectors to C
 315        arrays on input)?  We have to generate Lisp code that does the
 316        conversion and then calls the low-level wrapper.  If we
 317        generate Lisp code, it should be beautiful and readable.
 318        Therefore, we need at least a Lisp pretty printer.  A Lisp
 319        pretty printer works best when the Lisp program is represented
 320        not as text but as Lisp data.  Moreover, typemap writers will
 321        feel very much constrained by SWIG's capabilities for
 322        generating wrapper code, when compared to writing Lisp macros.
 323        Thus we would need half a re-implementation of Lisp in SWIG to
 324        make users happy.
 325
 326        The solution could be the following:
 327
 328 **     Build a SWIG library (again) and load it into a Common Lisp
 329        implementation.
 330
 331        The FFI declarations could be written manually, or this could
 332        be bootstrapped via the s-expression module or the primitive
 333        UFFI wrappers.  This should be easy because SWIG's API is quite
 334        simple.
 335
 336        The embedded SWIG would be driven by a CL program.  High-level
 337        typemaps would be written as Lisp programs that generate Lisp
 338        code.
 339
 340 ALLEGROCL
 341 -----
 342 These first three will remove most of the warnings from most of the
 343 remaining checkpartial tests that are failing.
 344 ****  Throws typemap support
 345 ****  const typemaps
 346 ****  long long typemaps
 347
 348 Ocaml
 349 -----
 350 **     I've been working with my camlp4 module and type information
 351        from the compiler.  When I'm done, the user will have access
 352        to type inference when writing code, when the inference is
 353        unambiguous.  This allows the user to write x = _foo 1.0
 354        instead of x = get_float (_foo (C_float 1.0)).  It's not as
 355        easy as it sounds, because O'caml doesn't keep type information
 356        at run time, and doesn't really have a mechanism for doing what
 357        I need.  However, it's possible to write a preprocessor that
 358        inserts correct type info at compile time.
 359
 360        That having been said, the program must compile for type info
 361        to be available, so I need to attend to a lot of details;  The
 362        program must compile both with and without type augmentation.
 363
 364 Xml
 365 ---
 366
 367
 368 Documentation
 369 -------------
 370
 371 ****   Extending SWIG (and internals).
 372
 373 ***    Perl, Python, Tcl modules.
 374
 375 ***    add section for Perl module support for operator overloading
 376
 377 **     Add section on WAD.
 378