diff options
Diffstat (limited to 'NEW')
| -rw-r--r-- | NEW | 267 |
1 files changed, 0 insertions, 267 deletions
@@ -1,267 +0,0 @@ -New Features and Important Changes, v1.3 - -Author(s) : David Beazley - -March 21, 2003 - -1. Introduction ---------------- -This document briefly explains some of the most important changes made -since the release of SWIG1.1. The goal is to provide information for -people who want to upgrade an older SWIG interface to the new version. - -Most changes pertain to the internal implementation of SWIG and the -organization of the core, parser, and language modules. As a SWIG -user, almost all of these changes are hidden from view except for a -few important cases where changes to the core have dramatically -altered SWIG's old behavior. - -2. Types and typemaps ---------------------- -2.1 Variables of the form 'const type *' are no longer wrapped as - constants, but as C global variables. The earlier SWIG behavior - was incorrect due to Dave's misinterpretation of 'const' in the C - language specification. - - If you have written an interface that expects to create - constants using 'const type *' you will need to rewrite those - specifications using a new %constant directive like this: - - %constant(type *) name = value; - -2.2 SWIG generally has better support for pointers, 'const', - arrays, and pointers to functions. - -2.3 Typemaps are now applied to a more precisely defined set - of datatypes. For example, consider the following - typemap: - - %typemap(in) foo * { - ... get a foo ... - } - - In SWIG1.1, this typemap would get applied to 'foo *', - 'foo &', 'foo []', 'foo[][]', and so forth. - - In SWIG1.3, this typemap *only* gets applied to 'foo *' and - 'const foo *'. It does *NOT* get mapped to the other - variants listed above. - -2.4 Bug fix. SWIG now correctly handles typemaps of the form - - %typemap(in) Object { - ... get an object ... - } - -2.5 The memberout typemap is no longer available and is withdrawn. - The old implementation was essentially useless because of the - way in which code was generated. - -2.6 The memberin typemap is now inserted inline in the generated - wrapper code. This provides access to scripting-specific - variables in the wrapper function. - -2.7 SWIG-1.3.10 features a total rewrite of the typemap system. - Typemaps now use a different variable naming scheme. Typemaps - for arguments look like this: - - %typemap(in) sometype { - $1 = convert value ($input); - } - - The variable $1 replaces $target and the variable $input replaces - $source. - - For output values, typemaps look like this: - - %typemap(out) sometype { - $result = create result ($1); - } - - The variable $1 replaces $source and the variable $result replaces - $target. - - See Doc/Manual/Typemaps.html for a full description of the new - typemap system. - -2.8 Multi-argument typemaps are now supported. This solves a common - problem that occurs with functions like this - - void foo(char *buffer, int len); - - where you would like to make the two arguments operate as a single - object in the target language. - -2.9 Types such as 'const int &', 'const double &', are passed as - values instead of pointers. - -2.10 C++ namespaces are now supported. - -3. Type checking ----------------- - -SWIG no longer uses the functions SWIG_GetPtr() and SWIG_MakePtr() to -parse datatypes in wrapper code. This is because the type of a -pointer is no longer associated with a string, but with a special -"swig_type_info *" object. If you are not using typemaps, this change -should cause no noticable effects. However, if you have written -typemaps to handle pointers, here are the essential details: - -3.1 Type name mangling is different in SWIG1.3. For a type of - "int **", SWIG1.1 used to produce a name of the form - "_int_pp". SWIG1.3 on the other hand, produces a name - of the form "_p_p_int". There are a number of reasons for - changing the format, but I'd rather not go into it here. You'll - just have to learn to live with it :-). - -3.2 Types are described by a special "swig_type_info *" object. Everywhere - a string was used before, an object of this type will be used. - The "swig_type_info *" for a given type can always be obtained - using macros involving the mangled typename in 3.1. For example, - the type object of of 'int **' is 'SWIGTYPE_p_p_int'. - -3.3 Instead of SWIG_GetPtr, a function of the following form is used: - - int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty, int flags); - - Note: the function name may differ in certain implementations (read - the source). For example: - - int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int,0); - - Passing a value of '0' for the type will accept any pointer. This - works kind of like 'void *'. The flags argument is reserved for - future expansion. - -3.4. To create a pointer object, one uses a function similar to - - ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty, int flags); - - It works in a similar manner: - - p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int, 0); - - You will have to read the source to get the exact function name - used. The flags argument is implementation specific and reserved - for future expansion. - -3.5. If, for whatever reason, you need to obtain the 'swig_type_info *' - outside the context of a wrapper file, you can use the - SWIG_TypeQuery() function. For example: - - swig_type_info *ty = SWIG_TypeQuery("int **"); - - this function returns an appropriate type_info structure or NULL - if no such type is registered. - -3.6 SWIG does not generate swig_type_info structures for types that are - not actually used in an interface file. As a result, the type - checking tables for SWIG1.3 tend to be much smaller than for SWIG1.1. - -*** Note: The old string-based type checking scheme is not going to -return to SWIG so do not ask for backwards compatibility. The new -scheme is substantially faster, it is less error-prone, it requires no -dynamic memory allocation, it works better with the runtime libraries, -and it is simpler to implement than the old string based approach. - -4. Deprecated Features (incomplete list) ----------------------------------------- - -4.1 Documentation system. The old documentation system has been removed - entirely. I expect it to return someday, but it will have a much - different form (probably influenced by XML). - -4.2 The %val and %out directives. These directives used to attach - properties to function parameters such as - - void foo(%val int *ptr); - - The same effect can now be achieved with typemaps: - - void foo(int *INPUT); - - -4.3 Extensions to the %module and %init directive are no longer - supported. For example: - - %module example, foo, bar - - This used to perform a special kind of multi-module - initialization for static linking. If you really - need to do this, you will have to manually insert - code into the module initialization function. - -4.4 %ifdef, %ifndef, %endif, %if, %elif, %else directives are - withdrawn. SWIG now has a real preprocessor. - -4.5 %checkout directive removed. - -4.6 %except and %new are deprecated. - -4.7 %readonly and %readwrite are deprecated. Use %immutable instead. - -4.8 The %addmethods directive has been renamed to %extend. - -5. Language specific changes ----------------------------- - -5.1 Python shadow classes are much more efficient and pass the shadow objects - directly to the C wrappers. - -5.2 Tcl code generation is substantially improved--especially for C++. - -5.3 Tcl module can now link to global variables of any type. - -5.4 Perl shadow classes improved and optimized somewhat. - -5.5 The Guile module represents pointers as smobs. (They used to be - mangled into strings.) Memory leaks and type conversion bugs have been - fixed. The Guile module system, including dynamic loading, and - exceptions are supported. A typemap-driven procedure-documentation - system has been added (requires Guile 1.4). Procedures-with-setters - can be generated. - -5.6 The Python module now automatically creates shadow class objects from the - C wrappers. This fixes a bunch of hard problems related to typemaps, - exception handling, and more. - -6. New Features ---------------- - -6.1 Java module added - -6.2 Ruby module added - -6.3 Mzscheme module added. - -6.4 Integrated preprocessor. You can now use C macros in SWIG interface files. - -6.5 PHP module added. - -6.6 %rename directive is greatly enhanced to deal with overloaded functions. - -6.7 Support for simple templates - -6.8 Support for overloaded operators. - -6.9 %feature directive. - -6.10 Ocaml module added. - -6.11 XML module added. - -6.12 CHICKEN module added. - -6.13 C# module added. - - - - - - - - - - - - |