<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
<!-- And munged by Dave's special Python script -->
<html>
<head>
<title>SWIG Basics</title>
</head>

<body bgcolor="#ffffff">
<a name="n0"></a><h1>3 SWIG Basics</h1><p><ul>
<li> <a href="#n1">Running SWIG</a>
<li> <a href="#n2">Simple C functions, variables, and constants</a>
<li> <a href="#n3">Pointers and complex objects</a>
<li> <a href="#n4">Getting down to business</a>
<li> <a href="#n5">Structures, unions, and object oriented C programming</a>
<li> <a href="#n6">C++ support</a>
<li> <a href="#n7">Objective-C</a>
<li> <a href="#n8">Conditional compilation</a>
<li> <a href="#n9">Code Insertion</a>
<li> <a href="#n10">A general interface building strategy</a>
</ul>

<a name="n1"></a><h2> Running SWIG</h2>
SWIG is invoked by the <tt>swig</tt> command. This command has a number of options including:<p>
<p>
<blockquote><pre>swig &lt;options&gt; filename

-tcl                  Generate Tcl wrappers
-tcl8                 Generate Tcl 8.0 wrappers
-perl                 Generate Perl5 wrappers
-python               Generate Python wrappers
-perl4                Generate Perl4 wrappers
-guile                Generate Guile wrappers
-dascii               ASCII documentation
-dlatex               LaTeX documentation
-dhtml                HTML documentation
-dnone                No documentation
-c++                  Enable C++ handling
-objc                 Enable Objective-C handling.
-Idir                 Set SWIG include directory
-lfile                Include a SWIG library file.
-c                    Generate raw wrapper code (omit supporting code)
-v                    Verbose mode (perhaps overly verbose)
-o outfile            Name of output file
-d docfile            Set name of documentation file (without suffix)
-module name          Set name of SWIG module
-Dsymbol              Define a symbol
-version              Show SWIG's version number
-help                 Display all options

</pre></blockquote>
This is only a partial list of options. A full listing of options can be obtained by invoking "<tt>swig -help</tt>". Each target language may have additional options which can be displayed using "<tt>swig -lang -help</tt>" where <tt>-lang</tt> is one of the target languages above.<p>
<a name="n11"></a><h3> Input format</h3>
As input, SWIG takes a file containing ANSI C/C++ declarations. This file may be a special "interface file" (usually given a .i suffix), a C header file or a C source file. The most common method of using SWIG is with a special interface file. These files contain ANSI C declarations like a header file, but also contain SWIG directives and documentation. Interface files usually have the following format :<p>
<p>
<p>
<blockquote><pre>%module mymodule 
%{
#include "myheader.h"
%}
// Now list ANSI C variable and function declarations

</pre></blockquote>
The name of the module (if supplied) must always appear before the first C declaration or be supplied on the SWIG command line using the <tt>-module</tt> option (When the module name is specified on the command line, it will override any module name present in a file). Everything inside the <tt>%{,%</tt>} block is copied verbatim into the resulting output file. The <tt>%{,%}</tt> block is optional, but most interface files use one to include the proper header files.<p>
<a name="n12"></a><h3> SWIG Output</h3>
By default an interface file with the name <tt>myfile.i</tt> will be transformed into a file called <tt>myfile_wrap.c</tt>. The name of the output file can be changed using the <tt>-o</tt> option. When working with some C++ compilers, the <tt>-o</tt> option can be used to give the output file a proper C++ suffix. The output file usually contains everything that is needed to build a working module for the target scripting language. Compile it along with your C program, link it, and you should be ready to run.<p>
<a name="n13"></a><h3> Comments</h3>
C and C++ style comments may be placed in interface files, but these are used to support the automatic documentation system. Please see the documentation section for more details on this. Otherwise, SWIG throws out all comments so you can use a C++ style comment even if the resulting wrapper file is compiled with the C compiler. <p>
<a name="n14"></a><h3> C Preprocessor directives</h3>
SWIG does not run the C preprocessor. If your input file makes extensive use of the C preprocessor, SWIG will probably hate it. However, SWIG does recognize a few C preprocessor constructs that are quite common in C code :<p>
<p>
<ul>
<li><tt>#define</tt>. Used to create constants
<li><tt>#ifdef,#ifndef,#else,#endif</tt>, <tt>#if, #elif</tt>. Used for conditional compilation
</ul>
<p>
All other C preprocessor directives are ignored by SWIG (including macros created using <tt>#define</tt>). <p>
<a name="n15"></a><h3> SWIG Directives</h3>
SWIG directives are always preceded by a "<tt>%</tt>" to distinguish them from normal C directives and declarations. There are about two dozen different directives that can be used to give SWIG hints, provide annotation, and change SWIG's behavior in some way or another. <p>
<a name="n16"></a><h3> Limitations in the Parser (and various things to keep in mind)</h3>
It was never my intent to write a full C/C++ parser. Therefore SWIG has a number of limitations to keep in mind.<p>
<p>
<ul>
<li>Functions with variable length arguments (ie. "...") are not supported.
<li>Complex declarations such as function pointers and arrays are problematic. You may need to remove these from the SWIG interface file or hide them with a typedef.
<li>C++ source code (what would appear in a .C file) is especially problematic. Running SWIG on C++ source code is highly discouraged.
<li>More sophisticated features of C++ such as templates and operator overloading are not supported. Please see the section on using SWIG with C++ for more details. When encountered, SWIG may issue a warning message or a syntax error if it can't figure out you are trying to do.
</ul>
<p>
Many of these limitations may be eliminated in future releases. It is worth noting that many of the problems associated with complex declarations can sometimes be fixed by clever use of <tt>typedef</tt>.<p>
<p>
If you are not sure whether SWIG can handle a particular declaration, the best thing to do is try it and see. SWIG will complain loudly if it can't figure out what's going on. When errors occur, you can either remove the offending declaration, conditionally compile it out (SWIG defines a symbol <tt>SWIG</tt> that can be used for this), or write a helper function to work around the problem. <p>
<a name="n2"></a><h2> Simple C functions, variables, and constants</h2>
SWIG supports just about any C function, variable, or constant involving built-in C datatypes. For example :<p>
<p>
<blockquote><pre>%module example

extern double sin(double x);
extern int strcmp(const char *, const char *);
extern int My_variable;
#define STATUS 50
const char *VERSION="1.1";

</pre></blockquote>
will create two commands called "<tt>sin</tt>" and "<tt>strcmp</tt>", a global variable "<tt>My_variable</tt>", and two constants "<tt>STATUS</tt>" and "<tt>VERSION</tt>". Things work about like you would expect. For example, in Tcl :<p>
<p>
<blockquote><pre>% sin 3
5.2335956
% strcmp Dave Mike
-1
% puts $My_variable
42
% puts $STATUS
50
% puts $VERSION
1.1

</pre></blockquote>
The main concern when working with simple functions is SWIG's treatment of basic datatypes. This is described next.<p>
<a name="n17"></a><h3> Integers</h3>
SWIG maps the following C datatypes into integers in the target scripting language. <p>
<p>
<blockquote><pre>int
short
long
unsigned
signed
unsigned short
unsigned long
unsigned char
signed char
bool
</pre></blockquote>
<p>
Scripting languages usually only support a single integer type that corresponds to either the <tt>int</tt> or <tt>long</tt> datatype in C. When converting from C, all of the above datatypes are cast into the representation used by the target scripting language. Thus, a 16 bit short in C may be converted to a 32 bit integer. When integers are converted from the scripting language back into C, the value will be cast into the appropriate type. The value will be truncated if it is too large to fit into the corresponding C datatype. This truncation is not currently checked.<p>
<p>
The <tt>unsigned char</tt> and <tt>signed char</tt> datatypes are special cases that are treated as integers by SWIG. Normally, the <tt>char</tt> datatype is mapped as an ASCII string. <p>
<p>
The <tt>bool</tt> datatype is cast to and from an integer value of 0 and 1.<p>
<p>
Some care is in order for large integer values. Most scripting language use 32 bit integers so mapping a 64 bit long integer may lead to truncation errors. Similar problems may arise with 32 bit unsigned integers that may show up as negative numbers. As a rule of thumb, the <tt>int</tt> datatype and all variations of <tt>char</tt> and <tt>short</tt> datatypes are safe to use. For <tt>unsigned int</tt> and <tt>long</tt> datatypes, you should verify the correct operation of your program after wrapping it with SWIG.<p>
<a name="n18"></a><h3> Floating Point</h3>
SWIG recognizes the following floating point types :<p>
<blockquote><pre>
float
double
</pre></blockquote>
<p>
Floating point numbers are mapped to and from the natural representation of floats in the target language. This is almost always a <tt>double</tt> except in Tcl 7.x which uses character strings. The rarely used datatype of "long double" is not supported by SWIG.<p>
<a name="n19"></a><h3> Character Strings</h3>
The <tt>char</tt> datatype is mapped into a NULL terminated ASCII string with a single character. When used in a scripting language it will show up as a tiny string containing the character value. When converting the value back into C, SWIG will take a character string from the scripting language and strip off the first character as the char value. Thus if you try to assigned the value "foo" to a <tt>char</tt> datatype, it will get the value `f'.<p>
<p>
The <tt>char *</tt> datatype is assumed to be a NULL-terminated ASCII string. SWIG maps this into a character string in the target language. SWIG converts character strings in the target language to NULL terminated strings before passing them into C/C++. It is illegal for these strings to have embedded NULL bytes although there are ways to work around this problem.<p>
<p>
The <tt>signed char</tt> and <tt>unsigned char</tt> datatypes are mapped into integer values. The following example illustrates the mapping of <tt>char</tt> datatypes.<p>
<tt></tt><p>
<blockquote><pre><tt>%{
#include &lt;stdio.h&gt;
#include &lt;ctype.h&gt;
#include &lt;string.h&gt;
signed char sum(signed char a, signed char b) { return a+b;}
%}

int  strcmp(char *, char *);
char toupper(char);
signed char sum(signed char a, signed char b);
</tt></pre></blockquote>
<p>
A Tcl script using these functions (and the resulting output) might be as follows.<p>
<p>
<blockquote><pre>tclsh &gt; strcmp Mike John
1
tclsh &gt; toupper g
G
tclsh &gt; sum 17 -8
9
</pre></blockquote>
<a name="n20"></a><h3> Variables</h3>
SWIG attempts to map C/C++ global variables into scripting language variables. For example:<p>
<p>
<blockquote><pre>%module example

double foo;

</pre></blockquote>
will result in a scripting language variable that can be used as follows :<p>
<p>
<blockquote><pre># Tcl
set foo [3.5] 			;# Set foo to 3.5
puts $foo			;# Print the value of foo

# Python
cvar.foo = 3.5			;# Set foo to 3.5
print cvar.foo			;# Print value of foo

# Perl
$foo = 3.5;			;# Set foo to 3.5
print $foo,"\n";			;# Print value of foo

</pre></blockquote>
Whenever this "special" variable is used, the underlying C global variable will be accessed. As it turns out, working with global variables is one of the most tricky aspects of SWIG. Whenever possible, you should try to avoid the use of globals. Fortunately, most modular programs make limited (or no) use of globals.<p>
<a name="n21"></a><h3> Constants</h3>
Constants can be created using <tt>#define</tt>, <tt>const</tt>, or enumerations. Constant expressions are also allowed. The following interface file shows a few valid constant declarations :<p>
<p>
<blockquote><pre>#define I_CONST       5               // An integer constant
#define F_CONST       3.14159         // A Floating point constant
#define S_CONST       "hello world"   // A string constant
#define NEWLINE       '\n'            // Character constant
#define MODE          DEBUG           // Sets MODE to DEBUG.
                                      // DEBUG is assumed to be an
                                      // int unless declared earlier
enum boolean {NO=0, YES=1};
enum months {JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
             SEP, OCT, NOV, DEC};
const double PI 3.141592654;
#define F_CONST (double) 5            // A floating pointer constant with cast
#define PI_4 PI/4
#define FLAGS 0x04 | 0x08 | 0x40

</pre></blockquote>
In <tt>#define</tt> declarations, the type of a constant is inferred by syntax or can be explicitly set using a cast. For example, a number with a decimal point is assumed to be floating point. When no explicit value is available for a constant, SWIG will use the value assigned by the C compiler. For example, no values are given to the <tt>months</tt> enumeration, but this is no problem---SWIG will use whatever the C compiler picks. <p>
<p>
The use of constant expressions is allowed, but SWIG does not evaluate them. Rather, it passes them through to the output file and lets the C compiler perform the final evaluation (SWIG does perform a limited form of type-checking however).<p>
<p>
For enumerations, it is critical that the original enum definition be included somewhere in the interface file (either in a header file or in the <tt>%{,%}</tt> block). SWIG only translates the enumeration into code needed to add the constants to a scripting language. It needs the original enumeration declaration to retrieve the correct enum values.<p>
<a name="n3"></a><h2> Pointers and complex objects</h2>
As we all know, most C programs have much more than just integers, floating point numbers, and character strings. There may be pointers, arrays, structures, and other objects floating around. Fortunately, this is usually not a problem for SWIG.<p>
<a name="n22"></a><h3> Simple pointers</h3>
Pointers to basic C datatypes such as <p>
<p>
<blockquote><pre>int *
double ***
char **
</pre></blockquote>
<p>
can be used freely in an interface file. SWIG encodes pointers into a representation containing the actual value of the pointer and a string representing the datatype. Thus, the SWIG representation of the above pointers (in Tcl), might look like the following :<p>
<p>
<blockquote><pre>_10081012_int_p
_1008e124_double_ppp
_f8ac_char_pp
</pre></blockquote>
<p>
A NULL pointer is represented by the string "NULL" or the value 0 encoded with type information.<p>
<p>
All pointers are treated as opaque objects by SWIG. A pointer may be returned by a function and passed around to other C functions as needed. For all practical purposes, the scripting language interface works in exactly the same way as you would write a C program (well, with a few limitations).<p>
<p>
The scripting language representation of a pointer should never be manipulated directly (although nothing prevents this). SWIG does not normally map pointers into high-level objects such as associative arrays or lists (for example, it might be desirable to convert an <tt>int *</tt> into an list of integers). There are several reasons for this :<p>
<p>
<ul>
<li>Adding special cases would make SWIG more complicated and difficult to maintain.
<li>There is not enough information in a C declaration to properly map pointers into higher level constructs. For example, an <tt>int *</tt> may indeed be an array of integers, but if it contains one million elements, converting it into a Tcl, Perl, or Python list would probably be an extremely bad idea.
<li>By treating all pointers equally, it is easy to know what you're going to get when you create an interface (pointers are treated in a consistent manner).
</ul>
<p>
As it turns out, you can remap any C datatype to behave in new ways so these rules are not set in stone. Interested readers should look at the chapter on typemaps.<p>
<a name="n23"></a><h3> Run time pointer type checking</h3>
By allowing pointers to be manipulated interactively in a scripting language, we have effectively bypassed the type-checker in the C/C++ compiler. By encoding pointer values with a datatype, SWIG is able to perform run-time type-checking in order to prevent mysterious system crashes and other anomalies. By default, SWIG uses a strict-type checking model that checks the datatype of all pointers before passing them to C/C++. However, you can change the handling of pointers using the <tt>-strict</tt> option:<p>
<p>
<blockquote><pre>-strict 0			No type-checking (living on the edge)
-strict 1			Generate warning messages (somewhat annoying)
-strict 2			Strict type checking (the default)

</pre></blockquote>
Strict type checking is the recommended default since is the most reliable and most closely follows the type checking rules of C. In fact, at this time, the other two modes should be considered to be outdated SWIG features that are supported, but no longer necessary.<p>
<p>
By default, SWIG allows "NULL" pointers to be passed to C/C++. This has the potential to crash code and cause other problems if you are not careful. Checks can be placed on certain values to prevent this but this requires the use of typemaps (described in later chapters).<p>
<blockquote><pre>
</pre></blockquote>
Like C, it should also be noted that functions involving <tt>void</tt> pointers can accept any kind of pointer object.<p>
<a name="n24"></a><h3> Derived types, structs, and classes</h3>
For everything else (structs, classes, arrays, etc...) SWIG applies a very simple rule :<p>
<p>
All complex datatypes are pointers<p>
<p>
In other words, SWIG manipulates everything else by reference. This model makes sense because most C/C++ programs make heavy use of pointers and we can use the type-checked pointer mechanism already present for handling pointers to basic datatypes.<p>
<p>
While all of this probably sounds complicated, it's really quite simple. Suppose you have an interface file like this :<p>
<p>
<blockquote><pre>%module fileio
FILE *fopen(char *, char *);
int fclose(FILE *);
unsigned fread(void *ptr, unsigned size, unsigned nobj, FILE *);
unsigned fwrite(void *ptr, unsigned size, unsigned nobj, FILE *);
void *malloc(int nbytes);
void free(void *);

</pre></blockquote>
In this file, SWIG doesn't know what a <tt>FILE</tt> is, but it's used as a pointer, so it doesn't really matter what it is. If you wrapped this module into Python, you could use the functions just like you would expect :<p>
<p>
<blockquote><pre># Copy a file 
def filecopy(source,target):
	f1 = fopen(source,"r")
	f2 = fopen(target,"w")
	buffer = malloc(8192)
	nbytes = fread(buffer,8192,1,f1)
	while (nbytes &gt; 0):
		fwrite(buffer,8192,1,f2)
		nbytes = fread(buffer,8192,1,f1)
	free(buffer)

</pre></blockquote>
In this case <tt>f1</tt>,<tt> f2</tt>, and <tt>buffer</tt> are all opaque objects containing C pointers. It doesn't matter what value they contain--our program works just fine without this knowledge.<p>
<a name="n25"></a><h3> What happens when SWIG encounters an unknown datatype?</h3>
When SWIG encounters an unknown datatype, it automatically assumes that it is some sort of complex datatype. For example, suppose the following function appeared in a SWIG input file:<p>
<p>
<blockquote><pre>void matrix_multiply(Matrix *a, Matrix *b, Matrix *c);
</pre></blockquote>
<p>
SWIG has no idea what a "<tt>Matrix</tt>" is so it will assume that you know what you are doing and map it into a pointer. This makes perfect sense because the underlying C function is using pointers in the first place. Unlike C or C++, SWIG does not actually care whether <tt>Matrix</tt> has been previously defined in the interface file or not. While this may sound strange, it makes it possible for SWIG to generate interfaces from only partial information. In many cases, you may not care what a <tt>Matrix</tt> really is as long as you can pass references to one around in the scripting language interface. The downside to this relaxed approach is that typos may go completely undetected by SWIG. You can also end up shooting yourself in the foot, but presumably you've passed your programming safety course if you've made it this far.<p>
<p>
As a debugging tool, SWIG will report a list of used, but undefined datatypes, if you run it with the <tt>-stat</tt> option.<p>
<p>
<blockquote><pre>[beazley@guinness SWIG1.1b6]$ swig -stat matrix.i
Making wrappers for Tcl
Wrapped 1 functions
Wrapped 0 variables
Wrapped 0 constants
The following datatypes were used, but undefined.
     Matrix
[beazley@guinness SWIG1.1b6]$
</pre></blockquote>
<a name="n26"></a><h3> Typedef</h3>
<tt>typedef</tt> can be used to remap datatypes within SWIG. For example :<p>
<p>
<blockquote><pre>typedef unsigned int size_t;

</pre></blockquote>
This makes SWIG treat <tt>size_t</tt> like an unsigned int. Use of <tt>typedef</tt> is fairly critical in most applications. Without it, SWIG would consider <tt>size_t</tt> to be a complex object (which would be incorrectly converted into a pointer).<p>
<a name="n4"></a><h2> Getting down to business</h2>
So far, you know just about everything you need to know to use SWIG to build interfaces. In fact, using nothing but basic datatypes and opaque pointers it is possible to build scripting language interfaces to most kinds of C/C++ packages. However, as the novelty wears off, you will want to do more. This section describes SWIG's treatment of more sophsticated issues.<p>
<a name="n27"></a><h3> Passing complex datatypes by value</h3>
Unfortunately, not all C programs manipulate complex objects by reference. When encountered, SWIG will transform the corresponding C/C++ declaration to use references instead. For example, suppose you had the following function :<p>
<p>
<blockquote><pre>double dot_product(Vector a, Vector b);
</pre></blockquote>
<p>
SWIG will transform this function call into the equivalent of the following :<p>
<p>
<blockquote><pre>double wrap_dot_product(Vector *a, Vector *b) {
	return dot_product(*a,*b);
}
</pre></blockquote>
<p>
In the scripting language<tt>, dot_product</tt> will now take references to Vectors instead of Vectors, although you may not notice the change. <p>
<a name="n28"></a><h3> Return by value</h3>
C functions that return complex datatypes by value are more difficult to handle. Consider the following function:<p>
<p>
<blockquote><pre>Vector cross(Vector v1, Vector v2);

</pre></blockquote>
This function is returning a complex object, yet SWIG only likes to work with references. Clearly, something must be done with the return result, or it will be lost forever. As a result, SWIG transforms this function into the following code :<p>
<p>
<blockquote><pre>Vector *wrap_cross(Vector *v1, Vector *v2) {
	Vector *result;
	result = (Vector *) malloc(sizeof(Vector));
	*(result) = cross(*v1,*v2);
	return result;
}
</pre></blockquote>
<p>
or if using C++ :<p>
<p>
<blockquote><pre>Vector *wrap_cross(Vector *v1, Vector *v2) {
	Vector *result = new Vector(cross(*v1,*v2)); // Uses default copy constructor
	return result;
}
</pre></blockquote>
<p>
SWIG is forced to create a new object and return a reference to it. It is up to the user to delete the returned object when it is no longer in use. When used improperly, this can lead to memory leaks and other problems. Personally, I'd rather live with a potential memory leak than forbid the use of such a function. Needless to say, some care is probably in order (you need to be aware of this behavior in any case). <p>
<a name="n29"></a><h3> Linking to complex variables</h3>
When global variables or class members involving complex datatypes are encountered, SWIG converts them into references. For example, a global variable like this :<p>
<blockquote><pre>
Vector unit_i;
</pre></blockquote>
<p>
gets mapped to a pair of set/get functions like this :<p>
<p>
<blockquote><pre>Vector *unit_i_get() {
	return &amp;unit_i;
}
Vector *unit_i_set(Vector *value) {
	unit_i = *value;
	return &amp;unit_i;
}
</pre></blockquote>
<p>
Returning a reference to the variable makes it accessible like any other object of this type. When setting the value, we simply make a copy of some other Vector reference. Again some caution is in order. A global variable created in this manner will show up as a reference in the target scripting language. It would be an extremely bad idea to free or destroy such a reference. Similarly, one can run into problems when copying complex C++ objects in this manner. Fortunately, in well-written modular code, excessive use (or abuse) of global variables is rare.<p>
<a name="n30"></a><h3> Arrays</h3>
The use of arrays in the current version of SWIG is supported, but with caution. If simple arrays appear, they will be mapped into a pointer representation. Thus, the following declarations :<p>
<p>
<blockquote><pre>int foobar(int a[40]);
void grok(char *argv[]);
void transpose(double a[20][20]);
</pre></blockquote>
<p>
will be processed as if they were declared like this:<p>
<p>
<blockquote><pre>int foobar(int *a);
void grok(char **argv);
void transpose(double (*a)[20]);
</pre></blockquote>
<p>
Multi-dimensional arrays are transformed into a single pointer since <tt>a[][]</tt> and <tt>**a</tt> are not the same thing (even though they can be used in similar ways). Rather, <tt>a[][]</tt> is mapped to *a, where <tt>*a</tt> is the equivalent of <tt>&amp;a[0][0]</tt>. The reader is encouraged to dust off their C book and look at the section on arrays before using them with SWIG.<p>
<p>
Be aware that use of arrays may cause compiler warnings or errors when compiling SWIG generated modules. While every attempt has been made to eliminate these problems, handling of arrays can be somewhat problematic due to the subtle differences between an array and a pointer.<p>
<a name="n31"></a><h3> Creating read-only variables</h3>
A read-only variable can be created by using the <tt>%readonly</tt> directive as shown :<p>
<blockquote><pre>
// File : interface.i

int 	a; 			// Can read/write
%readonly
int	b,c,d			// Read only variables
%readwrite
double	x,y			// read/write
</pre></blockquote>
<p>
The <tt>%readonly</tt> directive enables read-only mode until it is explicitly disabled using the <tt>%readwrite</tt> directive.<p>
<a name="n32"></a><h3> Renaming declarations</h3>
Normally, the name of a C function is used as the name of the command added to the target scripting language. Unfortunately, this name may conflict with a keyword or already existing function in the scripting language. Naming conflicts can be resolved using the <tt>%name</tt> directive as shown :<p>
<p>
<blockquote><pre>// interface.i

%name(my_print) extern void print(char *);
%name(foo) extern int a_really_long_and_annoying_name;

</pre></blockquote>
SWIG still calls the correct C functions, but in this case the function <tt>print()</tt> will really be called "<tt>my_print()</tt>" in the scripting language. <p>
<p>
A more powerful renaming operation can be performed with the<tt> %renam</tt>e directive as follows :<p>
<p>
<blockquote><pre>%rename oldname newname;

</pre></blockquote>
<tt>%rename </tt>applies a renaming operation to all future occurrences of a name. The renaming applies to functions, variables, class and structure names, member functions, and member data. For example, if you had two-dozen C++ classes, all with a member function named `print' (which is a keyword in Python), you could rename them all to `output' by specifying :<p>
<p>
<blockquote><pre>%rename print output; // Rename all `print' functions to `output'
</pre></blockquote>
<p>
SWIG does not perform any checks to see if the functions it adds are already defined in the target scripting language. However, if you are careful about namespaces and your use of modules, you can usually avoid these problems.<p>
<a name="n33"></a><h3> Overriding call by reference</h3>
SWIG is quite literal in its interpretation of datatypes. If you give it a pointer, it will use pointers. For example, if you're trying to call a function in a Fortran library (through its C interface) all function parameters will have to be passed by reference. Similarly, some C functions may use pointers in unusual ways. The <tt>%val</tt> directive can be used to change the calling mechanism for a C function. For example :<p>
<p>
<blockquote><pre>// interface.i
%{
#include &lt;time.h&gt;
%}

typedef long time_t;
time_t time(time_t *t);
struct tm *localtime(%val time_t *t);
char *asctime(struct tm *);

</pre></blockquote>
The <tt>localtime()</tt> function takes a pointer to a <tt>time_t</tt> value, but we have forced it to take a value instead in order to match up nicely with the return value of the <tt>time()</tt> function. When used in Perl, this allows us to do something like this :<p>
<blockquote><pre>
$t = time(0);
$tm = localtime($t); # Note passing $t by value here
print $asctime($tm);

</pre></blockquote>
Internally, the <tt>%val</tt> directive creates a temporary variable. The argument value is stored in this variable and a function call is made using a pointer to the temporary variable. Of course, if the function returns a value in this temporary variable, it will be lost forever. <p>
<a name="n34"></a><h3> Default/optional arguments</h3>
SWIG allows default arguments to be used in both C/C++ code as follows :<p>
<p>
<blockquote><pre>int plot(double x, double y, int color=WHITE);

</pre></blockquote>
To specify a default argument, simply specify it the function prototype as shown. SWIG will generate wrapper code in which the default arguments are optional. For example, this function could be used in Tcl as follows :<p>
<p>
<blockquote><pre>% plot -3.4 7.5 				# Use default value
% plot -3.4 7.5 10				# set color to 10 instead

</pre></blockquote>
While the ANSI C standard does not specify default arguments, default arguments used in a SWIG generated interface work with both C and C++.<p>
<a name="n35"></a><h3> Pointers to functions</h3>
At the moment, the SWIG parser has difficulty handling pointers to functions (a deficiency that is being corrected). However, having function pointers is useful for managing C callback functions and other things. To properly handle function pointers, it is currently necessary to use <tt>typedef.</tt> For example, the function <p>
<blockquote><pre>
void do_operation(double (*op)(double,double), double a, double b);
</pre></blockquote>
<p>
should be handled as follows :<p>
<blockquote><pre>
typedef double (*OP_FUNC)(double,double);
void do_operation(OP_FUNC op, double a, double b);

</pre></blockquote>
SWIG understands both the typedef declaration and the later function call. It will treat <tt>OP_FUNC</tt> just like any other complex datatype. In order for this approach to work, it is necessary that the typedef declaration be present in the original C code--otherwise, the C compiler will complain. If you are building a separate interface file to an existing C program and do not want to make changes to the C source, you can also do the following :<p>
<blockquote><pre>
// File : interface.i
%typedef double (*OP_FUNC)(double,double);
double do_operation(OP_FUNC op, double a, double b);
</pre></blockquote>
<p>
<tt>%typedef</tt> forces SWIG to generate a <tt>typedef</tt> in the C output code for you. This would allow the interface file shown to work with the original unmodified C function declaration.<p>
<p>
Constants containing the addresses of C functions can also be created. For example, suppose you have the following callback functions :<p>
<p>
<blockquote><pre>extern double op_add(double a, double b);
extern double op_sub(double a, double b);
extern double op_mul(double a, double b);

</pre></blockquote>
The addresses of these functions could be installed as scripting language constants as follows :<p>
<p>
<blockquote><pre>// interface.i
typedef double (*OP_FUNC)(double,double);
...
const OP_FUNC ADD = op_add;
const OP_FUNC SUB = op_sub;
const OP_FUNC MUL = op_mul;
...

</pre></blockquote>
When wrapped, this would create the constants <tt>ADD</tt>,<tt>SUB</tt>, and <tt>MUL</tt> containing the addresses of C callback functions. We could then pass these to other C functions expecting such function pointers as arguments as shown (for Tcl) :<p>
<p>
<blockquote><pre>%do_operation $ADD 3 4
7
%
</pre></blockquote>
<a name="n5"></a><h2> Structures, unions, and object oriented C programming</h2>
If SWIG encounters the definition of a structure or union, it will create a set of accessor functions for you. While SWIG does not need structure definitions to build an interface, providing definitions make it possible to access structure members. The accessor functions generated by SWIG simply take a pointer to an object and allow access to an individual member. For example, the declaration :<p>
<p>
<blockquote><pre>struct Vector {
	double x,y,z;
}

</pre></blockquote>
gets mapped into the following set of accessor functions :<p>
<p>
<blockquote><pre>double Vector_x_get(Vector *obj) {
	return obj-&gt;x;
}
double Vector_y_get(Vector *obj) { 
	return obj-&gt;y;
}
double Vector_z_get(Vector *obj) { 
	return obj-&gt;z;
}
double Vector_x_set(Vector *obj, double value) {
	obj-&gt;x = value;
	return value;
}
double Vector_y_set(Vector *obj, double value) {
	obj-&gt;y = value;
	return value;
}
double Vector_z_set(Vector *obj, double value) {
	obj-&gt;z = value;
	return value;
}
</pre></blockquote>
<a name="n36"></a><h3> Typedef and structures</h3>
SWIG supports the following construct which is quite common in C programs :<p>
<p>
<blockquote><pre>typedef struct {
	double x,y,z;
} Vector;

</pre></blockquote>
When encountered, SWIG will assume that the name of the object is `Vector' and create accessor functions like before. If two different names are used like this :<p>
<p>
<blockquote><pre>typedef struct vector_struct {
	double x,y,z;
} Vector;

</pre></blockquote>
the name `Vector' will still be used instead of "vector_struct".<p>
<a name="n37"></a><h3> Character strings and structures</h3>
Structures involving character strings require some care. SWIG assumes that all members of type <tt>char *</tt> have been dynamically allocated using <tt>malloc()</tt> and that they are NULL-terminated ASCII strings. When such a member is modified, the previously contents will be released, and the new contents allocated. For example :<p>
<p>
<blockquote><pre>%module mymodule
...
struct Foo {
	char *name;
	...
}

</pre></blockquote>
This results in the following accessor functions :<p>
<p>
<blockquote><pre>char *Foo_name_get(Foo *obj) {
	return Foo-&gt;name;
}

char *Foo_name_set(Foo *obj, char *c) {
	if (obj-&gt;name) free(obj-&gt;name);
	obj-&gt;name = (char *) malloc(strlen(c)+1);
	strcpy(obj-&gt;name,c);
	return obj-&gt;name;
}
</pre></blockquote>
<p>
This seems to work most of the time, but occasionally it's not always what you want. Typemaps can be used to change this behavior if necessary.<p>
<a name="n38"></a><h3> Array members</h3>
Arrays may appear as the members of structures, but they will be read-only. SWIG will write an accessor function that returns the pointer to the first element of the array, but will not write a function to change the array itself. This restriction is due to the fact that C won't let us change the "value" of an array. When this situation is detected, SWIG generates a warning message such as the following :<p>
<p>
<blockquote><pre>interface.i : Line 116. Warning. Array member will be read-only

</pre></blockquote>
To eliminate the warning message, typemaps can be used, but this is discussed in a later chapter (and best reserved for experienced users). Otherwise, if you get this warning, it may be harmless.<p>
<a name="n39"></a><h3> C constructors and destructors </h3>
While not part of the C language, it is usually useful to have some mechanism for creating and destroying an object. You can, of course, do this yourself by making an appropriate call to <tt>malloc()</tt>, but SWIG can make such functions for you automatically if you use C++ syntax like this :<p>
<p>
<blockquote><pre>%module mymodule
...
struct Vector {
	Vector(); 			// Tell SWIG to create a C constructor
	~Vector();			// Tell SWIG to create a C destructor
	double x,y,z;
}

</pre></blockquote>
When used with C code, SWIG will create two additional functions like this :<p>
<p>
<blockquote><pre>Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}

void delete_Vector(Vector *v) {
	free(v);
}

</pre></blockquote>
While C knows nothing about constructors and destructors, SWIG does---and it can automatically create some for you if you want. This only applies to C code--handling of C++ is handled differently.<p>
<p>
As an alternative to explicitly defining constructors and destructors, SWIG can also automatically generate them using either a command line option or a pragma. For example :<p>
<p>
<blockquote><pre>swig -make_default example.i 

</pre></blockquote>
or<p>
<p>
<blockquote><pre>%module foo
...
%pragma make_default 					// Make default constructors
... declarations ...
%pragma no_default					// Disable default constructors

</pre></blockquote>
This works with both C and C++.<p>
<a name="n40"></a><h3> Adding member functions to C structures</h3>
Many scripting languages provide a mechanism for creating classes and supporting object oriented programming. From a C standpoint, object oriented programming really just boils down to the process of attaching functions to structures. These functions typically operate on the structure (or object) in some way or another. While there is a natural mapping of C++ to such a scheme, there is no direct mechanism for utilizing it with C code. However, SWIG provides a special <tt>%addmethods</tt> directive that makes it possible to attach methods to C structures for purposes of building an object oriented scripting language interface. Suppose you have a C header file with the following declaration :<p>
<p>
<blockquote><pre>/* file : vector.h */
...
typedef struct {
	double x,y,z;
} Vector;

</pre></blockquote>
You can make a Vector look alot like a class by doing the following in an interface file :<p>
<p>
<blockquote><pre>// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

%include vector.h 				// Just grab original C header file
%addmethods Vector { 				// Attach these functions to struct Vector
	Vector(double x, double y, double z) {
		Vector *v;
		v = (Vector *v) malloc(sizeof(Vector));
		v-&gt;x = x;
		v-&gt;y = y;
		v-&gt;z = z;
		return v;
	}
	~Vector() {
		free(self);
	}
	double magnitude() {
		return sqrt(self-&gt;x*self-&gt;x+self-&gt;y*self-&gt;y+self-&gt;z*self-&gt;z);
	}
	void print() {
		printf("Vector [%g, %g, %g]\n", self-&gt;x,self-&gt;y,self-&gt;z);
	}
};

</pre></blockquote>
Now, when used with shadow classes in Python, you can do things like this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; v = Vector(3,4,0) 					# Create a new vector
&gt;&gt;&gt; print v.magnitude()					# Print magnitude
5.0
&gt;&gt;&gt; v.print()					# Print it out
[ 3, 4, 0 ]
&gt;&gt;&gt; del v					# Destroy it
</pre></blockquote>
<p>
The <tt>%addmethods</tt> directive can also be used in the definition of the Vector structure. For example:<p>
<blockquote><pre>// file : vector.i
%module mymodule
%{
#include "vector.h"
%}

typedef struct {
	double x,y,z;
	%addmethods {
		Vector(double x, double y, double z) { ... }
		~Vector() { ... }
		...
	}
} Vector;
</pre></blockquote>
<p>
Finally, <tt>%addmethods</tt> can be used to access externally written functions provided they follow the naming convention used in this example :<p>
<p>
<blockquote><pre>/* File : vector.c */
/* Vector methods */
#include "vector.h"
Vector *new_Vector(double x, double y, double z) {
	Vector *v;
	v = (Vector *) malloc(sizeof(Vector));
	v-&gt;x = x;
	v-&gt;y = y;
	v-&gt;z = z;
	return v;
}
void delete_Vector(Vector *v) {
	free(v);
}

double Vector_magnitude(Vector *v) {
	return sqrt(v-&gt;x*v-&gt;x+v-&gt;y*v-&gt;y+v-&gt;z*v-&gt;z);
}

// File : vector.i
// Interface file
%module mymodule
%{
#include "vector.h"
%}

typedef struct {
	double x,y,z;
	%addmethods {
		double magnitude(); 			// This will call Vector_magnitude
		...
	}
} Vector;

</pre></blockquote>
So why bother with all of this <tt>%addmethods</tt> business? In short, you can use it to make some pretty cool `object oriented' scripting language interfaces to C programs without having to rewrite anything in C++. <p>
<a name="n41"></a><h3> Nested structures</h3>
Occasionally, a C program will involve structures like this :<p>
<p>
<blockquote><pre>typedef struct Object {
	int objtype;
	union {
		int 	ivalue;
		double	dvalue;
		char	*strvalue;
		void	*ptrvalue;
	} intRep;
} Object;

</pre></blockquote>
When SWIG encounters this, it performs a structure splitting operation that transforms the declaration into the equivalent of the following:<p>
<p>
<blockquote><pre>typedef union {
	int 		ivalue;
	double		dvalue;
	char		*strvalue;
	void		*ptrvalue;
} Object_intRep;

typedef struct Object {
	int objType;
	Object_intRep intRep;
} Object;

</pre></blockquote>
SWIG will create an <tt>Object_intRep</tt> structure for use inside the interface file. Accessor functions will be created for both structures. In this case, functions like this would be created :<p>
<p>
<blockquote><pre>Object_intRep *Object_intRep_get(Object *o) {
	return (Object_intRep *) &amp;o-&gt;intRep;
}
int Object_intRep_ivalue_get(Object_intRep *o) {
	return o-&gt;ivalue;
}
int Object_intRep_ivalue_set(Object_intRep *o, int value) {
	return (o-&gt;ivalue = value);
}
double Object_intRep_dvalue_get(Object_intRep *o) {
	return o-&gt;dvalue;
}
... etc ...

</pre></blockquote>
Is it hairy? You bet. Does it work? Well, surprisingly yes. When used with Python and Perl5 shadow classes, it's even possible to access the nested members just like you expect :<p>
<p>
<blockquote><pre># Perl5 script for accessing nested member
$o = CreateObject(); 				# Create an object somehow
$o-&gt;{intRep}-&gt;{ivalue} = 7 				# Change value of o.intRep.ivalue
</pre></blockquote>
<p>
If you've got a bunch of nested structure declarations, it is certainly advisable to check them out after running SWIG. However, there is a good chance that they will work. If not, you can always remove the nested structure declaration and write your own set of accessor functions.<p>
<a name="n42"></a><h3> Other things to note about structures</h3>
SWIG doesn't care if the definition of a structure exactly matches that used in the underlying C code (except in the case of nested structures). For this reason, there are no problems omitting problematic members or simply omitting the structure definition altogether. If you are happy simply passing pointers around, this can be done without ever giving SWIG a structure definition.<p>
<p>
It is also important to note that most language modules may choose to build a more advanced interface. You may never use the low-level interface described here, although most of SWIG's language modules use it in some way or another.<p>
<a name="n6"></a><h2> C++ support</h2>
SWIG's support for C++ is an extension of the support for C functions, variables, and structures. However, SWIG only supports a subset of the C++ language. It has never been my goal to write a full C++ compiler or to turn scripting languages into some sort of weird pseudo C++ interpreter (considering how hard it is to write a C++ compiler, I'm not sure this would even be feasible anyways). <p>
<p>
This section describes SWIG's low-level access to C++ declarations. In many instances, this low-level interface may be hidden by shadow classes or an alternative calling mechanism (this is usually language dependent and is described in detail in later chapters).<p>
<a name="n43"></a><h3> Supported C++ features</h3>
SWIG supports the following C++ features :<p>
<p>
<ul>
<li>Simple class definitions
<li>Constructors and destructors
<li>Virtual functions
<li>Public inheritance (including multiple inheritance)
<li>Static functions
<li>References
</ul>
<p>
The following C++ features are not currently supported :<p>
<p>
<ul>
<li>Operator overloading
<li>Function overloading (without renaming)
<li>Templates (anything that would be defined using the `<tt>template</tt>' keyword).
<li>Friends
<li>Nested classes
<li>Namespaces
<li>Pointers to member functions.
</ul>
<p>
Since SWIG's C++ support is a "work in progress", many of these limitations may be lifted in future releases. In particular, function overloading and nested classes, may be supported in the future. Operator overloading and templates are unlikely to be supported anytime in the near future, but I'm not going to rule out the possibility in later releases.<p>
<a name="n44"></a><h3> C++ example</h3>
The following code shows a SWIG interface file for a simple C++ class.<p>
<p>
<blockquote><pre>%module list
%{
#include "list.h"
%}

// Very simple C++ example for linked list

class List {
public:
  List();
  ~List();
  int  search(char *value);
  void insert(char *);
  void remove(char *);
  char *get(int n);
  int  length;
static void print(List *l);
};
</pre></blockquote>
<p>
When compiling C++ code, it is critical that SWIG be called with the `<tt>-c++</tt>' option. This changes the way a number of critical features are handled with respect to differences between C and C++. It also enables the detection of C++ keywords. Without the <tt>-c++</tt> flag, SWIG will either issue a warning or a large number of syntax errors if it encounters any C++ code in an interface file.<p>
<a name="n45"></a><h3> Constructors and destructors</h3>
C++ constructors and destructors are translated into accessor functions like the following :<p>
<p>
<blockquote><pre>List * new_List(void) {
	return new List;
}
void delete_List(List *l) {
	delete l;
}

</pre></blockquote>
If the original C++ class does not have any constructors or destructors, putting constructors and destructors in the SWIG interface file will cause SWIG to generate wrappers for the default constructor and destructor of an object.<p>
<a name="n46"></a><h3> Member functions</h3>
Member functions are translated into accessor functions like this :<p>
<p>
<blockquote><pre>int List_search(List *obj, char *value) {
	return obj-&gt;search(value);
}

</pre></blockquote>
Virtual member functions are treated in an identical manner since the C++ compiler takes care of this for us automatically.<p>
<a name="n47"></a><h3> Static members</h3>
Static member functions are called directly without making any additional C wrappers. For example, the static member function <tt>print(List *l)</tt> will simply be called as <tt>List::print(List *l)</tt> in the resulting wrapper code.<p>
<a name="n48"></a><h3> Member data</h3>
Member data is handled in exactly the same manner as used for C structures. A pair of accessor functions will be created. For example :<p>
<p>
<blockquote><pre>int List_length_get(List *obj) {
	return obj-&gt;length;
}
int List_length_set(List *obj, int value) {
	obj-&gt;length = value;
	return value;
}

</pre></blockquote>
A read-only member can be created using the <tt>%readonly</tt> and <tt>%readwrite</tt> directives. For example, we probably wouldn't want the user to change the length of a list so we could do the following to make the value available, but read-only.<p>
<p>
<blockquote><pre>class List {
public:
...
%readonly
	int length;
%readwrite
...
};
</pre></blockquote>
<a name="n49"></a><h3> Protection</h3>
SWIG can only wrap class members that are declared public. Anything specified in a private or protected section will simply be ignored. To simplify your interface file, you may want to consider eliminating all private and protected declarations (if you've copied a C++ header file for example).<p>
<p>
By default, members of a class definition are assumed to be private until you explicitly give a `<tt>public:</tt>' declaration (This is the same convention used by C++).<p>
<a name="n50"></a><h3> Enums and constants</h3>
Enumerations and constants placed in a class definition are mapped into constants with the classname as a prefix. For example :<p>
<p>
<blockquote><pre>class Swig {
public:
	enum {ALE, LAGER, PORTER, STOUT};
};

</pre></blockquote>
Generates the following set of constants in the target scripting language :<p>
<p>
<blockquote><pre>Swig_ALE = Swig::ALE
Swig_LAGER = Swig::LAGER
Swig_PORTER = Swig::PORTER
Swig_STOUT = Swig::STOUT

</pre></blockquote>
Members declared as <tt>const</tt> are wrapped in a similar manner.<p>
<a name="n51"></a><h3> References</h3>
C++ references are supported, but SWIG will treat them as pointers. For example, a declaration like this :<p>
<p>
<blockquote><pre>class Foo {
public:
	double bar(double &amp;a);
}
</pre></blockquote>
<p>
will be accessed using a function like this :<p>
<p>
<blockquote><pre>double Foo_bar(Foo *obj, double *a) {
	obj-&gt;bar(*a);
}

</pre></blockquote>
Functions returning a reference will be mapped into functions returning pointers.<p>
<a name="n52"></a><h3> Inheritance</h3>
SWIG supports basic C++ public inheritance of classes and allows both single and multiple inheritance. The SWIG type-checker knows about the relationship between base and derived classes and will allow pointers to any object of a derived class to be used in functions of a base class. The type-checker properly casts pointer values and is safe to use with multiple inheritance.<p>
SWIG does not support private or protected inheritance (it will be parsed, but ignored).<p>
<p>
The following example shows how SWIG handles inheritance. For clarity, the full C++ code has been omitted.<p>
<p>
<blockquote><pre>// shapes.i
%module shapes
%{
#include "shapes.h"
%}

class Shape {
public:
	virtual double area() = 0;
	virtual double perimeter() = 0;
	void    set_location(double x, double y);
};
class Circle : public Shape {
public:
	Circle(double radius);
	~Circle();
	double area();
	double perimeter();
};
class Square : public Shape {
public:
	Square(double size);
	~Square();
	double area();
	double perimeter();
}
</pre></blockquote>
<p>
When wrapped into Perl5, we can now perform the following operations :<p>
<p>
<blockquote><pre>beazley@slack% perl5.003
use shapes;
$circle = shapes::new_Circle(7);
$square = shapes::new_Square(10);
print shapes::Circle_area($circle),"\n";
# Notice use of base class below
print shapes::Shape_area($circle),"\n";
print shapes::Shape_area($square),"\n";
shapes::Shape_set_location($square,2,-3);
print shapes::Shape_perimeter($square),"\n";
&lt;ctrl-d&gt;
153.93804004599999757
153.93804004599999757
100.00000000000000000
40.00000000000000000
 
</pre></blockquote>
In our example, we have created Circle and Square objects. We can call member functions on each object by making calls to <tt>Circle_area</tt>, <tt>Square_area</tt>, and so on. However, we can can accomplish the same thing by simply using the <tt>Shape_area</tt> function on either object.<p>
<a name="n53"></a><h3> Templates</h3>
SWIG does not support template definitions--that is, it does not support anything that would be declared in C++ using the `<tt>template</tt>' keyword. If a template definition is found, SWIG will issue a warning message and attempt to ignore the contents of the entire declaration. For example, a template class such as the following would be ignored by SWIG :<p>
<p>
<blockquote><pre>// File : list.h
#define MAXITEMS 100
template&lt;class T&gt; class List { 						// Entire class is ignored by SWIG
private:
    T *data;
    int nitems;
public:
    List() {
      data = new T [MAXITEMS];
      nitems = 0;
    }
    ~List() {
      delete [] data;
    };
    void append(T obj) {
      if (nitems &lt; MAXITEMS) {
        data[nitems++] = obj;
      }
    }
    int length() {
      return nitems;
    }
    T get(int n) {
      return data[n];
    }
};

</pre></blockquote>
However, SWIG can support instantiations of a template and types involving templates. For example, the following interface file would be legal :<p>
<p>
<blockquote><pre>// SWIG interface involving a template
%module example
%{
#include "list.h"				// Get Template definition 
%}

// Now a function involving templates
extern void PrintData(List&lt;double&gt; &amp;l);

</pre></blockquote>
The type "<tt>List&lt;double</tt>&gt;" becomes the datatype for the function parameter. In, Python it might appear like this :<p>
<p>
<blockquote><pre>&gt;&gt;&gt; print cl
_80a2df8_List&lt;double&gt;_p
&gt;&gt;&gt;

</pre></blockquote>
To create specific objects, you may need to supply helper functions such as the following :<p>
<blockquote><pre>
%inline %{
// Helper function to create a List&lt;double&gt;
List&lt;double&gt; *new_DoubleList() {
	return new List&lt;double&gt;;
}
%}
</pre></blockquote>
<p>
Specific templates can also be wrapped in a clever way using <tt>typedef.</tt> For example, the following would also work :<p>
<p>
<blockquote><pre>%module example
%{
#include "list.h"
typedef List&lt;double&gt; DoubleList;
%}

class DoubleList {
public:
	DoubleList();
	~DoubleList();
	void append(double);
	int length();
	double get(int n);
};

</pre></blockquote>
In this case, SWIG thinks that there is a class "<tt>DoubleList</tt>" with the methods supplied. It generates the appropriate code and everything works like you would expect (of course, in reality there is no such class). When the SWIG module is compiled, all of the methods get supplied by the original template class. A key thing to keep in mind when working with templates is that SWIG can only handle particular instantiations of a template (such as a list of double). More general support is not yet provided (but may be added someday).<p>
<a name="n54"></a><h3> Renaming</h3>
C++ member functions and data can be renamed with the <tt>%name</tt> directive. The <tt>%name</tt> directive only replaces the member function name. For example :<p>
<p>
<blockquote><pre>class List {
public:
  List();
%name(ListSize) List(int maxsize);
  ~List();
  int  search(char *value); 
%name(find)    void insert(char *); 
%name(delete)  void remove(char *); 
  char *get(int n);
  int  length;
static void print(List *l);
};

</pre></blockquote>
This will create the functions <tt>List_find</tt>, <tt>List_delete</tt>, and a function named <tt>new_ListSize</tt> for the overloaded constructor.<p>
<p>
The <tt>%name </tt>directive can be applied to all members including constructors, destructors, static functions, data members, and enumeration values.<p>
<p>
The class name prefix can be changed by specifying <p>
<p>
<blockquote><pre>%name(newname) class List {
...
}
</pre></blockquote>
<a name="n55"></a><h3> Adding new methods</h3>
New methods can be added to a class using the <tt>%addmethods</tt> directive. This directive is primarily used in conjunction with shadow classes to add additional functionality to an existing class. For example :<p>
<p>
<blockquote><pre>%module vector
%{
#include "vector.h"
%}

class Vector {
public:
	double x,y,z;
	Vector();
	~Vector();
	... bunch of C++ methods ...
	%addmethods {
		char *__str__() {
			static char temp[256];
			sprintf(temp,"[ %g, %g, %g ]", v-&gt;x,v-&gt;y,v-&gt;z);
			return &amp;temp[0];
		}
	}
};
</pre></blockquote>
<p>
This code adds a<tt> __str__</tt> method to our class for producing a string representation of the object. In Python, such a method would allow us to print the value of an object using the <tt>print</tt> command. <p>
<p>
<blockquote><pre>&gt;&gt;&gt;
&gt;&gt;&gt; v = Vector();
&gt;&gt;&gt; v.x = 3
&gt;&gt;&gt; v.y = 4
&gt;&gt;&gt; v.z = 0
&gt;&gt;&gt; print(v)
[ 3.0, 4.0, 0.0 ]
&gt;&gt;&gt;

</pre></blockquote>
The<tt> %addmethods</tt> directive follows all of the same conventions as its use with C structures.<p>
<a name="n56"></a><h3> Partial class definitions</h3>
Since SWIG is still somewhat limited in its support of C++, it may be necessary to only use partial class information in an interface file. This should not present a problem as SWIG does not need the exact C++ specification. As a general rule, you should strip all classes of operator overloading, friends, and other declarations before giving them to SWIG (although SWIG will generate only warnings for most of these things).<p>
<p>
As a rule of thumb, running SWIG on raw C++ header or source files is currently discouraged. Given the complexity of C++ parsing and limitations in SWIG's parser it will still take some time for SWIG's parser to evolve to a point of being able to safely handle most raw C++ files.<p>
<a name="n57"></a><h3> SWIG, C++, and the Legislation of Morality</h3>
As languages go, C++ is quite possibly one of the most immense and complicated languages ever devised. It is certainly a far cry from the somewhat minimalistic nature of C. Many parts of C++ are designed to build large programs that are "safe" and "reliable." However, as a result, it is possible for developers to overload operators, implement smart pointers, and do all sorts of other insane things (like expression templates). As far as SWIG is concerned, the primary goal is attaching to such systems and providing a scripting language interface. There are many features of C++ that I would not have the slightest idea how to support in SWIG (most kinds of templates for example). There are other C++ idioms that may be unsafe to use with SWIG. For example, if one implements "smart" pointers, how would they actually interact with the pointer mechanism used by SWIG? <p>
<p>
Needless to say, handling all of the possible cases is probably impossible. SWIG is certainly not guaranteed to work with every conceivable type of C++ program (especially those that use C++ in a maximal manner). Nor is SWIG claiming to build C++ interfaces in a completely "safe" manner. The bottom line is that effective use of C++ with SWIG requires that you know what you're doing and that you have a certain level of "moral flexibility" when it comes to the issue of building a useful scripting language interface.<p>
<a name="n58"></a><h3> The future of C++ and SWIG</h3>
SWIG's support of C++ is best described as an ongoing project. It will probably remain evolutionary in nature for the foreseeable future. In the short term, work is already underway for supporting nested classes and function overloading. As always, these developments will take time. Feedback and contributions are always welcome.<p>
<a name="n7"></a><h2> Objective-C</h2>
One of SWIG's most recent additions is support for Objective-C parsing. This is currently an experimental feature that may be improved in future releases. <p>
<p>
Objective-C support is built using the same approach as used for C++ parsing. Objective-C interface definitions are converted into a collection of ANSI C accessor functions. These accessor functions are then wrapped by SWIG and turned into an interface.<p>
<p>
To enable Objective-C parsing, SWIG should be given the <tt>-objc</tt> option (this option may be used in conjunction with the <tt>-c++</tt> option if using Objective-C++). It may also be helpful to use the -o option to give the output file the .m suffix needed by many Objective-C compilers. For example :<p>
<p>
<blockquote><pre>% swig -objc -o example_wrap.m example.i

</pre></blockquote>
Objective-C interfaces should also include the file `<tt>objc.i</tt>' as this contains important definitions that are common to most Objective-C programs. <p>
<a name="n59"></a><h3> Objective-C Example</h3>
The following code shows a SWIG interface file for a simple Objective-C class :<p>
<p>
<blockquote><pre>%module list
%{
#import "list.h"
%}
%include objc.i
// Very simple list class
@interface List : Object {
     int   nitems;                  // Number of items in the list
     int   maxitems;                // Maximum number of items
     id   *items;                   // Array holding the items
}
//-------------------------  List methods --------------------------

// Create a new list
+ new;

// Destroy the list
- free;

// Copy a list
- copy;

// Append a new item to the list
- (void) append: (id) item;

// Insert an item in the list
- (void) insert: (id) item : (int) pos;

// Delete an item from the list
-  remove: (int) pos;

// Get an item from the list
- get: (int) i;

// Find an item in the list and return its index
- (int) index: obj;

// Get length of the list
- (int) len;

// Print out a list (Class method)
+ (void) print: (List *) l;

@end

</pre></blockquote>
<a name="n60"></a><h3> Constructors and destructors</h3>
By default, SWIG assumes that the methods "new" and "free" correspond to constructors and destructors. These functions are translated into the following accessor functions :<p>
<p>
<blockquote><pre>List *new_List(void) {
	return (List *) [List new];
}
void delete_List(List *l) {
	[l free];
}

</pre></blockquote>
If the original Objective-C class does not have any constructors or destructors, putting them in the interface file will cause SWIG to generate wrappers for a default constructor and destructor (assumed to be defined in the object's base-class).<p>
<p>
If your Objective-C program uses a different naming scheme for constructors and destructors, you can tell SWIG about it using the following directive :<p>
<p>
<blockquote><pre>%pragma objc_new = "create" 					// Change constructor to `create'
%pragma objc_delete = "destroy" 					// Change destructor to `destroy'
</pre></blockquote>
<a name="n61"></a><h3> Instance methods</h3>
Instance methods are converted into accessor functions like this :<p>
<p>
<blockquote><pre>void List_append(List *l, id item) {
	[l append : item];
}
</pre></blockquote>
<a name="n62"></a><h3> Class methods</h3>
Class methods are translated into the following access function :<p>
<blockquote><pre>
void List_print(List *l) {
	[List print : l];
}
</pre></blockquote>
<a name="n63"></a><h3> Member data</h3>
Member data is handled in the same manner as for C++ with accessor functions being produced for getting and setting the value. By default, all data members of an Objective-C object are private unless explicitly declared <tt>@public</tt>. <p>
<a name="n64"></a><h3> Protection</h3>
SWIG can only wrap data members that are declared @public. Other protection levels are ignored.<p>
<a name="n65"></a><h3> The use of id</h3>
The datatype `<tt>id</tt>' assumes the same role in SWIG as it does with Objective-C. A function operating on an `id' will accept any Object type (works kind of like <tt>void *</tt>). All methods with no explicit return value are also assumed to return an `id'. <p>
<a name="n66"></a><h3> Inheritance</h3>
Essentially all Objective-C classes will inherit from a baseclass <tt>Object</tt>. If undefined, SWIG will generate a warning, but other function properly. A missing baseclass has no effect on the wrapper code or the operation of the resulting module. Really, the only side effect of a missing base class is that you will not be able to execute base-class methods from the scripting interface. Objective-C does not support multiple inheritance.<p>
<a name="n67"></a><h3> Referring to other classes</h3>
The<tt> @class</tt> declaration can be used to refer to other classes. SWIG uses this in certain instances to make sure wrapper code is generated correctly.<p>
<a name="n68"></a><h3> Categories</h3>
Categories provide a mechanism for adding new methods to existing Objective-C classes. SWIG correctly parses categories and attaches the methods to the wrappers created for the original class. For example :<p>
<p>
<blockquote><pre>%module example
%{
#import "foo.h"
%}

// Sample use of a category in an interface
@interface Foo (CategoryName)
// Method declarations
-bar : (id) i;
@end

</pre></blockquote>
<a name="n69"></a><h3> Implementations and Protocols</h3>
SWIG currently ignores all declarations found inside an <tt>@implementation</tt> or <tt>@protocol</tt> section. Support for this may be added in future releases.<p>
<p>
Although SWIG ignores protocols, protocol type-specifiers may be used. For example, these are legal declarations :<p>
<p>
<blockquote><pre>%module example

%interface Foo : Object &lt;proto1, proto2&gt; {

}
// Methods
- Bar : (id &lt;proto1,proto2&gt;) i;
@end

</pre></blockquote>
SWIG will carry the protocol lists through the code generation process so the resulting wrapper code compiles without warnings.<p>
<a name="n70"></a><h3> Renaming</h3>
Objective-C members can be renamed using the <tt>%name()</tt> directive as in :<p>
<p>
<blockquote><pre>@interface List : Object {
@public
%name(size) int length; 						// Rename length to size
}

+ new;
- free;
%name(add) -(void) append: (id) item;						// Rename append to add
@end

</pre></blockquote>
<a name="n71"></a><h3> Adding new methods</h3>
New methods can be added to a class using the <tt>%addmethods</tt> directive. This is primarily used with shadow classes to add additional functionality to a class. For example :<p>
<p>
<blockquote><pre>@interface List : Object {
}
... bunch of Objective-C methods ...
%addmethods {
	- (void) output {
		... code to output a list ...
	}
}
@end
</pre></blockquote>
<p>
<tt>%addmethods </tt>works in exactly the same manner as it does for C and C++ (except that Objective-C syntax is allowed). Consult those sections for more details.<p>
<a name="n72"></a><h3> Other issues</h3>
Objective-C is dynamically typed while SWIG tends to enforce a type-checking model on all of its pointer values. This mismatch could create operational problems with Objective-C code in the form of SWIG type errors. One solution to this (although perhaps not a good one) is to use the SWIG pointer library in conjunction with Objective-C. The pointer library provides simple functions for casting pointer types and manipulating values. <p>
<p>
Certain aspects of Objective-C are not currently supported (protocols for instance). These limitations may be lifted in future releases.<p>
<a name="n8"></a><h2> Conditional compilation</h2>
SWIG does not run the C preprocessor, but it does support conditional compilation of interface files in a manner similar to the C preprocessor. This can be done by placed <tt>#ifdef</tt>, <tt>#ifndef</tt>, <tt>#if</tt>, <tt>#else</tt>, <tt>#elif</tt>, and <tt>#endif</tt> directives in your interface file. These directives can be safely nested. This allows one to conditionally compile out troublesome C/C++ code if necessary. For example, the following file can serve as both a C header file and a SWIG interface file :<p>
<p>
<blockquote><pre>#ifdef SWIG
%module mymodule
%{
#include "header.h"
%}

%include wish.i
#endif

... normal C declarations here ...

</pre></blockquote>
<p>
Similarly, conditional compilation can be used to customize an interface. The following interface file can be used to build a Perl5 module that works with either static or dynamic linking :<p>
<p>
<blockquote><pre>
%module mymodule
%{
#include "header.h"
%}

... Declarations ...

#ifdef STATIC
%include perlmain.i 				// Include code for static linking
#endif

</pre></blockquote>
However, it is not safe to use conditional compilation in the middle of a declaration. For example :<p>
<p>
<blockquote><pre>double foo(
#ifdef ANSI_ARGS
double a, double b
#endif
);

</pre></blockquote>
This fails because the SWIG parser is not equipped to handle conditional compilation directives in an arbitrary location (like the C preprocessor). For files that make heavy use of the C preprocessor like this, it may be better to run the header file through the C preprocessor and use the output as the input to SWIG.<p>
<a name="n73"></a><h3> Defining symbols</h3>
To define symbols, you can use the <tt>-D</tt> option as in :<p>
<blockquote><pre>
swig -perl5 -static -DSTATIC interface.i

</pre></blockquote>
Symbols can also be defined using <tt>#define</tt> with no arguments. For example :<p>
<p>
<blockquote><pre>%module mymodule
#define STATIC 

... etc ...
</pre></blockquote>
<p>
For the purposes of conditional compilation, one should not assign values to symbols. If this is done, SWIG interprets the #define as providing the definition of a scripting language constant. <p>
<a name="n74"></a><h3> The #if directive</h3>
The <tt>#if</tt> directive can only be used in the following context :<p>
<blockquote><pre>
#if defined(SYMBOL)
...
#elif !defined(OTHERSYMBOL)
...
#endif
</pre></blockquote>
<p>
The C preprocessor version supports any constant integral expression as an argument to <tt>#if</tt>, but SWIG does not yet contain an expression evaluator so this is not currently supported. As a result, declarations such as the following don't yet work :<p>
<p>
<blockquote><pre>#if (defined(foo) || defined(bar))
...
#endif

</pre></blockquote>
<a name="n75"></a><h3> Predefined Symbols</h3>
One or more of the following symbols will be defined by SWIG when it is processing an interface file :<p>
<p>
<blockquote><pre>SWIG				Always defined when SWIG is processing a file
SWIGTCL				Defined when using Tcl
SWIGTCL8				Defined when using Tcl8.0
SWIGPERL				Defined when using Perl
SWIGPERL4				Defined when using Perl4
SWIGPERL5				Defined when using Perl5
SWIGPYTHON				Defined when using Python
SWIGGUILE				Defined when using Guile
SWIGWIN				Defined when running SWIG under Windows
SWIGMAC				Defined when running SWIG on the Macintosh

</pre></blockquote>
Interface files can look at these symbols as necessary to change the way in which an interface is generated or to mix SWIG directives with C code. These symbols are also defined within the C code generated by SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined within the SWIG compiler).<p>
<a name="n9"></a><h2> Code Insertion</h2>
Sometimes it is necessary to insert special code into the resulting wrapper file generated by SWIG.   For example, you may want to include additional C code to perform initialization or other operations.  There are four ways to insert code, but it's useful to know how the output of SWIG is structured first.<p>
<a name="n76"></a><h3> The output of SWIG</h3>
SWIG creates a single C source file containing wrapper functions, initialization code, and support code. The structure of this file is as follows :<p>
<center><img src="ch3.1.png"></center>

<p>
<p>
The headers portion typically contains header files, supporting code, helper functions, and forward declarations. If you look at it, you'll usually find a hideous mess since this also contains the SWIG run-time pointer type-checker and internal functions used by the wrapper functions. The "wrapper" portion of the output contains all of the wrapper functions. Finally, the initialization function is a single C function that is created to initialize your module when it is loaded.<p>
<a name="n77"></a><h3> Code blocks</h3>
A code block is enclosed by a <tt>%{, %}</tt> and is used to insert code into the header portion of the resulting wrapper file. Everything in the block is copied verbatim into the output file and will appear before any generated wrapper functions.   Most SWIG input files have at least one code block that is normally used to include header files and supporting C code.      Additional code blocks may be placed anywhere in a SWIG file as needed. <p>
<blockquote><pre>
%module mymodule
%{
#include "my_header.h"
%}

... Declare functions here
%{

... Include Tcl_AppInit() function here ...

%}
</pre></blockquote>
<p>
Code blocks are also typically used to write "helper" functions. These are functions that are used specifically for the purpose of building an interface and are generally not visible to the normal C program. For example :<p>
<p>
<blockquote><pre>%{

/* Create a new vector */
static Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}

%}

// Now wrap it 
Vector *new_Vector();

</pre></blockquote>
<a name="n78"></a><h3> Inlined code blocks</h3>
Because the process of writing helper functions is fairly common, there is a special inlined form of code block that is used as follows :<p>
<p>
<blockquote><pre>%inline %{
/* Create a new vector */
Vector *new_Vector() {
	return (Vector *) malloc(sizeof(Vector));
}
%}

</pre></blockquote>
The <tt>%inline</tt> directive inserts all of the code that follows verbatim into the header portion of an interface file. The code is then fed into the SWIG parser and turned into an interface. Thus, the above example creates a new command <tt>new_Vector</tt> using only one declaration. Since the code inside an <tt>%inline %{ ... %}</tt> block is given to both the C compiler and SWIG, it is illegal to include any SWIG directives inside the <tt>%{ ... %}</tt> block.<p>
<a name="n79"></a><h3> Initialization blocks</h3>
Code may also be inserted using an initialization block, as shown below :<p>
<p>
<blockquote><pre>%init %{

	init_variables();
%}
</pre></blockquote>
<p>
This code is inserted directly into SWIG's initialization function.    You can use it to perform additional initialization and operations.   Since this code is inserted directly into another function, it should not declare functions or include header files.   Primarily this can be used to add callouts to widgets and other packages that might also need to be initialized when your extension is loaded.<p>
<a name="n80"></a><h3> Wrapper code blocks</h3>
Code may be inserted in the wrapper code section of an output file using the <tt>%wrapper</tt> directive as shown :<p>
<p>
<blockquote><pre>%wrapper %{
	... a bunch of code ...
%}

</pre></blockquote>
This directive, for almost all practical purposes, is identical to just using a <tt>%{,%}</tt> block, but may be required for more sophisticated applications. It is mainly only used for advanced features in the SWIG library. As a general rule, you should avoid using this directive unless you absolutely know what you are doing.<p>
<a name="n10"></a><h2> A general interface building strategy</h2>
This section describes the general approach for building interface with SWIG. The specifics related to a particular scripting language are found in later chapters.<p>
<a name="n81"></a><h3> Preparing a C program for SWIG</h3>
SWIG doesn't require modifications to your C code, but if you feed it a collection of raw C header files or source code, the results might not be what you expect---in fact, they might be awful. Here's a series of steps you can follow to make an interface for a C program :<p>
<p>
<ul>
<li>Identify the functions that you want to wrap. It's probably not necessary to access every single function in a C program--thus, a little forethought can dramatically simplify the resulting scripting language interface. C header files are particularly good source for finding things to wrap.
<li>Create a new interface file to describe the scripting language interface to your program.
<li>Copy the appropriate declarations into the interface file or use SWIG's <tt>%include</tt> directive to process an entire C source/header file. Either way, this step is fairly easy.
<li>Make sure everything in the interface file uses ANSI C/C++syntax.
<li>Check to make sure there aren't any functions involving function pointers, or variable length arguments since SWIG doesn't like these very much.
<li>Eliminate unnecessary C preprocessor directives. SWIG will probably remove most of them, but better safe than sorry. Remember, SWIG does not run the C preprocessor.
<li>Make sure all necessary `<tt>typedef</tt>' declarations and type-information is available in the interface file.
<li>If your program has a main() function, you may need to rename it (read on).
<li>Run SWIG and compile.
</ul>
<p>
While this may sound complicated, the process turns out to be relatively easy in practice--for example, making an interface to the entire OpenGL library only takes about 5-10 minutes.<p>
<p>
In the process of building an interface, you are encouraged to use SWIG to find problematic declarations and specifications. SWIG will report syntax errors and other problems along with the associated file and line number. <p>
<a name="n82"></a><h3> The SWIG interface file</h3>
The preferred method of using SWIG is to generate separate interface file. Suppose you have the following C header file :<p>
<blockquote><pre>
/* File : header.h */

#include &lt;stdio.h&gt;
#include &lt;math.h&gt;

extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

</pre></blockquote>
A typical SWIG interface file for this header file would look like the following :<p>
<blockquote><pre>
/* File : interface.i */
%module mymodule
%{
#include "header.h"
%}
extern int foo(double);
extern double bar(int, int);
extern void dump(FILE *f);

</pre></blockquote>
Of course, in this case, our header file is pretty simple so we could have made an interface file like this as well:<p>
<p>
<blockquote><pre>/* File : interface.i */
%module mymodule
%include header.h
</pre></blockquote>
<p>
Naturally, your mileage may vary.<p>
<a name="n83"></a><h3> Why use separate interface files?</h3>
While SWIG can parse many header files, it is more common to write a special <tt>.i</tt> file defining the interface to a package. There are several reasons for doing this :<p>
<p>
<ul>
<li>It is rarely necessary to access every single function in a large package. Many C functions might have little or no use in a scripted environment. Therfore, why wrap them?
<li>Separate interface files provide an opportunity to provide more precise rules about how an interface is to be constructed.
<li>Interface files can provide structure and organization. For example , you can break the interface up into sections, provide documentation, and do other things that you might not normally do with an ordinary .h file.
<li>SWIG can't parse certain definitions that appear in header files. Having a separate file allows you to eliminate or work around these problems.
<li>Interface files provide a precise definition of what the interface is. Users wanting to extend the system can go to the interface file and immediately see what is available without having to dig it out of header files.
</ul>
<a name="n84"></a><h3> Getting the right header files</h3>
Sometimes, it is necessary to use certain header files in order for the code generated by SWIG to compile properly. You can have SWIG include certain header files by using a <tt>%{,%}</tt> block as follows :<p>
<blockquote><pre>
%module graphics
%{
#include &lt;GL/gl.h&gt;
#include &lt;GL/glu.h&gt;
%}

// Put rest of declarations here
...
</pre></blockquote>
<a name="n85"></a><h3> What to do with main()</h3>
If your program defines a <tt>main()</tt> function, you may need to get rid of it or rename it in order to use a scripting language. Most scripting languages define their own <tt>main()</tt> procedure that must be called instead. <tt>main()</tt> also makes no sense when working with dynamic loading. There are a few approaches to solving the <tt>main()</tt> conflict :<p>
<p>
<ul>
<li>Get rid of <tt>main()</tt> entirely. This is the brute force approach.
<li>Rename <tt>main()</tt> to something else. You can do this by compiling your C program with an option like <tt>-Dmain=oldmain</tt>.
<li>Use conditional compilation to only include <tt>main()</tt> when not using a scripting language.
</ul>
<p>
Getting rid of <tt>main()</tt> may cause potential initialization problems of a program. To handle this problem, you may consider writing a special function called <tt>program_init()</tt> that initializes your program upon startup. This function could then be called either from the scripting language as the first operation, or when the SWIG generated module is loaded.<p>
<p>
As a general note, many C programs only use the <tt>main()</tt> function to parse command line options and to set parameters. However, by using a scripting language, you are probably trying to create a program that is more interactive. In many cases, the old <tt>main()</tt> program can be completely replaced by a Perl, Python, or Tcl script.<p>
<a name="n86"></a><h3> Working with the C preprocessor</h3>
If you have a header file that makes heavy use of macros and C preprocessor directives, it may be useful to run it through the C preprocessor first. This can usually be done by running the C compiler with the -E option. The output will be completely hideous, but macros and other preprocessor directives should now be expanded as needed. If you want to wrap a C preprocessor macro with SWIG, this can be done by giving a function declaration with the same name and usage as the macro. When writing the macro as a function declaration, you are providing SWIG with type-information--without that, SWIG would be unable to produce any sort of wrapper code. <p>
<a name="n87"></a><h3> How to cope with C++</h3>
Given the complexity of C++, it will almost always be necessary to build a special interface file containing suitably edited C++ declarations. If you are working with a system involving 400 header files, this process will not be trivial. Perhaps the best word of advice is to think hard about what you want this interface to be. Also, is it absolutely critical to wrap every single function in a C++ program? SWIG's support of C++ will improve with time, but I'll be the first to admit that SWIG works much better with pure ANSI C code when it comes to large packages.<p>
<a name="n88"></a><h3> How to avoid creating the interface from hell</h3>
SWIG makes it pretty easy to build a big interface really fast. In fact, if you apply it to a large enough package, you'll find yourself with a rather large chunk of code being produced in the resulting wrapper file. To give you an idea, wrapping a 1000 line C header file with a large number of structure declarations may result in a wrapper file containing 20,000-30,000 lines of code. I can only imagine what wrapping a huge C++ class hierarchy would generate. Here's a few rules of thumb for making smaller interfaces :<p>
<p>
<ul>
<li>Ask yourself if you really need to access particular functions. It is usually not necessary to wrap every single function in a package. In fact, you probably only need a relatively small subset.
<li>SWIG does not require structure definitions to operate. If you are never going to access the members of a structure, don't wrap the structure definition. 
<li>Eliminate unneeded members of C++ classes.
<li>Think about the problem at hand. If you are only using a subset of some library, there is no need to wrap the whole thing.
<li>Write support or helper functions to simplify common operations. Some C functions may not be easy to use in a scripting language environment. You might consider writing an alternative version and wrapping that instead.
</ul>
<p>
Writing a nice interface to a package requires work. Just because you use SWIG it doesn't mean that you're going to end up with a good interface. SWIG is primarily designed to eliminate the tedious task of writing wrapper functions. It does not eliminate the need for proper planning and design when it comes to building a useful application. In short, a little forethought can go a long way.<p>
<p>
Of course,if you're primarily interested in just slapping something together for the purpose of debugging, rapid application development, and prototyping, SWIG will gladly do it for you (in fact, I use SWIG alot for this when developing other C/C++ applications).<p>
<p>

<p><hr>

<address>SWIG 1.1 - Last Modified : Mon Aug  4 10:46:53 1997</address>
</body>
</html>