NEW

   1 New Features and Important Changes, v1.3
   2
   3 Author(s) :  David Beazley
   4
   5 March 21, 2003
   6
   7 1. Introduction
   8 ---------------
   9 This document briefly explains some of the most important changes made
  10 since the release of SWIG1.1.  The goal is to provide information for
  11 people who want to upgrade an older SWIG interface to the new version.
  12
  13 Most changes pertain to the internal implementation of SWIG and the
  14 organization of the core, parser, and language modules.  As a SWIG
  15 user, almost all of these changes are hidden from view except for a
  16 few important cases where changes to the core have dramatically
  17 altered SWIG's old behavior.
  18
  19 2. Types and typemaps
  20 ---------------------
  21 2.1 Variables of the form 'const type *' are no longer wrapped as
  22      constants, but as C global variables.  The earlier SWIG behavior
  23      was incorrect due to Dave's misinterpretation of 'const' in the C
  24      language specification.
  25
  26      If you have written an interface that expects to create
  27      constants using 'const type *' you will need to rewrite those
  28      specifications using a new %constant directive like this:
  29
  30        %constant(type *) name = value;
  31
  32 2.2  SWIG generally has better support for pointers, 'const',
  33      arrays, and pointers to functions.
  34
  35 2.3  Typemaps are now applied to a more precisely defined set
  36      of datatypes.  For example, consider the following
  37      typemap:
  38
  39            %typemap(in) foo * {
  40                 ... get a foo ...
  41            }
  42
  43      In SWIG1.1, this typemap would get applied to 'foo *',
  44      'foo &', 'foo []', 'foo[][]', and so forth.
  45
  46      In SWIG1.3, this typemap *only* gets applied to 'foo *' and
  47      'const foo *'. It does *NOT* get mapped to the other
  48      variants listed above.
  49
  50 2.4  Bug fix.  SWIG now correctly handles typemaps of the form
  51
  52           %typemap(in) Object {
  53                ... get an object ...
  54           }
  55
  56 2.5  The memberout typemap is no longer available and is withdrawn.
  57      The old implementation was essentially useless because of the
  58      way in which code was generated.
  59
  60 2.6  The memberin typemap is now inserted inline in the generated
  61      wrapper code.  This provides access to scripting-specific
  62      variables in the wrapper function.
  63
  64 2.7  SWIG-1.3.10 features a total rewrite of the typemap system.
  65      Typemaps now use a different variable naming scheme.  Typemaps
  66      for arguments look like this:
  67
  68        %typemap(in) sometype {
  69            $1 = convert value ($input);
  70        }
  71
  72      The variable $1 replaces $target and the variable $input replaces
  73      $source.
  74
  75      For output values, typemaps look like this:
  76
  77        %typemap(out) sometype {
  78           $result = create result ($1);
  79        }
  80
  81      The variable $1 replaces $source and the variable $result replaces
  82      $target.
  83
  84      See Doc/Manual/Typemaps.html for a full description of the new
  85      typemap system.
  86
  87 2.8  Multi-argument typemaps are now supported.   This solves a common
  88      problem that occurs with functions like this
  89
  90         void foo(char *buffer, int len);
  91
  92      where you would like to make the two arguments operate as a single
  93      object in the target language.
  94
  95 2.9  Types such as 'const int &', 'const double &', are passed as
  96      values instead of pointers.
  97
  98 2.10 C++ namespaces are now supported.
  99
 100 3. Type checking
 101 ----------------
 102
 103 SWIG no longer uses the functions SWIG_GetPtr() and SWIG_MakePtr() to
 104 parse datatypes in wrapper code.  This is because the type of a
 105 pointer is no longer associated with a string, but with a special
 106 "swig_type_info *" object.  If you are not using typemaps, this change
 107 should cause no noticable effects.  However, if you have written
 108 typemaps to handle pointers, here are the essential details:
 109
 110 3.1  Type name mangling is different in SWIG1.3.  For a type of
 111      "int **", SWIG1.1 used to produce a name of the form
 112      "_int_pp".  SWIG1.3 on the other hand, produces a name
 113       of the form "_p_p_int".   There are a number of reasons for
 114       changing the format, but I'd rather not go into it here. You'll
 115       just have to learn to live with it :-).
 116
 117 3.2  Types are described by a special "swig_type_info *" object.   Everywhere
 118      a string was used before, an object of this type will be used.
 119      The "swig_type_info *" for a given type can always be obtained
 120      using macros involving the mangled typename in 3.1.  For example,
 121      the type object of of 'int **' is 'SWIGTYPE_p_p_int'.
 122
 123 3.3  Instead of SWIG_GetPtr, a function of the following form is used:
 124
 125         int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty, int flags);
 126
 127      Note: the function name may differ in certain implementations (read
 128      the source). For example:
 129
 130         int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int,0);
 131
 132      Passing a value of '0' for the type will accept any pointer. This
 133      works kind of like 'void *'.  The flags argument is reserved for
 134      future expansion.
 135
 136 3.4. To create a pointer object, one uses a function similar to
 137
 138         ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty, int flags);
 139
 140      It works in a similar manner:
 141
 142          p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int, 0);
 143
 144      You will have to read the source to get the exact function name
 145      used.  The flags argument is implementation specific and reserved
 146      for future expansion.
 147
 148 3.5. If, for whatever reason, you need to obtain the 'swig_type_info *'
 149      outside the context of a wrapper file, you can use the
 150      SWIG_TypeQuery() function. For example:
 151
 152          swig_type_info *ty = SWIG_TypeQuery("int **");
 153
 154      this function returns an appropriate type_info structure or NULL
 155      if no such type is registered.
 156
 157 3.6  SWIG does not generate swig_type_info structures for types that are
 158      not actually used in an interface file.   As a result, the type
 159      checking tables for SWIG1.3 tend to be much smaller than for SWIG1.1.
 160
 161 *** Note: The old string-based type checking scheme is not going to
 162 return to SWIG so do not ask for backwards compatibility.  The new
 163 scheme is substantially faster, it is less error-prone, it requires no
 164 dynamic memory allocation, it works better with the runtime libraries,
 165 and it is simpler to implement than the old string based approach.
 166
 167 4. Deprecated Features (incomplete list)
 168 ----------------------------------------
 169
 170 4.1 Documentation system.  The old documentation system has been removed
 171     entirely.  I expect it to return someday, but it will have a much
 172     different form (probably influenced by XML).
 173
 174 4.2 The %val and %out directives.  These directives used to attach
 175     properties to function parameters such as
 176
 177            void foo(%val int *ptr);
 178
 179     The same effect can now be achieved with typemaps:
 180
 181            void foo(int *INPUT);
 182
 183
 184 4.3 Extensions to the %module and %init directive are no longer
 185     supported. For example:
 186
 187         %module example, foo, bar
 188
 189     This used to perform a special kind of multi-module
 190     initialization for static linking.   If you really
 191     need to do this, you will have to manually insert
 192     code into the module initialization function.
 193
 194 4.4 %ifdef, %ifndef, %endif, %if, %elif, %else directives are
 195     withdrawn. SWIG now has a real preprocessor.
 196
 197 4.5 %checkout directive removed.
 198
 199 4.6 %except and %new are deprecated.
 200
 201 4.7 %readonly and %readwrite are deprecated.  Use %immutable instead.
 202
 203 4.8 The %addmethods directive has been renamed to %extend.
 204
 205 5. Language specific changes
 206 ----------------------------
 207
 208 5.1 Python shadow classes are much more efficient and pass the shadow objects
 209     directly to the C wrappers.
 210
 211 5.2 Tcl code generation is substantially improved--especially for C++.
 212
 213 5.3 Tcl module can now link to global variables of any type.
 214
 215 5.4 Perl shadow classes improved and optimized somewhat.
 216
 217 5.5 The Guile module represents pointers as smobs.  (They used to be
 218     mangled into strings.)  Memory leaks and type conversion bugs have been
 219     fixed.  The Guile module system, including dynamic loading, and
 220     exceptions are supported.  A typemap-driven procedure-documentation
 221     system has been added (requires Guile 1.4).  Procedures-with-setters
 222     can be generated.
 223
 224 5.6 The Python module now automatically creates shadow class objects from the
 225     C wrappers.  This fixes a bunch of hard problems related to typemaps,
 226     exception handling, and more.
 227
 228 6. New Features
 229 ---------------
 230
 231 6.1 Java module added
 232
 233 6.2 Ruby module added
 234
 235 6.3 Mzscheme module added.
 236
 237 6.4 Integrated preprocessor.  You can now use C macros in SWIG interface files.
 238
 239 6.5 PHP module added.
 240
 241 6.6 %rename directive is greatly enhanced to deal with overloaded functions.
 242
 243 6.7 Support for simple templates
 244
 245 6.8 Support for overloaded operators.
 246
 247 6.9 %feature directive.
 248
 249 6.10 Ocaml module added.
 250
 251 6.11 XML module added.
 252
 253 6.12 CHICKEN module added.
 254
 255 6.13 C# module added.
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267