This commit was manufactured by cvs2svn to create tag 'rel-1-3-26'.
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/tags/rel-1-3-26@7639 626c5289-ae23-0410-ae9c-e8d60b6d4f22
diff --git a/swigweb/Doc1.1/HTML/About.html b/swigweb/Doc1.1/HTML/About.html
deleted file mode 100644
index 56f9c60..0000000
--- a/swigweb/Doc1.1/HTML/About.html
+++ /dev/null
@@ -1,51 +0,0 @@
-<html>
-<head>
-<title>About this manual</title>
-</head>
-
-<body bgcolor="#ffffff">
-<h1>About This Manual</h1><p>
-
-The HTML version of the SWIG Users Manual is a direct translation
-of the printed version which is produced using Framemaker 5. The
-conversion process was roughly as follows :
-
-<ul>
-<li> Raw HTML was produced using Framemaker 5 and Quadralay WebWorks Lite.
-<li> Tables and figures were converted into GIF images.
-<li> All of this output was fed into a magic Python script that cleaned
-up the HTML source and merged the GIF figures into the text.
-<li> A table of contents and alphabetized topic index were produced from
-HTML heading tags by the same script.
-</ul>
-
-While the conversion process is mostly complete, there are a few things
-to keep in mind :
-
-<ul>
-<li> Some sections of preformatted text may have weird formatting
-problems.
-<li> Framemaker tables were converted into GIF images instead
-of HTML tables--this is a little weird, but the easiest
-approach for now.
-<li> There may be a few minor formatting problems throughout
-due to minor "glitches" that slipped through the conversion process
-(although I've tried to correct as many as these as possible).
-<li> The printed version of the SWIG manual is more than
-300 pages long--resulting in about 670 Kbytes of HTML. The HTML version
-is broken up into chapters. Each chapter is fairly well-contained, but
-some may contain as many as 50 pages of printed text.
-</ul>
-
-Please report any problems with the documentation to beazley@cs.utah.edu.
-
-<hr>
-<address>
-Last Modified : August 3, 1997</address>
-</body>
-</html>
-
-
-
-
-
diff --git a/swigweb/Doc1.1/HTML/Advanced.html b/swigweb/Doc1.1/HTML/Advanced.html
deleted file mode 100644
index c955990..0000000
--- a/swigweb/Doc1.1/HTML/Advanced.html
+++ /dev/null
@@ -1,305 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Advanced Topics</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>11 Advanced Topics</h1><p><ul>
-<li> <a href="#n1">Creating multi-module packages</a>
-<li> <a href="#n2">Dynamic Loading of C++ modules</a>
-<li> <a href="#n3">Inside the SWIG type-checker</a>
-</ul>
-
-<a name="n1"></a><h2> Creating multi-module packages</h2>
-SWIG can be used to create packages consisting of many different modules. However, there are some technical aspects of doing this and techniques for managing the problem.<p>
-<a name="n4"></a><h3> Runtime support (and potential problems)</h3>
-All SWIG generated modules rely upon a small collection of functions that are used during run-time. These functions are primarily used for pointer type-checking, exception handling, and so on. When you run SWIG, these functions are included in the wrapper file (and declared as static). If you create a system consisting of many modules, each one will have an identical copy of these runtime libraries :<p>
-<center><img src="ch11.1.png"></center><p>
-<p>
-This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next).<p>
-<a name="n5"></a><h3> Why doesn't C++ inheritance work between modules?</h3>
-Consider for a moment the following two interface files :<p>
-<p>
-<blockquote><pre>// File : a.i
-%module a
-
-// Here is a base class
-class a {
-public:
- a();
- ~a();
- void foo(double);
-};
-
-
-// File : b.i
-%module b
-
-// Here is a derived class
-%extern a.i // Gets definition of base class
-
-class b : public a {
-public:
- bar();
-};
-
-</pre></blockquote>
-When compiled into two separate modules, the code does not work properly. In fact, you get a type error such as the following :<p>
-<p>
-<blockquote><pre>[beazley@guinness shadow]$ python
-Python 1.4 (Jan 16 1997) [GCC 2.7.2]
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> from a import *
->>> from b import *
->>> # Create a new "b"
->>> b = new_b()
->>> # Call a function in the base class
-...
->>> a_foo(b,3)
-Traceback (innermost last):
- File "<stdin>", line 1, in ?
-TypeError: Type error in argument 1 of a_foo. Expected _a_p.
->>>
-</pre></blockquote>
-<p>
-However, from our class definitions we know that "b" is an "a" by inheritance and there should be no type-error. This problem is directly due to the lack of type-sharing between modules. If we look closely at the module modules created here, they look like this :<p>
-<center><img src="ch11.2.png"></center><p>
-<p>
-The type information listed shows the acceptable values for various C datatypes. In the "a" module, we see that "a" can only accept instances of itself. In the "b" module, we see that "a" can accept both "a" and "b" instances--which is correct given that a "b" is an "a" by inheritance.<p>
-<p>
-Unfortunately, this problem is inherent in the method by which SWIG makes modules. When we made the "a" module, we had no idea what derived classes might be used at a later time. However, it's impossible to produce the proper type information until after we know all of the derived classes. A nice problem to be sure, but one that can be fixed by making all modules share a single copy of the SWIG run-time library.<p>
-<a name="n6"></a><h3> The SWIG runtime library</h3>
-To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules. This requires the use of the SWIG runtime library which is optionally built during SWIG installation. To use the runtime libraries, follow these steps :<p>
-<p>
-1. Build the SWIG run-time libraries. The <tt>SWIG1.1/Runtime</tt> directory contains a makefile for doing this. If successfully built, you will end up with 6 files that are usually installed in <tt>/usr/local/lib</tt>.<p>
-<p>
-<blockquote><pre>libswigtcl.a # Tcl library (static)
-libswigtcl.so # Tcl library (shared)
-libswigpl.a # Perl library (static)
-libswigpl.so # Perl library (shared)
-libswigpy.a # Python library (static)
-libswigpy.so # Python library (shared)
-</pre></blockquote>
-<p>
-Note that certain libraries may be missing due to missing packages or unsupported features (like dynamic loading) on your machine.<p>
-<p>
-2. Compile all SWIG modules using the <tt>-c</tt> option. For example :<p>
-<p>
-<blockquote><pre>% swig -c -python a.i
-% swig -c -python b.i
-
-</pre></blockquote>
-The <tt>-c</tt> option tells SWIG to omit runtime support. It's now up to you to provide it separately--which we will do using our libraries.<p>
-<p>
-3. Build SWIG modules by linking against the appropriate runtime libraries.<p>
-<p>
-<blockquote><pre>% swig -c -python a.i
-% swig -c -python b.i
-% gcc -c a_wrap.c b_wrap.c -I/usr/local/include
-% ld -shared a_wrap.o b_wrap.o -lswigpy -o a.so
-
-</pre></blockquote>
-or if building a new executable (static linking)<p>
-<p>
-<blockquote><pre>% swig -c -tcl -ltclsh.i a.i
-% gcc a_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl -lm -o mytclsh
-
-</pre></blockquote>
-<p>
-When completed you should now end up with a collection of modules like this :<p>
-<center><img src="ch11.3.png"></center><p>
-<p>
-<p>
-In this configuration, the runtime library manages all datatypes and other information between modules. This management process is dynamic in nature--when new modules are loaded, they contribute information to the run-time system. In the C++ world, one could incrementally load classes as needed. As this process occurs, type information is updated and base-classes learn about derived classes as needed.<p>
-<a name="n7"></a><h3> A few dynamic loading gotchas</h3>
-When working with dynamic loading, it is critical to check that only one copy of the run-time library is being loaded into the system. When working with <tt>.a</tt> library files, problems can sometimes occur so there are a few approaches to the problem.<p>
-<p>
-1. Rebuild the scripting language executable with the SWIG runtime library attached to it. This is actually, fairly easy to do using SWIG. For example :<p>
-<p>
-<blockquote><pre>%module mytclsh
-%{
-
-static void *__embedfunc(void *a) { return a};
-%}
-
-void *__embedfunc(void *);
-%include tclsh.i
-
-</pre></blockquote>
-<p>
-Now, run SWIG and compile as follows :<p>
-<p>
-<blockquote><pre>% swig -c -tcl mytclsh.i
-% gcc mytclsh_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lswigtcl -ldl -lm \
- -o tclsh
-
-</pre></blockquote>
-This produces a new executable "<tt>tclsh</tt>" that contains a copy of the SWIG runtime library. The weird <tt>__embedfunc()</tt> function is needed to force the functions in the runtime library to be included in the final executable. <p>
-<p>
-To make new dynamically loadable SWIG modules, simply compile as follows :<p>
-<p>
-<blockquote><pre>% swig -c -tcl example.i
-% gcc -c example_wrap.c -I/usr/local/include
-% ld -shared example_wrap.o -o example.so
-
-</pre></blockquote>
-Linking against the <tt>swigtcl</tt> library is no longer necessary as all of the functions are now included in the <tt>tclsh</tt> executable and will be resolved when your module is loaded.<p>
-<p>
-2. Using shared library versions of the runtime library<p>
-<p>
-If supported on your machine, the runtime libraries will be built as shared libraries (indicated by a <tt>.so</tt>, <tt>.sl</tt>, or .<tt>dll</tt> suffix). To compile using the runtime libraries, you link process should look something like this :<p>
-<blockquote><pre>
-% ld -shared swigtcl_wrap.o -o libswigtcl.so # Irix
-% gcc -shared swigtcl_wrap.o -o libswigtcl.so # Linux
-% ld -G swigtcl_wrap.o -o libswigtcl.so # Solaris
-</pre></blockquote>
-In order for the <tt>libswigtcl.so</tt> library to work, it needs to be placed in a location where the dynamic loader can find it. Typically this is a system library directory (ie. <tt>/usr/local/lib</tt> or <tt>/usr/lib</tt>). <p>
-<p>
-When running with the shared libary version, you may get error messages such as the following <p>
-<p>
-<blockquote><pre>Unable to locate libswigtcl.so
-
-</pre></blockquote>
-This indicates that the loader was unable to find the shared libary at run-time. To find shared libaries, the loader looks through a collection of predetermined paths. If the <tt>libswigtcl.so</tt> file is not in any of these directories, it results in an error. On most machines, you can change the loader search path by changing the Unix environment variable <tt>LD_LIBRARY_PATH</tt>. For example :<p>
-<p>
-<blockquote><pre>% setenv LD_LIBRARY_PATH .:/home/beazley/packages/lib
-
-</pre></blockquote>
-A somewhat better approach is to link your module with the proper path encoded. This is typically done using the `-rpath' or `-R' option to your linker (see the man page). For example :<p>
-<p>
-<blockquote><pre>% ld -shared example_wrap.o example.o -rpath /home/beazley/packages/lib \
- -L/home/beazley/packages/lib -lswigtcl.so -o example.so
-
-</pre></blockquote>
-The <tt>-rpath</tt> option encodes the location of shared libraries into your modules and gets around having to set the <tt>LD_LIBRARY_PATH</tt> variable. <p>
-<p>
-If all else fails, pull up the man pages for your linker and start playing around. <p>
-<a name="n2"></a><h2> Dynamic Loading of C++ modules</h2>
-Dynamic loading of C++ modules presents a special problem for many systems. This is because C++ modules often need additional supporting code for proper initialization and operation. Static constructors are also a bit of a problem.<p>
-<p>
-While the process of building C++ modules is, by no means, and exact science, here are a few rules of thumb to follow :<p>
-<p>
-<ul>
-<li>Don't use static constructors if at all possible (not always avoidable).
-<li>Try linking your module with the C++ compiler using a command like `c++ -shared'. This often solves alot of problems.
-<li>Sometimes it is necessary to link against special libraries. For example, modules compiled with g++ often need to be linked against the <tt>libgcc.a</tt>, <tt>libg++.a</tt>, and <tt>libstdc++.a</tt> libraries.
-<li>Read the compiler and linker man pages over and over until you have them memorized (this may not help in some cases however).
-<li>Search articles on Usenet, particularly in <tt>comp.lang.tcl</tt>, <tt>comp.lang.perl</tt>, and <tt>comp.lang.python</tt>. Building C++ modules is a common problem.
-</ul>
-<p>
-The SWIG distribution contains some additional documentation about C++ modules in the Doc directory as well.<p>
-<a name="n3"></a><h2> Inside the SWIG type-checker</h2>
-The SWIG runtime type-checker plays a critical role in the correct operation of SWIG modules. It not only checks the validity of pointer types, but also manages C++ inheritance, and performs proper type-casting of pointers when necessary. This section provides some insight into what it does, how it works, and why it is the way it is.<p>
-<a name="n8"></a><h3> Type equivalence</h3>
-SWIG uses a name-based approach to managing pointer datatypes. For example, if you are using a pointer like "<tt>double *</tt>", the type-checker will look for a particular string representation of that datatype such as "<tt>_double_p</tt>". If no match is found, a type-error is reported.<p>
-<p>
-However, the matching process is complicated by the fact that datatypes may use a variety of different names. For example, the following declarations<p>
-<p>
-<blockquote><pre>typedef double Real;
-typedef Real * RealPtr;
-typedef double Float;
-
-</pre></blockquote>
-define two sets of equivalent types :<p>
-<p>
-<blockquote><pre>{double, Real, Float}
-{RealPtr, Real *}
-
-</pre></blockquote>
-All of the types in each set are freely interchangable and the type-checker knows about the relationships by managing a table of equivalences such as the following :<p>
-<blockquote><pre>
-double => { Real, Float }
-Real => { double, Float }
-Float => { double, Real }
-RealPtr => { Real * }
-Real * => { RealPtr }
-
-</pre></blockquote>
-<p>
-When you declare a function such as the following :<p>
-<p>
-<blockquote><pre>void foo(Real *a);
-
-</pre></blockquote>
-SWIG first checks to see if the argument passed is a "<tt>Real *</tt>". If not, it checks to see if it is any of the other equivalent types (<tt>double *</tt>, <tt>RealPtr</tt>, <tt>Float *</tt>). If so, the value is accepted and no error occurs.<p>
-<p>
-Derived versions of the various datatypes are also legal. For example, if you had a function like this,<p>
-<p>
-<blockquote><pre>void bar(Float ***a);
-
-</pre></blockquote>
-The type-checker will accept pointers of type <tt>double ***</tt> and <tt>Real ***.</tt> However, the type-checker does not always capture the full-range of possibilities. For example, a datatype of `<tt>RealPtr **</tt>' is equivalent to a `<tt>Float ***</tt>' but would be flagged as a type error. If you encounter this kind of problem, you can manually force SWIG to make an equivalence as follows:<p>
-<p>
-<blockquote><pre>// Tell the type checker that `Float_ppp' and `RealPtr_pp' are equivalent.
-%init %{
- SWIG_RegisterMapping("Float_ppp","RealPtr_pp",0);
-%}
-
-</pre></blockquote>
-Doing this should hardly ever be necessary (I have never encountered a case where this was necessary), but if all else fails, you can force the run-time type checker into doing what you want.<p>
-<p>
-Type-equivalence of C++ classes is handled in a similar manner, but is encoded in a manner to support inheritance. For example, consider the following classes hierarchy :<p>
-<p>
-<blockquote><pre>class A { };
-class B : public A { };
-class C : public B { };
-class D {};
-class E : public C, public D {};
-
-</pre></blockquote>
-The type-checker encodes this into the following sets :<p>
-<p>
-<blockquote><pre>A => { B, C, E } "B isa A, C isa A, E isa A"
-B => { C, E } "C isa B, E isa B"
-C => { E } "E isa C"
-D => { E } "E isa D"
-E => { }
-
-</pre></blockquote>
-The encoding reflects the class hierarchy. For example, any object of type "A" will also accept objects of type B,C, and E because these are all derived from A. However, it is not legal to go the other way. For example, a function operating on a object from class E will not accept an object from class A.<p>
-<a name="n9"></a><h3> Type casting</h3>
-When working with C++ classes, SWIG needs to perform proper typecasting between derived and base classes. This is particularly important when working with multiple inheritance. To do this, conversion functions are created such as the following :<p>
-<p>
-<blockquote><pre>void *EtoA(void *ptr) {
- E *in = (E *) ptr;
- A *out = (A *) in; // Cast using C++
- return (void *) out;
-}
-
-</pre></blockquote>
-All pointers are internally represented as void *, but conversion functions are always invoked when pointer values are converted between base and derived classes in a C++ class hierarchy.<p>
-<a name="n10"></a><h3> Why a name based approach?</h3>
-SWIG uses a name-based approach to type-checking for a number of reasons :<p>
-<p>
-<ul>
-<li>One of SWIG's main uses is code development and debugging. In this environment, the type name of an object turns out to be a useful piece of information in tracking down problems.
-<li>In languages like Perl, the name of a datatype is used to determine things like packages and classes. By using datatype names we get a natural mapping between C and Perl.
-<li>I believe using the original names of datatypes is more intuitive than munging them into something completely different.
-</ul>
-<p>
-An alternative to a name based scheme would be to generate type-signatures based on the structure of a datatype. Such a scheme would result in perfect type-checking, but I think it would also result in a very confusing scripting language module. For this reason, I see SWIG sticking with the name-based approach--at least for the foreseeable future. <p>
-<a name="n11"></a><h3> Performance of the type-checker</h3>
-The type-checker performs the following steps when matching a datatype :<p>
-<p>
-
-<dl>
-<dt>1. Check a pointer against the type supplied in the original C declaration. If there is a perfect match, we're done.
-<dt>2. Check the supplied pointer against a cache of recently used datatypes.
-<dt>3. Search for a match against the full list of equivalent datatypes.
-<dt>4. If not found, report an error.
-
-</dl>
-<p>
-Most well-structured C codes will find an exact match on the first attempt, providing the best possible performance. For C++ codes, it is quite common to be passing various objects of a common base-class around between functions. When base-class functions are invoked, it almost always results in a miscompare (because the type-checker is looking for the base-type). In this case, we drop down to a small cache of recently used datatypes. If we've used a pointer of the same type recently, it will be in the cache and we can match against it. For tight loops, this results in about 10-15% overhead over finding a match on the first try. Finally, as a last resort, we need to search the internal pointer tables for a match. This involves a combination of hash table lookup and linear search. If a match is found, it is placed into the cache and the result returned. If not, we finally report a type-mismatch.<p>
-<p>
-As a rule of thumb, C++ programs require somewhat more processing than C programs, but this seems to be avoidable. Also, keep in mind that performance penalties in the type-checker don't necessarily translate into big penalties in the overall application. Performance is most greatly affected by the efficiency of the target scripting language and the types of operations your C code is performing.<p>
-<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:13 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Contents.html b/swigweb/Doc1.1/HTML/Contents.html
deleted file mode 100644
index d7e5e5b..0000000
--- a/swigweb/Doc1.1/HTML/Contents.html
+++ /dev/null
@@ -1,184 +0,0 @@
-
-<html>
-<head>
-<title> SWIG 1.1 Users Manual - Table of Contents </title>
-</head>
-<body bgcolor="#ffffff">
-
-<h1> SWIG 1.1 Users Manual </h1>
-
-<ul>
-<li> <a href="Copyright.html">Copyright</a>
-<li> <a href="About.html">About this manual</a>
-<li> <a href="Index.html">Alphabetical Topic Index</a>
-</ul>
-<h2><a href="Preface.html">Preface</a></h2><p><ul>
-<li> <a href="Preface.html#n1">Introduction</a>
-<li> <a href="Preface.html#n2">SWIG resources</a>
-<li> <a href="Preface.html#n3">About this manual</a>
-<li> <a href="Preface.html#n4">Credits</a>
-<li> <a href="Preface.html#n5">What's new?</a>
-<li> <a href="Preface.html#n6">Bug reports</a>
-<li> <a href="Preface.html#n7">SWIG is free</a>
-</ul>
-<h2><a href="Introduction.html">1 Introduction</a></h2><p><ul>
-<li> <a href="Introduction.html#n1">What is SWIG?</a>
-<li> <a href="Introduction.html#n2">Life before SWIG</a>
-<li> <a href="Introduction.html#n3">Life after SWIG</a>
-<li> <a href="Introduction.html#n4">The SWIG package</a>
-<li> <a href="Introduction.html#n5">A SWIG example</a>
-<li> <a href="Introduction.html#n6">C syntax, but not a C compiler</a>
-<li> <a href="Introduction.html#n7">Non-intrusive interface building</a>
-<li> <a href="Introduction.html#n8">Hands off code generation</a>
-<li> <a href="Introduction.html#n9">Event driven C programming</a>
-<li> <a href="Introduction.html#n10">Automatic documentation generation</a>
-<li> <a href="Introduction.html#n11">Summary</a>
-<li> <a href="Introduction.html#n12">SWIG for Windows and Macintosh</a>
-</ul>
-<h2><a href="Scripting.html">2 Scripting Languages</a></h2><p><ul>
-<li> <a href="Scripting.html#n1">The two language view of the world</a>
-<li> <a href="Scripting.html#n2">How does a scripting language talk to C?</a>
-<li> <a href="Scripting.html#n3">Building scripting language extensions</a>
-<li> <a href="Scripting.html#n4">Shared libraries and dynamic loading</a>
-</ul>
-<h2><a href="SWIG.html">3 SWIG Basics</a></h2><p><ul>
-<li> <a href="SWIG.html#n1">Running SWIG</a>
-<li> <a href="SWIG.html#n2">Simple C functions, variables, and constants</a>
-<li> <a href="SWIG.html#n3">Pointers and complex objects</a>
-<li> <a href="SWIG.html#n4">Getting down to business</a>
-<li> <a href="SWIG.html#n5">Structures, unions, and object oriented C programming</a>
-<li> <a href="SWIG.html#n6">C++ support</a>
-<li> <a href="SWIG.html#n7">Objective-C</a>
-<li> <a href="SWIG.html#n8">Conditional compilation</a>
-<li> <a href="SWIG.html#n9">Code Insertion</a>
-<li> <a href="SWIG.html#n10">A general interface building strategy</a>
-</ul>
-<h2><a href="Library.html">4 Multiple files and the SWIG library</a></h2><p><ul>
-<li> <a href="Library.html#n1">The %include directive</a>
-<li> <a href="Library.html#n2">The %extern directive</a>
-<li> <a href="Library.html#n3">The %import directive</a>
-<li> <a href="Library.html#n4">Including files on the command line</a>
-<li> <a href="Library.html#n5">The SWIG library</a>
-<li> <a href="Library.html#n6">Library example</a>
-<li> <a href="Library.html#n7">Creating Library Files</a>
-<li> <a href="Library.html#n8">Working with library files</a>
-<li> <a href="Library.html#n9">Static initialization of multiple modules</a>
-<li> <a href="Library.html#n10">More about the SWIG library</a>
-</ul>
-<h2><a href="Documentation.html">5 Documentation System</a></h2><p><ul>
-<li> <a href="Documentation.html#n1">Introduction</a>
-<li> <a href="Documentation.html#n2">How it works</a>
-<li> <a href="Documentation.html#n3">Choosing a documentation format</a>
-<li> <a href="Documentation.html#n4">Function usage and argument names</a>
-<li> <a href="Documentation.html#n5">Titles, sections, and subsections</a>
-<li> <a href="Documentation.html#n6">Formatting</a>
-<li> <a href="Documentation.html#n7">Adding Additional Text</a>
-<li> <a href="Documentation.html#n8">Disabling all documentation</a>
-<li> <a href="Documentation.html#n9">An Example</a>
-<li> <a href="Documentation.html#n10">ASCII Documentation</a>
-<li> <a href="Documentation.html#n11">HTML Documentation</a>
-<li> <a href="Documentation.html#n12">LaTeX Documentation</a>
-<li> <a href="Documentation.html#n13">C++ Support</a>
-<li> <a href="Documentation.html#n14">The Final Word?</a>
-</ul>
-<h2><a href="Typemaps.html">6 Pointers, Constraints, and Typemaps</a></h2><p><ul>
-<li> <a href="Typemaps.html#n1">Introduction</a>
-<li> <a href="Typemaps.html#n2">The SWIG Pointer Library</a>
-<li> <a href="Typemaps.html#n3">Introduction to typemaps</a>
-<li> <a href="Typemaps.html#n4">Managing input and output parameters</a>
-<li> <a href="Typemaps.html#n5">Applying constraints to input values</a>
-<li> <a href="Typemaps.html#n6">Writing new typemaps</a>
-<li> <a href="Typemaps.html#n7">Common typemap methods</a>
-<li> <a href="Typemaps.html#n8">Writing typemap code</a>
-<li> <a href="Typemaps.html#n9">Typemaps for handling arrays</a>
-<li> <a href="Typemaps.html#n10">Typemaps and the SWIG Library</a>
-<li> <a href="Typemaps.html#n11">Implementing constraints with typemaps</a>
-<li> <a href="Typemaps.html#n12">Typemap examples</a>
-<li> <a href="Typemaps.html#n13">How to break everything with a typemap</a>
-<li> <a href="Typemaps.html#n14">Typemaps and the future</a>
-</ul>
-<h2><a href="Exceptions.html">7 Exception Handling</a></h2><p><ul>
-<li> <a href="Exceptions.html#n1">The %except directive</a>
-<li> <a href="Exceptions.html#n2">Handling exceptions in C code</a>
-<li> <a href="Exceptions.html#n3">Exception handling with longjmp()</a>
-<li> <a href="Exceptions.html#n4">Handling C++ exceptions</a>
-<li> <a href="Exceptions.html#n5">Defining different exception handlers</a>
-<li> <a href="Exceptions.html#n6">Using The SWIG exception library</a>
-<li> <a href="Exceptions.html#n7">Debugging and other interesting uses for %except</a>
-<li> <a href="Exceptions.html#n8">More Examples</a>
-</ul>
-<h2><a href="Perl5.html">8 SWIG and Perl5</a></h2><p><ul>
-<li> <a href="Perl5.html#n1">Preliminaries</a>
-<li> <a href="Perl5.html#n2">Building Perl Extensions under Windows 95/NT</a>
-<li> <a href="Perl5.html#n3">Modules, packages, and classes</a>
-<li> <a href="Perl5.html#n4">Basic Perl interface</a>
-<li> <a href="Perl5.html#n5">A simple Perl example</a>
-<li> <a href="Perl5.html#n6">Accessing arrays and other strange objects</a>
-<li> <a href="Perl5.html#n7">Implementing methods in Perl</a>
-<li> <a href="Perl5.html#n8">Shadow classes</a>
-<li> <a href="Perl5.html#n9">Getting serious</a>
-<li> <a href="Perl5.html#n10">Wrapping C libraries and other packages</a>
-<li> <a href="Perl5.html#n11">Building a Perl5 interface to MATLAB</a>
-<li> <a href="Perl5.html#n12">Handling output values (the easy way)</a>
-<li> <a href="Perl5.html#n13">Exception handling</a>
-<li> <a href="Perl5.html#n14">Remapping datatypes with typemaps</a>
-<li> <a href="Perl5.html#n15">The gory details on shadow classes</a>
-<li> <a href="Perl5.html#n16">Where to go from here?</a>
-</ul>
-<h2><a href="Python.html">9 SWIG and Python</a></h2><p><ul>
-<li> <a href="Python.html#n1">Preliminaries</a>
-<li> <a href="Python.html#n2">Building Python Extensions under Windows 95/NT</a>
-<li> <a href="Python.html#n3">The low-level Python/C interface</a>
-<li> <a href="Python.html#n4">Python shadow classes</a>
-<li> <a href="Python.html#n5">About the Examples</a>
-<li> <a href="Python.html#n6">Solving a simple heat-equation</a>
-<li> <a href="Python.html#n7">Wrapping a C library</a>
-<li> <a href="Python.html#n8">Putting it all together</a>
-<li> <a href="Python.html#n9">Exception handling</a>
-<li> <a href="Python.html#n10">Remapping C datatypes with typemaps</a>
-<li> <a href="Python.html#n11">Implementing C callback functions in Python</a>
-<li> <a href="Python.html#n12">Other odds and ends</a>
-<li> <a href="Python.html#n13">The gory details of shadow classes</a>
-</ul>
-<h2><a href="Tcl.html">10 SWIG and Tcl</a></h2><p><ul>
-<li> <a href="Tcl.html#n1">Preliminaries</a>
-<li> <a href="Tcl.html#n2">Building Tcl/Tk Extensions under Windows 95/NT</a>
-<li> <a href="Tcl.html#n3">Basic Tcl Interface</a>
-<li> <a href="Tcl.html#n4">The object oriented interface</a>
-<li> <a href="Tcl.html#n5">About the examples</a>
-<li> <a href="Tcl.html#n6">Binary trees in Tcl</a>
-<li> <a href="Tcl.html#n7">Building C/C++ data structures with Tk</a>
-<li> <a href="Tcl.html#n8">Accessing arrays</a>
-<li> <a href="Tcl.html#n9">Building a simple OpenGL module</a>
-<li> <a href="Tcl.html#n10">Exception handling</a>
-<li> <a href="Tcl.html#n11">Typemaps</a>
-<li> <a href="Tcl.html#n12">Configuration management with SWIG</a>
-<li> <a href="Tcl.html#n13">Building new kinds of Tcl interfaces (in Tcl)</a>
-<li> <a href="Tcl.html#n14">Extending the Tcl Netscape Plugin</a>
-<li> <a href="Tcl.html#n15">Tcl8.0 features</a>
-</ul>
-<h2><a href="Advanced.html">11 Advanced Topics</a></h2><p><ul>
-<li> <a href="Advanced.html#n1">Creating multi-module packages</a>
-<li> <a href="Advanced.html#n2">Dynamic Loading of C++ modules</a>
-<li> <a href="Advanced.html#n3">Inside the SWIG type-checker</a>
-</ul>
-<h2><a href="Extending.html">12 Extending SWIG</a></h2><p><ul>
-<li> <a href="Extending.html#n1">Introduction</a>
-<li> <a href="Extending.html#n2">Compiling a SWIG extension</a>
-<li> <a href="Extending.html#n3">SWIG output</a>
-<li> <a href="Extending.html#n4">The Language class (simple version)</a>
-<li> <a href="Extending.html#n5">A tour of SWIG datatypes</a>
-<li> <a href="Extending.html#n6">Typemaps (from C)</a>
-<li> <a href="Extending.html#n7">File management</a>
-<li> <a href="Extending.html#n8">Naming Services</a>
-<li> <a href="Extending.html#n9">Code Generation Functions</a>
-<li> <a href="Extending.html#n10">Writing a Real Language Module</a>
-<li> <a href="Extending.html#n11">C++ Processing</a>
-<li> <a href="Extending.html#n12">Documentation Processing</a>
-<li> <a href="Extending.html#n13">The Future of SWIG</a>
-</ul>
-
-<p><hr>
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:18 1997 </address>
-</body>
-</html>
\ No newline at end of file
diff --git a/swigweb/Doc1.1/HTML/Copyright.html b/swigweb/Doc1.1/HTML/Copyright.html
deleted file mode 100644
index 94d8828..0000000
--- a/swigweb/Doc1.1/HTML/Copyright.html
+++ /dev/null
@@ -1,70 +0,0 @@
-<HTML>
-<HEAD>
-<title> SWIG Documentation Copyright</title>
-</head>
-
-<body BGCOLOR="#FFFFFF">
-<h2> SWIG Users Manual </h2>
-<b>
-Version 1.1<br>
-June, 1997 <br>
-</b>
-<p>
-Copyright(C) 1996, 1997<br>
-All Rights Reserved<br>
-<br>
-David M. Beazley<br>
-Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 </br>
-<tt>beazley@cs.utah.edu</tt>
-
-<p>
-This document may be freely distributed in whole or part provided this
-copyright notice is retained. Commercial distribution of this document
-is prohibited without the express written consent of the author.
-
-<hr>
-SWIG 1.1 is Copyright (C) 1995-1997 by the University of Utah and the
-Univerity of California and distributed under the following license.
-
-<p>
-This software is copyrighted by the University of Utah and the Regents
-of the University of California. The following terms apply to all
-files associated with the software unless explicitly disclaimed
-in individual files.
-
-<p>
-Permission is hereby granted, without written agreement and without
-license or royalty fees, to use, copy, modify, and distribute this
-software and its documentation for any purpose, provided that
-(1) The above copyright notice and the following two paragraphs
-appear in all copies of the source code and (2) redistributions
-including binaries reproduces these notices in the supporting
-documentation. Substantial modifications to this software may be
-copyrighted by their authors and need not follow the licensing terms
-described here, provided that the new terms are clearly indicated in
-all files where they apply.
-<p>
-IN NO EVENT SHALL THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, THE
-UNIVERSITY OF UTAH OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
-PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
-EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
-THE POSSIBILITY OF SUCH DAMAGE.
-
-<p>
-THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, AND THE UNIVERSITY OF UTAH
-SPECIFICALLY DISCLAIM ANY WARRANTIES,INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND
-THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
-SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-
-<hr>
-<address><a href="http://www.cs.utah.edu/~beazley"> beazley@cs.utah.edu </a> <br>
-Last Modified, August 3, 1997</address>
-</body>
-</html>
-
-
diff --git a/swigweb/Doc1.1/HTML/Documentation.html b/swigweb/Doc1.1/HTML/Documentation.html
deleted file mode 100644
index d7e836f..0000000
--- a/swigweb/Doc1.1/HTML/Documentation.html
+++ /dev/null
@@ -1,652 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Documentation System</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>5 Documentation System</h1><p><ul>
-<li> <a href="#n1">Introduction</a>
-<li> <a href="#n2">How it works</a>
-<li> <a href="#n3">Choosing a documentation format</a>
-<li> <a href="#n4">Function usage and argument names</a>
-<li> <a href="#n5">Titles, sections, and subsections</a>
-<li> <a href="#n6">Formatting</a>
-<li> <a href="#n7">Adding Additional Text</a>
-<li> <a href="#n8">Disabling all documentation</a>
-<li> <a href="#n9">An Example</a>
-<li> <a href="#n10">ASCII Documentation</a>
-<li> <a href="#n11">HTML Documentation</a>
-<li> <a href="#n12">LaTeX Documentation</a>
-<li> <a href="#n13">C++ Support</a>
-<li> <a href="#n14">The Final Word?</a>
-</ul>
-
-<a name="n1"></a><h2> Introduction</h2>
-While SWIG makes it easy to build interfaces, it is often difficult to keep track of all of the different functions, variables, constants, and other objects that have been wrapped. This especially becomes a problem when your interface starts to grow in size from a handful to several hundred functions. To address these concerns, SWIG can automatically generate documentation in a number of formats including ASCII, HTML, and LaTeX. The goal is that you could look at the documentation file to see what functions were wrapped and how they are used in the target scripting language.<p>
-<p>
-Usage documentation is generated for each declaration found in an interface file. This documentation is generated by the target language module so the Tcl module will follow Tcl syntax, the Perl module will use Perl syntax, and so on. In addition, C/C++ comments can be used to add descriptive text to each function. Comments can be processed in a number of different styles to suit personal preferences or to match the style used in a particular input file.<p>
-<p>
-Automatic documentation generation for C/C++ programs is a fairly formidable problem and SWIG was never intended to be a substitute for a full-blown documentation generator. However, I feel that is does a reasonable job of documenting scripting language interfaces. It seems to do just fine for many of SWIG's primary applications--rapid prototyping, debugging, and development.<p>
-<a name="n2"></a><h2> How it works</h2>
-For each declaration in an interface file, SWIG creates a "Documentation Entry." This entry contains three components; (1) a usage string, (2) a C information string, and (3) descriptive text. For example, suppose you have this declaration in an interface file :<p>
-<p>
-<blockquote><pre>int fact(int n);
-/* This function computes a factorial */
-
-</pre></blockquote>
-The documentation entry produced by the SWIG ASCII module will look like this for Tcl:<p>
-<p>
-<blockquote><pre>fact n
- [ returns int ]
- This function computes a factorial
-
-</pre></blockquote>
-The first line shows how to call the function, the second line shows some additional information about the function (related to its C implementation), while the third line contains the comment text. The first two lines are automatically generated by SWIG and may be different for each language module. For example, the Perl5 module would generate the following output :<p>
-<p>
-<blockquote><pre>fact($n)
- [ returns int ]
- This function computes a factorial
-
-</pre></blockquote>
-<p>
-Of course, this is only a simple example, more sophisticated things are possible.<p>
-<a name="n3"></a><h2> Choosing a documentation format</h2>
-The type of documentation is selected using the following command line options :<p>
-<blockquote><pre>
--dascii Produce ASCII documentation
--dhtml Produce HTML documentation
--dlatex Produce LaTeX documentation
--dnone Produce no documentation
-
-</pre></blockquote>
-The various documentation modules are implemented in a manner similar to language modules so the exact choice may change in the future. With a little C++ hacking, it is also possible for you to add your own modules to SWIG. For example, with a bit of work you could turn all of the documentation into an online help command in your scripting language. <p>
-<a name="n4"></a><h2> Function usage and argument names</h2>
-The function usage string is produced to match the declaration given in the SWIG interface file. The names of arguments can be specified by using argument names. For example, the declarations<p>
-<p>
-<blockquote><pre>void insert_item(List *, char *);
-char *lookup_item(char *name);
-</pre></blockquote>
-<p>
-will produce the following documentation (for Python) :<p>
-<p>
-<blockquote><pre>insert_item(List *, char *)
- [ returns void ]
-
-lookup_item(name)
- [ returns char * ]
-
-</pre></blockquote>
-When argument names are omitted, SWIG will use the C datatypes of the arguments in the documentation. If an argument name is specified, SWIG will use that in the documentation instead. Of course, it is up to each language module to create an appropriate usage string so your results may vary depending on how things have been implemented in each module.<p>
-<a name="n5"></a><h2> Titles, sections, and subsections</h2>
-The SWIG documentation system is hierarchical in nature and is organized into a collection of sections, subsections, subsubsections, and so on. The following SWIG directives can be used to organize an interface file :<p>
-<p>
-<ul>
-<li><tt>%title "Title Text"</tt>. Set the documentation title (may only be used once)
-<li><tt>%section "Section title"</tt>. Start a new section.
-<li><tt>%subsection "Subsection title"</tt>. Create a new subsection.
-<li><tt>%subsubsection "Subsubsection title"</tt>. Create a new subsubsection.
-</ul>
-<p>
-The <tt>%title</tt> directive should be placed prior to the first declaration in an interface file and may only be used once (subsequent occurrences will simply be ignored). The section directives may be placed anywhere. However, <tt>%subsection</tt> can only be used after a <tt>%section</tt> directive and <tt>%subsubsection</tt> can only be used after a <tt>%subsection</tt> directive.<p>
-<p>
-With the organization directives, a SWIG interface file looks something like this :<p>
-<p>
-<blockquote><pre>%title "Example Interface File"
-%module example
-%{
-#include "my_header.h"
-%}
-
-%section "Mathematical Functions"
-
-... declarations ...
-
-%section "Graphics"
-%subsection "2D Plotting"
-... Declarations ...
-%subsection "3D Plotting"
-%subsubsection "Viewing transformations"
-... Declarations ...
-%subsubsection "Lighting"
-... Declarations ...
-%subsubsection "Primitives"
-... Declarations ...
-
-%section "File I/O"
-
-... Declarations ...
-</pre></blockquote>
-<a name="n6"></a><h2> Formatting</h2>
-Documentation text can be sorted, chopped, sliced, and diced in a variety of ways. Formatting information is specified using a comma separated list of parameters after the <tt>%title</tt>, <tt>%section</tt>, <tt>%subsection</tt>, or <tt>%subsubsection</tt> directives. For example :<p>
-<p>
-<blockquote><pre>%title "My Documentation", sort, before, pre
-
-</pre></blockquote>
-This tells SWIG to sort all of the documentation, use comments that are before each declaration, and assume that text is preformatted. These formatting directives are applied to all children in the documentation tree--in this case, everything in an interface file.<p>
-<p>
-If formatting information is specified for a section like this<p>
-<p>
-<blockquote><pre>%subsection "3D Graphics", nosort, after
-</pre></blockquote>
-<p>
-then the effect will only apply to that particular section (and all of its subsections). In this case, the formatting of the subsection would override any previous formatting, but these changes would only apply to this subsection. The next subsection could use its own formatting or that of its parent.<p>
-<p>
-Style parameters can also be specified using the <tt>%style</tt> and <tt>%localstyle</tt> parameters. The <tt>%style</tt> directive applies a new format to the current section and all of its parents. The <tt>%localstyle</tt> directive applies a new format to the current section. For example :<p>
-<p>
-<blockquote><pre>%style sort,before, skip=1 # Apply these formats everywhere
-%localstyle sort # Apply this format to the current section
-
-</pre></blockquote>
-Use of these directives usually isn't required since it's easy enough to simply specify the information after each section.<p>
-<a name="n15"></a><h3> Default Formatting</h3>
-By default, SWIG will reformat comment text, produce documentation in the order encountered in an interface file (nosort), and annotate descriptions with a C information string. This behavior most closely matches that used in SWIG 1.0, although it is not an exact match due to differences in the old documentation system.<p>
-<p>
-When used in the default mode, comment text may contain documentation specific formatting markup. For example, you could embed LaTeX or HTML markup in comments to have precise control over the look of the final document.<p>
-<a name="n16"></a><h3> Comment Formatting variables</h3>
-The default formatting can be changed by changing one or more of the following formatting variables :<p>
-<blockquote><pre>
-after Use comments after a declaration (default)
-before Use comments before a declaration
-chop_top=nlines Comment chopping (preformatted)
-chop_bottom=nlines Comment chopping (preformatted)
-chop_left=nchar Comment chopping (preformatted)
-chop_right=nchar Comment chopping (preformatted)
-format Allow SWIG to reformat text (the default)
-ignore Ignore comments
-info Print C information text (default)
-keep Keep comments (opposite of ignore)
-noinfo Don't print C information text
-nosort Don't sort documentation (default)
-pre Assume text is preformatted
-skip=nlines Number of blank lines between comment and declaration
-sort Sort documentation
-tabify Leave tabs intact
-untabify Convert tabs to spaces (default)
-</pre></blockquote>
-<p>
-More variables may be available depending on particular documentation modules. The use of these variables is described in the next few sections.<p>
-<a name="n17"></a><h3> Sorting </h3>
-Documentation can be sorted using the `<tt>sort</tt>' parameter. For example :<p>
-<p>
-<blockquote><pre>%title "My interface",sort
-</pre></blockquote>
-<p>
-When used, all documentation entries, including sections will be alphabetically sorted. Sorting can be disabled in particular sections and subsection by specifying the `<tt>nosort</tt>' parameter in a section declaration. By default, SWIG does not sort documentation. As a general rule, it really only comes in handy if you have a really messy interface file.<p>
-<p>
-For backwards compatibility with earlier versions of SWIG, the following directives can be used to specify sorting. <p>
-<p>
-<blockquote><pre>%alpha Sort documentation alphabetically (obsolete)
-%raw Keep documentation in order (obsolete)
-
-</pre></blockquote>
-These directives only apply globally and should near the beginning of file. Future support of these directives is not guaranteed and generally discouraged.<p>
-<a name="n18"></a><h3> Comment placement and formatting</h3>
-Comments may be placed before or after a declaration. This is specified using the `<tt>before</tt>' and `<tt>after</tt>' parameters. The space between a comment and a declaration can be set by changing the `<tt>skip</tt>' parameter. By default, <tt>skip=1</tt>, indicating that a comment and declaration must be on adjacent lines. Use of the <tt>skip</tt> parameter makes it possible for the documentation generator to ignore comments that are too far away and possibly unrelated to a declaration.<p>
-<p>
-By default, SWIG reformats the text found in a comment. However, in many cases, your file may have preformatted comments or comment blocks. To handle such comments correctly, you can use preformatted mode. This is specified using the `pre' parameter as follows :<p>
-<p>
-<blockquote><pre>%section "Preformatted Section",pre
-%section "Reformatted Section", format
-
-</pre></blockquote>
-All declarations in this section will now be assumed to have preformatted comments. When using the preformat mode, a variety of other parameters are available as shown in the following diagram :<p>
-<center><img src="ch5.1.png"></center>
-
-.<p>
-<p>
-The chopping parameters can be used to strip out the text of block comments. For example, using <tt>chop_left=3</tt>, <tt>chop_top=1</tt>, <tt>chop_bottom=1</tt> on the above comment produces the following output :<p>
-<blockquote><pre>
-Plot2D_line x1 y1 x2 y2 color
- [ returns void ]
- void Plot2D_line(int x1, int y1, int x2, int y2, Pixel color)
-
- Draws a line between the points (x1,y1) and (x2,y2) using the
- the given color. The line is cropped to fit in the current
- bounding box.
-
- Uses the Bresenham line drawing algorithm.
-</pre></blockquote>
-<p>
-The chopping parameters only apply if a comment is sufficiently large (i.e.. if the number of lines exceed <tt>chop_top</tt>+<tt>chop_bottom</tt>). Thus, in our example, a one line comment will be unaltered even though chopping has been set. By default, SWIG sets chop_left=3 and all others to zero. This setting removes the `<tt>/* </tt>` or `<tt>// </tt>` preceeding a comment.<p>
-<a name="n19"></a><h3> Tabs and other annoyances</h3>
-When using the preformatted mode, SWIG will automatically convert tabs to white space. This is done assuming that tabs are placed every 8 characters. The tabification mode can be selected using the `tabify' and `untabify' parameters :<p>
-<p>
-<blockquote><pre>%section "Untabified Section",untabify
-%section "Leave those tabs alone", tabify
-
-</pre></blockquote>
-Tabs are simply ignored when comments are reformatted (well, actually, they're just copied into the output, but the target documentation method will ignore them).<p>
-<a name="n20"></a><h3> Ignoring comments</h3>
-To ignore the comments in a particular section, you can use the `ignore' parameter. For example :<p>
-<blockquote><pre>
-%section "No Comments", ignore
-%section "Keep Comments", keep
-
-</pre></blockquote>
-The `<tt>keep</tt>' parameter is used to disable the effect of an ignore parameter (if set by a section's parent).<p>
-<a name="n21"></a><h3> C Information</h3>
-Normally, each declaration in a file will have a C information tag attached to it. This is usually enclosed in [ ] and contains the return type of a function along with other information. This text can disabled using the `noinfo' parameters and reenabled using the `info' parameter.<p>
-<p>
-<blockquote><pre>%section "No C Information", noinfo
-%section "Print C Information", info
-
-</pre></blockquote>
-<a name="n7"></a><h2> Adding Additional Text</h2>
-Additional documentation text can be added using the <tt>%text</tt> directive as shown :<p>
-<p>
-<blockquote><pre><tt>%text %{
-</tt>
-This is some additional documentation text.
-
-%}
-
-</pre></blockquote>
-The <tt>%text</tt> directive is primarily used to add text that is not associated with any particular declaration. For example, you may want to provide a general description of a module before defining all of the functions. Any text can be placed inside the <tt>%{,%}</tt> block except for a `<tt>%}</tt>' that ends the block. For the purposes of sorting, text segments will always appear immediately after the previous declaration.<p>
-<a name="n8"></a><h2> Disabling all documentation</h2>
-All documentation can be suppressed for a portion of an interface file by using the <tt>%disabledoc</tt> and <tt>%enabledoc </tt>directives. These would be used as follows:<p>
-<p>
-<blockquote><pre>%disabledoc
-... A a bunch of declarations with no documentation ...
-%enabledoc
-... Now declarations are documented again ...
-
-</pre></blockquote>
-These directives can be safely nested. Thus, the occurrence of these directives inside a <tt>%disabledoc </tt>section has no effect (only the outer-most occurrence is important).<p>
-<p>
-The primary use of these directives is for disabling the documentation on commonly used modules that you might use repeatedly (but don't want any documentation for). For example :<p>
-<blockquote><pre>
-%disabledoc
-%include wish.i
-%include array.i
-%include timer.i
-%enabledoc
-
-</pre></blockquote>
-<p>
-<a name="n9"></a><h2> An Example</h2>
-To illustrate the documentation system in action, here is some code from the SWIG library file `array.i'.<p>
-<p>
-<blockquote><pre>//
-// array.i
-// This SWIG library file provides access to C arrays.
-
-%module carray
-
-%section "SWIG C Array Module",info,after,pre,nosort,skip=1,chop_left=3,
-chop_right=0,chop_top=0,chop_bottom=0
-
-%text %{
-%include array.i
-
-This module provides scripting language access to various kinds of C/C++
-arrays. For each datatype, a collection of four functions are created :
-
- <type>_array(size) : Create a new array of given size
- <type>_get(array, index) : Get an element from the array
- <type>_set(array, index, value) : Set an element in the array
- <type>_destroy(array) : Destroy an array
-
-The functions in this library are only low-level accessor functions
-designed to directly access C arrays. Like C, no bounds checking is
-performed so use at your own peril.
-%}
-
-// -----------------------------------------------------------------------
-// Integer array support
-// -----------------------------------------------------------------------
-
-%subsection "Integer Arrays"
-/* The following functions provide access to integer arrays (mapped
- onto the C 'int' datatype. */
-
-%{
- ... Supporting C code ...
-%}
-int *int_array(int nitems);
-/* Creates a new array of integers. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++. */
-
-void int_destroy(int *array);
-/* Destroys the given array. */
-
-int int_get(int *array, int index);
-/* Returns the value of array[index]. */
-
-int int_set(int *array, int index, int value);
-/* Sets array[index] = value. Returns value. */
-
-// -----------------------------------------------------------------------
-// Floating point
-// -----------------------------------------------------------------------
-
-%subsection "Floating Point Arrays"
-/* The following functions provide access to arrays of floats and doubles. */
-
-%{
- .. Supporting C code ...
-%}
-double *double_array(int nitems);
-/* Creates a new array of doubles. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++. */
-
-void double_destroy(double *array);
-/* Destroys the given array. */
-
-double double_get(double *array, int index);
-/* Returns the value of array[index]. */
-
-double double_set(double *array, int index, double value);
-/* Sets array[index] = value. Returns value. */
-
-float *float_array(int nitems);
-/* Creates a new array of floats. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++. */
-
-void float_destroy(float *array);
-/* Destroys the given array. */
-
-float float_get(float *array, int index);
-/* Returns the value of array[index]. */
-
-float float_set(float *array, int index, float value);
-/* Sets array[index] = value. Returns value. */
-
-// -----------------------------------------------------------------------
-// Character strings
-// -----------------------------------------------------------------------
-
-%subsection "String Arrays"
-
-%text %{
-The following functions provide support for the 'char **' datatype. This
-is primarily used to handle argument lists and other similar structures that
-need to be passed to a C/C++ function.
-%}
-
-#if defined(SWIGTCL)
-%text %{
-To convert from a Tcl list into a 'char **', the following code can be used :
-
- # $list is a list
- set args [string_array expr {[llength $list] + 1}]
- set i 0
- foreach a $list {
- string_set $args $i $a
- incr i 1
- }
- string_set $i ""
- # $args is now a char ** type
-%}
-#elif defined(SWIGPERL)
-
-%text %{
-To convert from a Perl list into a 'char **', code similar to the following
-can be used :
-
- # @list is a list
- my $l = scalar(@list);
- my $args = string_array($l+1);
- my $i = 0;
- foreach $arg (@list) {
- string_set($args,$i,$arg);
- $i++;
- }
- string_set($args,$i,"");
-
-(of course, there is always more than one way to do it)
-%}
-#elif defined(SWIGPYTHON)
-
-%text %{
-To convert from a Python list to a 'char **', code similar to the following
-can be used :
-
- # 'list' is a list
- args = string_array(len(list)+1)
- for i in range(0,len(list)):
- string_set(args,i,list[i])
- string_set(args,len(list),"")
-%}
-
-#endif
-
-%{
- ... Supporting C code ...
-%}
-char **string_array(int nitems);
-/* Creates a new array of strings. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++. Each element
- of the array is set to NULL upon initialization. */
-
-void string_destroy(char *array);
-/* Destroys the given array. Each element of the array is assumed to be
- a NULL-terminated string allocated with malloc() or new(). All of
- these strings will be destroyed as well. (It is probably only safe to
- use this function on an array created by string_array) */
-
-char *string_get(char **array, int index);
-/* Returns the value of array[index]. Returns a string of zero length
- if the corresponding element is NULL. */
-
-char *string_set(char **array, int index, char *value);
-/* Sets array[index] = value. value is assumed to be a NULL-terminated
- string. A string of zero length is mapped into a NULL value. When
- setting the value, the value will be copied into a new string allocated
- with malloc() or new(). Any previous value in the array will be
- destroyed. */
-</pre></blockquote>
-<p>
-In this file, all of the declarations are placed into a new section. We specify formatting information for our section. Since this is a general purpose library file, we have no idea what formatting our parent might be using so an explicit declaration makes sure we get it right. Each comment contains preformatted text describing each function. Finally, in the case of the string functions, we are using a combination of conditional compilation and documentation system directives to produce language-specific documentation. In this case, the documentation contains a usage example in the target scripting language.<p>
-<p>
-When processed through the ASCII module, this file will produce documentation similar to the following :<p>
-<p>
-<blockquote><pre>7. SWIG C Array Module
-=======================
-
-%include array.i
-
-This module provides scripting language access to various kinds of C/C++
-arrays. For each datatype, a collection of four functions are created :
-
- <type>_array(size) : Create a new array of given size
- <type>_get(array, index) : Get an element from the array
- <type>_set(array, index, value) : Set an element in the array
- <type>_destroy(array) : Destroy an array
-
-The functions in this library are only low-level accessor functions
-designed to directly access C arrays. Like C, no bounds checking is
-performed so use at your own peril.
-
-7.1. Integer Arrays
---------------------
-The following functions provide access to integer arrays (mapped
-onto the C 'int' datatype.
-
-
-int_array(nitems)
- [ returns int * ]
- Creates a new array of integers. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++.
-
-int_destroy(array)
- [ returns void ]
- Destroys the given array.
-
-int_get(array,index)
- [ returns int ]
- Returns the value of array[index].
-
-int_set(array,index,value)
- [ returns int ]
- Sets array[index] = value. Returns value.
-
-7.2. Floating Point Arrays
----------------------------
-The following functions provide access to arrays of floats and doubles.
-
-
-double_array(nitems)
- [ returns double * ]
- Creates a new array of doubles. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++.
-
-double_destroy(array)
- [ returns void ]
- Destroys the given array.
-
-double_get(array,index)
- [ returns double ]
- Returns the value of array[index].
-
-double_set(array,index,value)
- [ returns double ]
- Sets array[index] = value. Returns value.
-
-float_array(nitems)
- [ returns float * ]
- Creates a new array of floats. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++.
-
-float_destroy(array)
- [ returns void ]
- Destroys the given array.
-
-float_get(array,index)
- [ returns float ]
- Returns the value of array[index].
-
-float_set(array,index,value)
- [ returns float ]
- Sets array[index] = value. Returns value.
-
-7.3. String Arrays
--------------------
-
-The following functions provide support for the 'char **' datatype. This
-is primarily used to handle argument lists and other similar structures that
-need to be passed to a C/C++ function.
-
-To convert from a Python list to a 'char **', code similar to the following
-can be used :
-
- # 'list' is a list
- args = string_array(len(list)+1)
- for i in range(0,len(list)):
- string_set(args,i,list[i])
- string_set(args,len(list),"")
-
-string_array(nitems)
- [ returns char ** ]
- Creates a new array of strings. nitems specifies the number of elements.
- The array is created using malloc() in C and new() in C++. Each element
- of the array is set to NULL upon initialization.
-
-string_destroy(array)
- [ returns void ]
- Destroys the given array. Each element of the array is assumed to be
- a NULL-terminated string allocated with malloc() or new(). All of
- these strings will be destroyed as well. (It is probably only safe to
- use this function on an array created by string_array)
-
-string_get(array,index)
- [ returns char * ]
- Returns the value of array[index]. Returns a string of zero length
- if the corresponding element is NULL.
-
-string_set(array,index,value)
- [ returns char * ]
- Sets array[index] = value. value is assumed to be a NULL-terminated
- string. A string of zero length is mapped into a NULL value. When
- setting the value, the value will be copied into a new string allocated
- with malloc() or new(). Any previous value in the array will be
- destroyed.
-
-</pre></blockquote>
-<a name="n10"></a><h2> ASCII Documentation</h2>
-The ASCII module produces documentation in plaintext as shown in the previous example. Two formatting options are available (default values shown) :<p>
-<p>
-<blockquote><pre>ascii_indent = 8
-ascii_columns = 70
-
-</pre></blockquote>
-`<tt>ascii_indent</tt>' specifies the number of characters to indent each function description. `<tt>ascii_columns</tt>' specifies the width of the output when reformatting text.<p>
-<p>
-When reformatting text, all extraneous white-space is stripped and text is filled to fit in the specified number of columns. The output text will be left-justified. A single newline is ignored, but multiple newlines can be used to start a new paragraph. The character sequence `\\' can be used to force a newline.<p>
-<p>
-Preformatted text is printed into the resulting output unmodified although it may be indented when used as part of a function description.<p>
-<a name="n11"></a><h2> HTML Documentation</h2>
-The HTML module produces documentation in HTML format (who would have guessed?). However, a number of style parameters are available (shown with default values)<p>
-<blockquote><pre>
-html_title = "<H1>:</H1>"
-html_contents = "<H1>:</H1>"
-html_section = "<HR><H2>:</H2>"
-html_subsection = "<H3>:</H3>"
-html_subsubsection = "<H4>:</H4>"
-html_usage = "<B><TT>:</TT></B>"
-html_descrip = "<BLOCKQUOTE>:</BLOCKQUOTE>"
-html_text = "<P>"
-html_cinfo = ""
-html_preformat = "<PRE>:</PRE>"
-html_body = "<BODY bg_color=\"#ffffff\">:</BODY>"
-</pre></blockquote>
-<p>
-Any of these parameters can be changed, by simply specifying them after a <tt>%title</tt> or <tt>%section</tt> directive. However, the effects are applied globally so it probably makes sense to use the <tt>%style</tt> directive instead. For example :<p>
-<p>
-<blockquote><pre>%style html_contents="<HR><H1>:</H1>"
-... Rest of declarations ...
-
-</pre></blockquote>
-Each tag uses a ":" to separate the start and end tags. Any text will be inserted in place of the ":". Since strings are specified in SWIG using quotes, any quotes that need to be inserted into a tag should be escaped using the "\" character.<p>
-<p>
-Sample HTML output is shown below :<p>
-<p><a href="ch5.2.png">Sample Screenshot 1 </a><p>
-<p>
-<p>
-Since our example used preformatted text, the output is very similar to the ASCII module. However, if you use the default mode, it is possible to insert HTML markup directly into your C comments for a more personalized document.<p>
-<p>
-For navigation within the document, SWIG also produces a table of contents with links to each section within the document. With a large interface, the contents may look something like this :<p>
-<p><a href="ch5.3.png">Sample Screenshot 2 </a><p>
-<p>
-<p>
-<a name="n12"></a><h2> LaTeX Documentation</h2>
-The LaTeX module operates in a manner similar to the HTML module. The following style parameters are available (some knowledge of LaTeX is assumed).<p>
-<blockquote><pre>
-latex_parindent = "0.0in"
-latex_textwidth = "6.5in"
-latex_documentstyle = "[11pt]{article}"
-latex_oddsidemargin = "0.0in"
-latex_pagestyle = "\\pagestyle{headings}"
-latex_title = "{\\Large \\bf :} \\\\\n"
-latex_preformat = "{\\small \\begin{verbatim}:\\end{verbatim}}"
-latex_usage = "{\\tt \\bf : }"
-latex_descrip = "{\\\\\n \\makebox[0.5in]{} \begin{minipage}[t]{6in} : \n
-\\end{minipage} \\\\";
-latex_text = ":\\\\"
-latex_cinfo = "{\\tt : }"
-latex_section = "\\section{:}"
-latex_subsection = "\\subsection{:}"
-latex_subsubsection = "\\subsubsection{:}"
-
-</pre></blockquote>
-The style parameters, well, look downright ugly. Keep in mind that the strings used by SWIG have escape codes in them so it's necessary to represent the `\' character as `\\'. Thus, within SWIG your code will look something like this :<p>
-<p>
-<blockquote><pre>%style latex_section="\\newpage \n \\section{:}"
-</pre></blockquote>
-<p>
-The default values should be sufficient for creating a readable LaTeX document in any case you don't want to worry changing the default style parameters.<p>
-<a name="n13"></a><h2> C++ Support</h2>
-C++ classes are encapsulated in a new subsection of the current section. This subsection contains descriptions of all of the member functions and variables. Since language modules are responsible for creating the documentation, the use of shadow classes will result in documentation describing the resulting shadow classes, not the lower level interface to the code.<p>
-<p>
-While it's not entirely clear that this is the best way to document C++ code, it is a start (and it's better than no documentation).<p>
-<a name="n14"></a><h2> The Final Word?</h2>
-Early versions of SWIG used a fairly primitive documentation system, that could best be described as "barely usable." The system described here represents an almost total rewrite of the documentation system. While it is, by no means, a perfect solution, I think it is a step in the right direction. The SWIG library is now entirely self-documenting and is a good source of documentation examples. As always suggestions and improvements are welcome.<p>
-<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:55 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Exceptions.html b/swigweb/Doc1.1/HTML/Exceptions.html
deleted file mode 100644
index 7ee575b..0000000
--- a/swigweb/Doc1.1/HTML/Exceptions.html
+++ /dev/null
@@ -1,295 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Exception Handling</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>7 Exception Handling</h1><p><ul>
-<li> <a href="#n1">The %except directive</a>
-<li> <a href="#n2">Handling exceptions in C code</a>
-<li> <a href="#n3">Exception handling with longjmp()</a>
-<li> <a href="#n4">Handling C++ exceptions</a>
-<li> <a href="#n5">Defining different exception handlers</a>
-<li> <a href="#n6">Using The SWIG exception library</a>
-<li> <a href="#n7">Debugging and other interesting uses for %except</a>
-<li> <a href="#n8">More Examples</a>
-</ul>
-
-In some cases, it is desirable to catch errors that occur in C functions and propagate them up to the scripting language interface (ie. raise an exception). By default, SWIG does nothing, but you can create a user-definable exception handler using the <tt>%except</tt> directive.<p>
-<a name="n1"></a><h2> The %except directive</h2>
-The <tt>%except</tt> directive allows you to define an exception handler. It works something like this :<p>
-<p>
-<blockquote><pre>%except(python) {
- try {
- $function
- }
- catch (RangeError) {
- PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
- return NULL;
- }
-}
-</pre></blockquote>
-<p>
-As an argument, you need to specify the target language. The exception handling C/C++ code is then enclosed in braces. The symbol <tt>$function </tt>is replaced with the real C/C++ function call that SWIG would be ordinarily make in the wrapper code. The C code you specify inside the <tt>%except</tt> directive can be anything you like including custom C code and C++ exceptions.<p>
-<p>
-To delete an exception handler, simply use the <tt>%except</tt> directive with no code. For example :<p>
-<p>
-<blockquote><pre>%except(python); // Deletes any previously defined handler
-
-</pre></blockquote>
-Exceptions can be redefined as necessary. The scope of an exception handler is from the point of definition to the end of the file, the definition of a new exception handler, or until the handler is deleted.<p>
-<a name="n2"></a><h2> Handling exceptions in C code</h2>
-C has no formal mechanism for handling exceptions so there are many possibilities. The first approach is to simply provide some functions for setting and checking an error code. For example :<p>
-<p>
-<blockquote><pre>
-
-/* File : except.c */
-
-static char error_message[256];
-static int error_status = 0;
-
-void throw_exception(char *msg) {
- strncpy(error_message,msg,256);
- error_status = 1;
-}
-
-void clear_exception() {
- error_status = 0;
-}
-char *check_exception() {
- if (error_status) return error_message;
- else return NULL;
-}
-
-</pre></blockquote>
-To work, functions will need to explicitly call <tt>throw_exception()</tt> to indicate an error occurred. For example :<p>
-<p>
-<blockquote><pre>double inv(double x) {
- if (x != 0) return 1.0/x;
- else {
- throw_exception("Division by zero");
- return 0;
- }
-}
-
-</pre></blockquote>
-To catch the exception, you can write a simple exception handler such as the following (shown for Perl5) :<p>
-<p>
-<blockquote><pre>%except(perl5) {
- char *err;
- clear_exception();
- $function
- if ((err = check_exception())) {
- croak(err);
- }
-}
-</pre></blockquote>
-<p>
-Now, when an error occurs, it will be translated into a Perl error. The downside to this approach is that it isn't particularly clean and it assumes that your C code is a willing participant in generating error messages. (This isn't going to magically add exceptions to a code that doesn't have them).<p>
-<a name="n3"></a><h2> Exception handling with longjmp()</h2>
-Exception handling can also be added to C code using the <tt><setjmp.h></tt> library. This usually isn't documented very well (at least not in any of my C books). In any case, here's one implementation that uses the C preprocessor :<p>
-<blockquote><pre>
-/* File : except.c
- Just the declaration of a few global variables we're going to use */
-
-#include <setjmp.h>
-jmp_buf exception_buffer;
-int exception_status;
-
-/* File : except.h */
-#include <setjmp.h>
-extern jmp_buf exception_buffer;
-extern int exception_status;
-
-#define try if ((exception_status = setjmp(exception_buffer)) == 0)
-#define catch(val) else if (exception_status == val)
-#define throw(val) longjmp(exception_buffer,val)
-#define finally else
-
-/* Exception codes */
-
-#define RangeError 1
-#define DivisionByZero 2
-#define OutOfMemory 3
-
-</pre></blockquote>
-Now, within a C program, you can do the following :<p>
-<p>
-<blockquote><pre>double inv(double x) {
- if (x) return 1.0/x;
- else {throw(DivisionByZero);
-}
-
-</pre></blockquote>
-Finally, to create a SWIG exception handler, write the following :<p>
-<p>
-<blockquote><pre>%{
-#include "except.h"
-%}
-
-%except(perl5) {
- try {
- $function
- } catch(RangeError) {
- croak("Range Error");
- } catch(DivisionByZero) {
- croak("Division by zero");
- } catch(OutOfMemory) {
- croak("Out of memory");
- } finally {
- croak("Unknown exception");
- }
-}
-
-</pre></blockquote>
-<p>
-At this point, you're saying this sure looks alot like C++ and you'd be right (C++ exceptions are often implemented in a similar manner). As always, the usual disclaimers apply--your mileage may vary. <p>
-<a name="n4"></a><h2> Handling C++ exceptions</h2>
-Handling C++ exceptions is almost completely trivial (well, all except for the actual C++ part). A typical SWIG exception handler will look like this :<p>
-<p>
-<blockquote><pre>%except(perl5) {
- try {
- $function
- } catch(RangeError) {
- croak("Range Error");
- } catch(DivisionByZero) {
- croak("Division by zero");
- } catch(OutOfMemory) {
- croak("Out of memory");
- } catch(...) {
- croak("Unknown exception");
- }
-}
-
-</pre></blockquote>
-The exception types need to be declared as classes elsewhere, possibly in a header file :<p>
-<p>
-<blockquote><pre>class RangeError {};
-class DivisionByZero {};
-class OutOfMemory {};
-
-</pre></blockquote>
-Newer versions of the SWIG parser should ignore exceptions specified in function declarations. For example :<p>
-<p>
-<blockquote><pre>double inv(double) throw(DivisionByZero);
-
-</pre></blockquote>
-<a name="n5"></a><h2> Defining different exception handlers</h2>
-By default, the <tt>%except</tt> directive creates an exception handler that is used for all wrapper functions that follow it. Creating one universal exception handler for all functions may be unwieldy and promote excessive code bloat since the handler will be inlined into each wrapper function created. For this reason, the exception handler can be redefined at any point in an interface file. Thus, a more efficient use of exception handling may work like this :<p>
-<p>
-<blockquote><pre>%except(python) {
- ... your exception handler ...
-}
-/* Define critical operations that can throw exceptions here */
-
-%except(python); // Clear the exception handler
-
-/* Define non-critical operations that don't throw exceptions */
-
-</pre></blockquote>
-<a name="n9"></a><h3> Applying exception handlers to specific datatypes.</h3>
-An alternative approach to using the <tt>%except</tt> directive is to use the "except" typemap. This allows you to attach an error handler to specific datatypes and function name. The typemap is applied to the return value of a function. For example :<p>
-<p>
-<blockquote><pre>%typemap(python,except) void * {
- $function
- if (!$source) {
- PyExc_SetString(PyExc_MemoryError,"Out of memory in $name");
- return NULL;
- }
-}
-
-void *malloc(int size);
-
-</pre></blockquote>
-When applied, this will automatically check the return value of <tt>malloc()</tt> and raise an exception if it's invalid. For example :<p>
-<p>
-<blockquote><pre>Python 1.4 (Jan 16 1997) [GCC 2.7.2]
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> from example import *
->>> a = malloc(2048)
->>> b = malloc(1500000000)
-Traceback (innermost last):
- File "<stdin>", line 1, in ?
-MemoryError: Out of memory in malloc
->>>
-</pre></blockquote>
-<p>
-Since typemaps can be named, you can define an exception handler for a specific function as follows :<p>
-<p>
-<blockquote><pre>%typemap(python,except) void *malloc {
- ...
-}
-
-</pre></blockquote>
-This will only be applied to the <tt>malloc()</tt> function returning <tt>void *</tt>. While you probably wouldn't want to write a different exception handler for every function, it is possible to have a high degree of control if you need it. When typemaps are used, they override any exception handler defined with <tt>%except</tt>.<p>
-<a name="n6"></a><h2> Using The SWIG exception library</h2>
-The <tt>exception.i</tt> library file provides support for creating language independent exceptions in your interfaces. To use it, simply put an "<tt>%include exception.i</tt>" in your interface file. This creates a function<tt> SWIG_exception()</tt> that can be used to raise scripting language exceptions in a portable manner. For example :<p>
-<p>
-<blockquote><pre>// Language independent exception handler
-%include exception.i
-
-%except {
- try {
- $function
- } catch(RangeError) {
- SWIG_exception(SWIG_ValueError, "Range Error");
- } catch(DivisionByZero) {
- SWIG_exception(SWIG_DivisionByZero, "Division by zero");
- } catch(OutOfMemory) {
- SWIG_exception(SWIG_MemoryError, "Out of memory");
- } catch(...) {
- SWIG_exception(SWIG_RuntimeError,"Unknown exception");
- }
-}
-
-</pre></blockquote>
-As arguments, <tt>SWIG_exception()</tt> takes an error type code (an integer) and an error message string. The currently supported error types are :<p>
-<p>
-<blockquote><pre>SWIG_MemoryError
-SWIG_IOError
-SWIG_RuntimeError
-SWIG_IndexError
-SWIG_TypeError
-SWIG_DivisionByZero
-SWIG_OverflowError
-SWIG_SyntaxError
-SWIG_ValueError
-SWIG_SystemError
-SWIG_UnknownError
-</pre></blockquote>
-<p>
-Since the <tt>SWIG_exception()</tt> function is defined at the C-level it can be used elsewhere in SWIG. This includes typemaps and helper functions. The exception library provides a language-independent exception handling mechanism, so many of SWIG's library files now rely upon the library as well.<p>
-<a name="n7"></a><h2> Debugging and other interesting uses for %except</h2>
-Since the <tt>%except </tt>directive allows you to encapsulate the actual C function call, it can also be used for debugging and tracing operations. For example :<p>
-<p>
-<blockquote><pre>%except(tcl) {
- printf("Entering function : $name\n");
- $function
- printf("Leaving function : $name\n");
-}
-
-</pre></blockquote>
-allows you to follow the function calls in order to see where an application might be crashing. <p>
-<p>
-Exception handlers can also be chained. For example :<p>
-<p>
-<blockquote><pre>%except(tcl) {
- printf("Entering function : $name\n");
- $except
- printf("Leaving function : $name\n");
-}
-
-</pre></blockquote>
-Any previously defined exception handler will be inserted in place of the "<tt>$except</tt>" symbol. As a result, you can attach debugging code to existing handlers if necessary. However, it should be noted that this must be done before any C/C++ declarations are made (as exception handlers are applied immediately to all functions that follow them).<p>
-<a name="n8"></a><h2> More Examples</h2>
-By now, you know most of the exception basics. See the SWIG Examples directory for more examples and ideas. Further chapters show how to generate exceptions in specific scripting languages.<p>
-<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:57 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Extending.html b/swigweb/Doc1.1/HTML/Extending.html
deleted file mode 100644
index 06d2d2f..0000000
--- a/swigweb/Doc1.1/HTML/Extending.html
+++ /dev/null
@@ -1,1848 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Extending SWIG</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>12 Extending SWIG</h1><p><ul>
-<li> <a href="#n1">Introduction</a>
-<li> <a href="#n2">Compiling a SWIG extension</a>
-<li> <a href="#n3">SWIG output</a>
-<li> <a href="#n4">The Language class (simple version)</a>
-<li> <a href="#n5">A tour of SWIG datatypes</a>
-<li> <a href="#n6">Typemaps (from C)</a>
-<li> <a href="#n7">File management</a>
-<li> <a href="#n8">Naming Services</a>
-<li> <a href="#n9">Code Generation Functions</a>
-<li> <a href="#n10">Writing a Real Language Module</a>
-<li> <a href="#n11">C++ Processing</a>
-<li> <a href="#n12">Documentation Processing</a>
-<li> <a href="#n13">The Future of SWIG</a>
-</ul>
-
-<a name="n1"></a><h2> Introduction</h2>
-This chapter attempts to describe the process of extending SWIG to support new target languages and documentation methods. First a word of warning--SWIG started out being a relatively simple system for building interfaces to ANSI C programs. Since then, it has grown into something much more than that (although I'm still trying to figure out what). As a result, it is undergoing a number of growing pains. Certain parts of the code have been rewritten and others can probably be described as a hackish nightmare. I'm always working on ways to improve the implementation, but expect to find a few warts and inconsistencies.<p>
-<a name="n14"></a><h3> Prerequisites</h3>
-In order to develop or modify a SWIG module, I assume the following :<p>
-<p>
-<ul>
-<li>That you understand the C API for the scripting language of interest.
-<li>You have a good understanding of how SWIG operates and a good idea of how typemaps work.
-<li>That you have some experience with C++. SWIG is written in C++, but doesn't use it maximally. However, familiarity with classes, inheritance, and operator overloading will help.
-<li>That you're just a little crazy (this will help alot).
-</ul>
-<a name="n15"></a><h3> SWIG Organization</h3>
-SWIG is built around a central core of functions and classes responsible for parsing interface files, managing documentation, handling datatypes, and utility functions. This code is contained in the "SWIG" directory of the distribution, but contains no information specific to any one scripting language. The various scripting language modules are implemented as C++ classes and found in the "Modules" directory of the distribution. The basic idea behind writing a module is that you write a language class containing about a dozen methods for creating wrapper functions, variables, constants, etc.... To use the language, you simply create a language "object", pass it on the parser and you magically get wrapper code. Documentation modules are written in a similar manner.<p>
-<p>
-An important aspect of the design is the relationship between ANSI C and C++. The original version of SWIG was developed to support ANSI C programs. To add C++ support, an additional "layer" was added to the system---that is, all of the C++ support is really built on top of the ANSI C support. Language modules can take advantage of both C and C++ although a module written only for C can still work with C++ (due to the layered implementation). <p>
-<p>
-As for making modifications to SWIG, all files in the "SWIG" directory should be considered "critical." Making changes here can cause serious problems in all SWIG language modules. When making customizations, one should only consider files in the "Modules" directory if at all possible.<p>
-<a name="n16"></a><h3> The organization of this chapter</h3>
-The remainder of this chapter is a bottom-up approach is to building SWIG modules. It will start with the basics and gradually build up a working language module, introducing new concepts as needed.<p>
-<a name="n2"></a><h2> Compiling a SWIG extension</h2>
-The first order of business is that of compiling an extension to SWIG and using it. This is the easy part.<p>
-<a name="n17"></a><h3> Required files</h3>
-To build any SWIG extension you need to locate the files "<tt>swig.h</tt>" and "<tt>libswig.a</tt>". In a typical installation, these will usually be found in <tt>/usr/local/include</tt> and <tt>/usr/local/lib</tt> respectively. All extension modules will need to include the "<tt>swig.h</tt>" header file and link against the <tt>libswig.a</tt> library. <p>
-<a name="n18"></a><h3> Required C++ compiler</h3>
-Due to name-mangling in the C++ compiler (which is different between compiler implementations), you will need to use the same C++ compiler used to compile SWIG. If you don't know which C++ compiler was used, typing `<tt>swig -version</tt>' will cause SWIG to print out its version number and the C++ compiler that was used to build it.<p>
-<a name="n19"></a><h3> Writing a main program</h3>
-To get any extension to work, it is necessary to write a small <tt>main()</tt> program to create a language object and start the SWIG parser. For example :<br><p>
-<blockquote><pre>#include <swig.h>
-#include "swigtcl.h" // Language specific header
-
-extern int SWIG_main(int, char **, Language *, Documentation *);
-int main(int argc, char **argv) {
-
- TCL *l = new Tcl; // Create a new Language object
- init_args(argc, argv); // Initialize args
- return SWIG_main(argc, argv, l, 0);
-}
-</pre></blockquote>
-<a name="n20"></a><h3> Compiling</h3>
-To compile your extension, do the following :<p>
-<p>
-<blockquote><pre>% c++ tcl.cxx main.cxx -lswig -o myswig
-
-</pre></blockquote>
-In this case we get a special version of SWIG that compiles Tcl extensions.<p>
-<a name="n3"></a><h2> SWIG output</h2>
-The output of SWIG is a single file that is organized as follows :<p>
-<center><img src="ch12.1.png"></center><p>
-<p>
-<p>
-During code generation, the three sections are created as separate files that are accessed using the following file handles :<p>
-<p>
-<blockquote><pre>FILE *f_header; // Header section
-FILE *f_wrappers; // Wrapper section
-FILE *f_init; // Initialization function
-
-</pre></blockquote>
-On exit, the three files are merged into a single output file.<p>
-<p>
-When generating code, your language module should use the I/O functions in the C <tt><stdio.h></tt> library. SWIG does not use the C++ streams library.<p>
-<p>
-The use of each output section can be roughly described as follows :<p>
-<p>
-<ul>
-<li>The header section contains forward declarations, header files, helper functions, and run-time functions (such as the pointer type-checker). All code included with %{,%} also ends up here.
-<li>The wrapper section contains all of the SWIG generated wrapper functions.
-<li>The initialization section is a single C function used to initialize the module. For large modules, this function can be quite large. In any case, output to <tt>f_init</tt> should be treated with some care considering that the file is essentially one big C function.
-</ul>
-<a name="n4"></a><h2> The Language class (simple version)</h2>
-Writing a new language module involves inheriting from the SWIG <tt>Language</tt> class and implementing methods for a few virtual functions. A minimal definition of a new Language module is as follows :<p>
-<p>
-<blockquote><pre>// File : mylang.h
-// A minimal SWIG Language module
-
-class MYLANG : public Language {
-private:
- char *module;
-public :
- MYLANG() {
- module = 0;
- };
- // Virtual functions required by the SWIG parser
- void parse_args(int, char *argv[]);
- void parse();
- void create_function(char *, char *, DataType *, ParmList *);
- void link_variable(char *, char *, DataType *);
- void declare_const(char *, char *, DataType *, char *);
- void initialize(void);
- void headers(void);
- void close(void);
- void set_module(char *,char **);
- void create_command(char *, char *);
-};
-
-</pre></blockquote>
-<p>
-Given the above header file, we can create a very simplistic language module as follows :<p>
-<p>
-<blockquote><pre>// ---------------------------------------------------------------------
-// A simple SWIG Language module
-// ---------------------------------------------------------------------
-
-#include "swig.h"
-#include "mylang.h"
-
-// ---------------------------------------------------------------------
-// MYLANG::parse_args(int argc, char *argv[])
-//
-// Parse command line options and initializes variables.
-// ---------------------------------------------------------------------
-void MYLANG::parse_args(int argc, char *argv[]) {
- printf("Getting command line options\n");
- typemap_lang = "mylang";
-}
-
-// ---------------------------------------------------------------------
-// void MYLANG::parse()
-//
-// Start parsing an interface file.
-// ---------------------------------------------------------------------
-void MYLANG::parse() {
- fprintf(stderr,"Making wrappers for My Language\n");
- headers();
- yyparse(); // Run the SWIG parser
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::set_module(char *mod_name,char **mod_list)
-//
-// Sets the module name. Does nothing if it's already set (so it can
-// be overridden as a command line option).
-//
-// mod_list is a NULL-terminated list of additional modules. This
-// is really only useful when building static executables.
-//----------------------------------------------------------------------
-
-void MYLANG::set_module(char *mod_name, char **mod_list) {
- if (module) return;
- module = new char[strlen(mod_name)+1];
- strcpy(module,mod_name);
-}
-
-// ----------------------------------------------------------------------
-// MYLANG::headers(void)
-//
-// Generate the appropriate header files for MYLANG interface.
-// ----------------------------------------------------------------------
-void MYLANG::headers(void) {
- emit_banner(f_header); // Print the SWIG banner message
- fprintf(f_header,"/* Implementation : My Language */\n\n");
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::initialize(void)
-//
-// Produces an initialization function. Assumes that the module
-// name has already been specified.
-// ---------------------------------------------------------------------
-void MYLANG::initialize() {
- if (!module) module = "swig"; // Pick a default name
- // Start generating the initialization function
- fprintf(f_init,"int %s_initialize() {\n", module);
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::close(void)
-//
-// Finish the initialization function. Close any additional files and
-// resources in use.
-// ---------------------------------------------------------------------
-void MYLANG::close(void) {
- // Finish off our init function
- fprintf(f_init,"}\n");
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::create_command(char *cname, char *iname)
-//
-// Creates a new command from a C function.
-// cname = Name of the C function
-// iname = Name of function in scripting language
-// ---------------------------------------------------------------------
-void MYLANG::create_command(char *cname, char *iname) {
- fprintf(f_init,"\t Creating command %s\n", iname);
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::create_function(char *name, char *iname, DataType *d, ParmList *l)
-//
-// Create a function declaration and register it with the interpreter.
-// name = Name of real C function
-// iname = Name of function in scripting language
-// d = Return datatype
-// l = Function parameters
-// ---------------------------------------------------------------------
-void MYLANG::create_function(char *name, char *iname, DataType *d, ParmList *l) {
- fprintf(f_wrappers,"\nwrap_%s() { }\n\n", name);
- create_command(name,iname);
-}
-
-
-// ---------------------------------------------------------------------
-// MYLANG::link_variable(char *name, char *iname, DataType *t)
-//
-// Create a link to a C variable.
-// name = Name of C variable
-// iname = Name of variable in scripting language
-// t = Datatype of the variable
-// ---------------------------------------------------------------------
-void MYLANG::link_variable(char *name, char *iname, DataType *t) {
- fprintf(f_init,"\t Linking variable : %s\n", iname);
-}
-
-// ---------------------------------------------------------------------
-// MYLANG::declare_const(char *name, char *iname, DataType *type, char *value)
-//
-// Makes a constant.
-// name = Name of the constant
-// iname = Scripting language name of constant
-// type = Datatype of the constant
-// value = Constant value (as a string)
-// ---------------------------------------------------------------------
-void MYLANG::declare_const(char *name, char *iname, DataType *type, char *value) {
- fprintf(f_init,"\t Creating constant : %s = %s\n", name, value);
-}
-</pre></blockquote>
-<p>
-To compile our new language, we write a main program (as described previously) and do this :<p>
-<p>
-<blockquote><pre>% g++ main.cxx mylang.cxx -I/usr/local/include -L/usr/local/lib -lswig -o myswig
-
-</pre></blockquote>
-Now, try running this new version of SWIG on a few interface files to see what happens. The various <tt>printf()</tt> statements will show you where output appears and how it is structured. For example, if we run this module on the following interface file :<p>
-<p>
-<blockquote><pre>/* File : example.i */
-%module example
-%{
-/* Put headers and other declarations here */
-%}
-
-// A function
-extern double foo(double a, double b);
-
-// A variable
-extern int bar;
-
-// A constant
-#define SPAM 42
-
-</pre></blockquote>
-We get the following output :<p>
-<p>
-<blockquote><pre>/*
- * FILE : example_wrap.c
- *
- * This file was automatically generated by :
- * Simplified Wrapper and Interface Generator (SWIG)
- * Version 1.1 (Final)
- *
- * Portions Copyright (c) 1995-1997
- * The University of Utah and The Regents of the University of California.
- * Permission is granted to distribute this file in any manner provided
- * this notice remains intact.
- *
- * Do not make changes to this file--changes will be lost!
- *
- */
-
-
-#define SWIGCODE
-/* Implementation : My Language */
-
-
-/* Put headers and other declarations here */
-extern double foo(double ,double );
-extern int bar;
-
-wrap_foo() { }
-
-int example_initialize() {
- Creating command foo
- Linking variable : bar
- Creating constant : SPAM = 42
-}
-
-</pre></blockquote>
-Looking at the language module and the output gives some idea of how things are structured. The first part of the file is a banner message printed by the <tt>emit_banner()</tt> function. The "extern" declarations are automatically supplied by the SWIG compiler when use an extern modifier. The wrapper functions appear after all of the headers and forward declarations. Finally, the initialization function is written.<p>
-<p>
-It is important to note that this minimal module is enough to use virtually all aspects of SWIG. If we feed SWIG a C++ file, we will see our low-level module functions being called even though we have not explicitly defined any C++ handling (this is due to the layered approach of implementing C++ on top of C). For example, the following interface file <p>
-<blockquote><pre>
-%module example
-struct Vector {
- double x,y,z;
- Vector();
- ~Vector();
- double magnitude();
-};
-</pre></blockquote>
-<p>
-produces accessor functions and the following output :<p>
-<p>
-<blockquote><pre>/*
- * FILE : example_wrap.c
- *
- * This file was automatically generated by :
- * Simplified Wrapper and Interface Generator (SWIG)
- * Version 1.1 (Final)
- *
- * Portions Copyright (c) 1995-1997
- * The University of Utah and The Regents of the University of California.
- * Permission is granted to distribute this file in any manner provided
- * this notice remains intact.
- *
- * Do not make changes to this file--changes will be lost!
- *
- */
-
-
-#define SWIGCODE
-/* Implementation : My Language */
-
-static double Vector_x_set(Vector *obj, double val) {
- obj->x = val;
- return val;
-}
-
-wrap_Vector_x_set() { }
-
-static double Vector_x_get(Vector *obj) {
- double result;
- result = (double ) obj->x;
- return result;
-}
-
-wrap_Vector_x_get() { }
-
-static double Vector_y_set(Vector *obj, double val) {
- obj->y = val;
- return val;
-}
-
-wrap_Vector_y_set() { }
-
-static double Vector_y_get(Vector *obj) {
- double result;
- result = (double ) obj->y;
- return result;
-}
-
-wrap_Vector_y_get() { }
-
-static double Vector_z_set(Vector *obj, double val) {
- obj->z = val;
- return val;
-}
-
-wrap_Vector_z_set() { }
-
-static double Vector_z_get(Vector *obj) {
- double result;
- result = (double ) obj->z;
- return result;
-}
-
-wrap_Vector_z_get() { }
-
-static Vector *new_Vector() {
- return new Vector();
-}
-
-wrap_new_Vector() { }
-
-static void delete_Vector(Vector *obj) {
- delete obj;
-}
-
-wrap_delete_Vector() { }
-
-static double Vector_magnitude(Vector *obj) {
- double _result = (double )obj->magnitude();
- return _result;
-}
-
-wrap_Vector_magnitude() { }
-
-int example_initialize() {
- Creating command Vector_x_set
- Creating command Vector_x_get
- Creating command Vector_y_set
- Creating command Vector_y_get
- Creating command Vector_z_set
- Creating command Vector_z_get
- Creating command new_Vector
- Creating command delete_Vector
- Creating command Vector_magnitude
-}
-</pre></blockquote>
-<p>
-With just a little work, we already see that SWIG does quite alot for us. Now our task is to fill in the various Language methods with the real code needed to produce a working module. Before doing that, we first need to take a tour of some important SWIG datatypes and functions.<p>
-<a name="n5"></a><h2> A tour of SWIG datatypes</h2>
-While SWIG has become somewhat complicated over the last year, its internal operation is based on just a few fundamental datatypes. These types are described now although examples of using the various datatypes are shown later.<p>
-<a name="n21"></a><h3> The DataType class</h3>
-All C datatypes are represented by the following structure :<p>
-<blockquote><pre>
-
-class DataType {
-public:
- DataType();
- DataType(DataType *);
- ~DataType();
- int type; // SWIG Type code
- char name[MAXNAME]; // Name of type
- char is_pointer; // Is this a pointer?
- char implicit_ptr; // Implicit ptr
- char is_reference; // A C++ reference type
- char status; // Is this datatype read-only?
- char *qualifier; // A qualifier string (ie. const).
- char *arraystr; // String containing array part
- int id; // type identifier (unique for every type).
- // Output methods
- char *print_type(); // Return string containing datatype
- char *print_full(); // Return string with full datatype
- char *print_cast(); // Return string for type casting
- char *print_mangle(); // Return mangled version of type
- char *print_mangle_default(); // Default mangling scheme
- char *print_real(); // Print the real datatype
- char *print_arraycast(); // Prints an array cast
- // Array query functions
- int array_dimensions(); // Return number of array dimensions (if any)
- char *get_dimension(int); // Return string for a particular dimension
-};
-
-
-</pre></blockquote>
-The fundamental C datatypes are given a unique numerical code which is stored in the <tt>type</tt> field. The current list of types is as follows :<p>
-<p>
-<blockquote><pre>C Datatype SWIG Type Code
-int T_INT
-short T_SHORT
-long T_LONG
-char T_CHAR
-float T_FLOAT
-double T_DOUBLE
-void T_VOID
-unsigned int T_UINT
-unsigned short T_USHORT
-unsigned long T_ULONG
-unsigned char T_UCHAR
-signed char T_SCHAR
-bool T_BOOL
-<user> T_USER
-error T_ERROR
-</pre></blockquote>
-<p>
-The <tt>T_USER</tt> type is used for all derived datatypes including structures and classes. The <tt>T_ERROR</tt> type indicates that a parse/type error has occurred and went undetected (as far as I know this doesn't happen).<p>
-<p>
-The <tt>name[]</tt> field contains the actual name of the datatype as seen by the parser and is currently limited to a maximum of 96 bytes (more than enough for most applications). If a typedef has been used, the name field contains the actual name used, not the name of the primitive C datatype. Here are some examples :<p>
-<p>
-<blockquote><pre>C Datatype type name[]
-double T_DOUBLE double
-unsigned int T_UINT unsigned int
-signed long T_LONG signed long
-struct Vector T_USER struct Vector
-Real T_DOUBLE Real
-
-</pre></blockquote>
-C qualifiers such as "<tt>const</tt>" or "<tt>volatile</tt>" are stored separately in the <tt>qualifier</tt> field. In order to produce usable wrapper code, SWIG often needs to strip the qualifiers. For example, trying to assign a passed function argument into a type of "<tt>const int</tt>" will irritate most compilers. Unfortunately, this kind of assignment is unavoidable when converting arguments between a scripting and C representation.<p>
-<p>
-The <tt>is_pointer</tt> field indicates whether or not a particular datatype is a pointer. The value of <tt>is_pointer</tt> determines the level of indirection used. For example :<p>
-<p>
-<blockquote><pre>C Datatype type is_pointer
-double * T_DOUBLE 1
-int *** T_INT 3
-char * T_CHAR 1
-
-</pre></blockquote>
-The <tt>implicit_ptr</tt> field is an internally used parameter that is used to properly handle the use of pointers in typedef statements. However, for the curious, in indicates the level of indirection implicitly defined in a datatype. For example :<p>
-<p>
-<blockquote><pre>typedef char *String;
-
-</pre></blockquote>
-is represented by a datatype with the following parameters :<p>
-<p>
-<blockquote><pre>type = T_CHAR;
-name[] = "String";
-is_pointer = 1;
-implicit_ptr = 1;
-
-</pre></blockquote>
-Normally, language modules do not worry about the <tt>implicit_ptr </tt>field.<p>
-<p>
-C++ references are indicated by the <tt>is_reference</tt> field. By default, the parser converts references into pointers which makes them indistinguishable from other pointer datatypes. However, knowing that something is a reference effects some code generation procedures so this field can be checked to see if a datatype really is a C++ reference.<p>
-<p>
-The <tt>arraystr</tt> field is used to hold the array dimensions of array datatypes. The dimensions are simply represented by a string. For example :<p>
-<p>
-<blockquote><pre>C Datatype type is_pointer arraystr
-double a[50] T_DOUBLE 1 [50]
-int b[20][30][50] T_INT 1 [20][30][50]
-char *[MAX] T_CHAR 2 [MAX]
-
-</pre></blockquote>
-SWIG converts all arrays into pointers. Thus a "<tt>double [50]</tt>" is really just a special version of "<tt>double *</tt>". If a datatype is not declared as an array, the <tt>arraystr</tt> field contains the NULL pointer.<p>
-<p>
-A collection of "output" methods are available for datatypes. The names of these methods are mainly "historical" in that they don't actually "print" anything, but now return character strings instead. Assuming that <tt>t</tt> is a datatype representing the C datatype "<tt>const int *</tt>", here's what the methods produce :<p>
-<p>
-<blockquote><pre>Operation Output
-t->print_type() int *
-t->print_full() const int *
-t->print_cast() (int *)
-t->print_mangle() < language dependent >
-t->print_mangle_default() _int_p
-</pre></blockquote>
-<p>
-A few additional output methods are provided for dealing with arrays :<p>
-<p>
-<blockquote><pre>type Operation Output
-int a[50] t->print_type() int *
-int a[50] t->print_real() int [50]
-int a[50] t->print_arraycast() (int *)
-int a[50][50] t->print_arraycast() (int (*)[50])
-
-</pre></blockquote>
-Additional information about arrays is also available using the following functions :<p>
-<p>
-<blockquote><pre>type Operation Result
-int a[50] t->array_dimension() 1
-int a[50] t->get_dimension(0) 50
-int b[MAXN][10] t->array_dimension() 2
-int b[MAXN][10] t->get_dimension(0) MAXN
-int b[MAXN][10] t->get_dimension(1) 10
-
-</pre></blockquote>
-The <tt>DataType</tt> class contains a variety of other methods for managing typedefs, scoping, and other operations. These are usually only used by the SWIG parser. While available to language modules too, they are never used (at least not in the current implementation), and should probably be avoided unless you absolutely know what you're doing (not that this is a strict requirement of course).<p>
-<a name="n22"></a><h3> Function Parameters</h3>
-Each argument of a function call is represented using the <tt>Parm</tt> structure :<p>
-<p>
-<blockquote><pre>struct Parm {
- Parm(DataType *type, char *name);
- Parm(Parm *p);
- ~Parm();
- DataType *t; // Datatype of this parameter
- int call_type; // Call type (value or reference or value)
- char *name; // Name of parameter (optional)
- char *defvalue; // Default value (as a string)
- int ignore; // Ignore flag
-};
-
-</pre></blockquote>
-<tt>t</tt> is the datatype of the parameter, <tt>name</tt> is an optional parameter name, and <tt>defvalue</tt> is a default argument value (if supplied). <p>
-<p>
-<tt>call_type</tt> is an integer code describing any special processing. It can be one of two values :<p>
-<p>
-<ul>
-<li><tt>CALL_VALUE</tt>. This means that the argument is a pointer, but we should make it work like a call-by-value argument in the scripting interface. This value used to be set by the <tt>%val</tt> directive, but this approach is now deprecated (since the same effect can be achieved by typemaps).
-<li><tt>CALL_REFERENCE</tt>. This is set when a complex datatype is being passed by value to a function. Since SWIG can't handle complex datatypes by value, the datatype is implicitly changed into a pointer and<tt> call_type</tt> set to <tt>CALL_REFERENCE</tt>. Many of SWIG's internals look at this when generating code. A common mistake is forgetting that all complex datatypes in SWIG are pointers. This is even the case when writing a language-module---the conversion to pointers takes place in the parser before data is even passed into a particular module.
-</ul>
-<p>
-The <tt>ignore</tt> field is set when SWIG detects that a function parameter is to be "ignored" when generating wrapper functions. An "ignored" parameter is usually set to a default value and effectively disappears when a function call is made from a scripting language (that is, the function is called with fewer arguments than are specified in the interface file). The <tt>ignore</tt> field is normally only set when an "ignore" typemap has been used.<p>
-<p>
-All of the function parameters are passed in the structure <tt>ParmList</tt>. This structure has the following user-accesible methods available :<p>
-<p>
-<blockquote><pre>class ParmList {
-public:
- int nparms; // Number of parms in list
- void append(Parm *p); // Append a parameter to the end
- void insert(Parm *p, int pos); // Insert a parameter into the list
- void del(int pos); // Delete a parameter at position pos
- int numopt(); // Get number of optional arguments
- int numarg(); // Get number of active arguments
- Parm *get(int pos); // Get the parameter at position pos
-};
-
-</pre></blockquote>
-The methods operate in the manner that you would expect. The most common operation that will be performed in a language module is walking down the parameter list and processing individual parameters. This can be done as follows :<p>
-<p>
-<blockquote><pre>// Walk down a parameter list
-ParmList *l; // Function parameter list (already created)
-Parm *p;
-
-for (int i = 0; i < l->nparms; i++) {
- p = l->get(i); // Get ith parameter
- // do something with the parameter
- ...
-}
-
-</pre></blockquote>
-<a name="n23"></a><h3> The String Class</h3>
-The process of writing wrapper functions is mainly just a tedious exercise in string manipulation. To make this easier, the <tt>String</tt> class provides relatively simple mechanism for constructing strings, concatenating values, replacing symbols, and so on. <p>
-<p>
-<blockquote><pre>class String {
-public:
- String();
- String(const char *s);
- ~String();
- char *get() const;
- friend String& operator<<(String&,const char *s);
- friend String& operator<<(String&,const int);
- friend String& operator<<(String&,const char);
- friend String& operator<<(String&,String&);
- friend String& operator>>(const char *s, String&);
- friend String& operator>>(String&,String&);
- String& operator=(const char *);
- operator char*() const { return str; }
- void untabify();
- void replace(char *token, char *rep);
- void replaceid(char *id, char *rep);
-};
-</pre></blockquote>
-<p>
-Strings can be manipulated in a manner that looks similar to C++ I/O operations. For example :<p>
-<p>
-<blockquote><pre>String s;
-
-s << "void" << " foo() {\n"
- << tab4 << "printf(\"Hello World\");\n"
- << "}\n";
-
-fprintf(f_wrappers,"%s", (char *) s);
-
-</pre></blockquote>
-produces the output :<p>
-<p>
-<blockquote><pre>void foo() {
- printf("Hello World");
-}
-
-</pre></blockquote>
-The <tt><<</tt> operator always appends to the end of a string while <tt>>></tt> can be used to insert a string at the beginning. Strings may be used anywhere a <tt>char *</tt> is expected. For example :<p>
-<p>
-<blockquote><pre>String s1,s2;
-...
-if (strcmp(s1,s2) == 0) {
- printf("Equal!\n");
-}
-
-</pre></blockquote>
-The <tt>get()</tt> method can be used to explicitly return the <tt>char *</tt> containing the string data. The <tt>untabify()</tt> method replaces tabs with whitespace. The <tt>replace()</tt> method can be used to perform substring replacement and is used by typemaps. For example :<p>
-<p>
-<blockquote><pre>s.replace("$target","_arg3");
-
-</pre></blockquote>
-The <tt>replaceid()</tt> method can be used to replace valid C identifiers with a new value. C identifiers must be surrounded by white-space or other non-identifier characters. The <tt>replace()</tt> method does not have this restriction.<p>
-<a name="n24"></a><h3> Hash Tables</h3>
-Hash tables can be created using the <tt>Hash</tt> class :<p>
-<p>
-<blockquote><pre>class Hash {
-public:
- Hash();
- ~Hash();
- int add(const char *key, void *object);
- int add(const char *key, void *object, void (*del)(void *));
- void *lookup(const char *key);
- void remove(const char *key);
- void *first();
- void *next();
- char *firstkey();
- char *nextkey();
-};
-
-</pre></blockquote>
-Hash tables store arbitrary objects (cast to <tt>void *</tt>) with string keys. An optional object deletion function may be registered with each entry to delete objects when the hash is destroyed. Hash tables are primarily used for managing internal symbol tables although language modules may also use them to keep track of special symbols and other state.<p>
-<p>
-The following hash table shows how one might keep track of real and renamed function names.<p>
-<p>
-<blockquote><pre>Hash wrapped_functions;
-
-int add_function(char *name, char *renamed) {
- char *nn = new char[strlen(renamed)+1];
- strcpy(nn,renamed);
- if (wrapped_functions.add(name,nn) == -1) {
- printf("Function multiply defined!\n");
- delete [] nn;
- return -1;
- }
-}
-char *get_renamed(char *name) {
- char *rn = (char *) wrapped_functions.lookup(name);
- return rn;
-}
-
-</pre></blockquote>
-The <tt>remove()</tt> method removes a hash-table entry. The <tt>first()</tt> and <tt>next()</tt> methods are iterators for extracting all of the hashed objects. They return NULL when no more objects are found in the hash. The <tt>firstkey()</tt> and <tt>nextkey() </tt>methods are iterators that return the hash keys. NULL is returned when no more keys are found.<p>
-<a name="n25"></a><h3> The WrapperFunction class</h3>
-Finally, a <tt>WrapperFunction</tt> class is available for simplifying the creation of wrapper functions. The class is primarily designed to organize code generation and provide a few supporting services. The class is defined as follows :<p>
-<p>
-<blockquote><pre>class WrapperFunction {
-public:
- String def;
- String locals;
- String code;
- void print(FILE *f);
- void print(String &f);
- void add_local(char *type, char *name, char *defvalue = 0);
- char *new_local(char *type, char *name, char *defvalue = 0);
-};
-
-</pre></blockquote>
-Three strings are available. The <tt>def</tt> string contains the actual function declaration, the <tt>locals</tt> string contain local variable declarations, and the <tt>code</tt> string contains the resulting wrapper code.<p>
-<p>
-The method <tt>add_local()</tt> creates a new local variable which is managed with an internal symbol table (that detects variable conflicts and reports potential errors). The <tt>new_local()</tt> method can be used to create a new local variable that is guaranteed to be unique. Since a renaming might be required, this latter method returns the name of the variable that was actually selected for use (typically, this is derived from the original name).<p>
-<p>
-The <tt>print()</tt> method can be used to emit the wrapper function to a file. The printing process consolidates all of the strings into a single result.<p>
-<p>
-Here is a very simple example of the wrapper function class :<p>
-<p>
-<blockquote><pre>WrapperFunction f;
-
-f.def << "void count_n(int n) {";
-f.add_local("int","i");
-f.code << tab4 << "for (i = 0; i < n; i++) {\n"
- << tab8 << "printf(\"%d\\n\",i);\n"
- << tab4 << "}\n"
- << "}\n";
-
-f.print(f_wrappers);
-
-</pre></blockquote>
-This produces the following output :<p>
-<p>
-<blockquote><pre>void count_n(int n) {
- int i;
- for (i = 0; i < n; i++) {
- printf("%d\n",i);
- }
-}
-
-</pre></blockquote>
-Of course, as you can guess, the functions actually generated by your language module will be more complicated than this.<p>
-<a name="n6"></a><h2> Typemaps (from C)</h2>
-The typemapper plays a big role in generating code for all of SWIG's modules. Understanding the <tt>%typemap</tt> directive and how it works is probably a good starting point for understanding this section.<p>
-<a name="n26"></a><h3> The typemap C API.</h3>
- There is a relatively simple C API for managing typemaps in language modules.<p>
-<p>
-<h6> <b>void typemap_register(char *op, char *lang, DataType *type, char *pname,</b> <b> char *code, ParmList *l = 0);</b></h6>
-<dl>
-<dt><dd>
-<dt><dd>Registers a new typemap with the typemapper. This is the C equivalent of the <tt>%typemap </tt>directive. For example :
-<dt><dd>
-<blockquote><pre> %typemap(lang,op) type pname { ... code ... };
- %typemap(lang,op) type pname(ParmList) { ... code ... };
-
-</pre></blockquote>
-<dt><dd><tt>code</tt> contains the actual typemap code, while <tt>l</tt> is a parameter list containing local variable declarations. Normally, it is not necessary to execute this function from language modules.
-<dt><dd>
-</dl>
-<h6> void typemap_register_default(char *op, char *lang, int type, int ptr, char *arraystr, char *code, ParmList *args)</h6>
-<dl>
-<dt><dd>
-<dt><dd>Registers a default typemap. This works in the same way as the normal registration function, but takes a type code (an integer) instead. Default typemaps are more general than normal typemaps (see below).
-<dt><dd>
-</dl>
-<h6> char *typemap_lookup(char *op, char *lang, DataType *type, char *pname, char *source, char *target, WrapperFunction *f = 0);</h6>
-<dl>
-<dt><dd>
-<dt><dd>Looks up a typemap, performs variable substitutions, and returns a string with the corresponding typemap code. The tuple <tt>(op, lang, type, pname)</tt> determine which typemap to find. <tt>source</tt> contains the string to be assigned to the <tt>$source</tt> variable, <tt>target</tt> contains the string to be assigned to the<tt> $target</tt> variable. <tt>f</tt> is an optional wrapper function object. It should be supplied to support parameterized typemaps (ie. typemaps that declare additional local variables).
-<dt><dd>
-<dt><dd><tt>typemap_lookup()</tt> returns NULL is no typemap is found. Otherwise it returns a string containing the updated typemap code. This code has a number of variables substituted including <tt>$source</tt>, <tt>$target</tt>, <tt>$type</tt>, <tt>$mangle</tt>, and <tt>$basetype</tt>.
-<dt><dd>
-</dl>
-<h6> char *typemap_check(char *op, char *lang, DataType *type, char *pname)</h6>
-<p>
-<dl>
-<dt><dd>Checks to see if a typemap exists. The tuple <tt>(op, lang, type, pname)</tt> determine which typemap to find. If the typemap exists, the raw typemap code is returned. Otherwise, NULL is returned. While <tt>typemap_lookup()</tt> could be used to accomplish the same thing, this function is more compact and is significantly faster since it does not perform any variable substitutions.
-<dt><dd>
-</dl>
-<a name="n27"></a><h3> What happens on typemap lookup?</h3>
-When looking for a typemap, SWIG searches for a match in a series of steps.<p>
-<p>
-<ul>
-<li>Explicit typemaps. These are specified directly with the <tt>%typemap()</tt> directive. Named typemaps have the highest precedence while arrays have higher precedence than pointers (see the typemap chapter for more details).
-<li>If no explicit typemap is found, mappings applied with the <tt>%apply </tt>directive are checked. Basically, <tt>%apply </tt>is nothing more than a glorified renaming operation. We rename the datatype and see if there are any explicit typemaps that match. If so, we use the typemap that was found.
-<li>Default typemaps. If no match is found with either explicit typemaps or apply directives, we make a final search using the default typemap. Unlike other typemaps, default typemaps are applied to the raw SWIG internal datatypes (<tt>T_INT</tt>, <tt>T_DOUBLE</tt>, <tt>T_CHAR</tt>, etc...). As a result, they are insentive to typedefs and renaming operations. If nothing is found here, a NULL pointer is returned indicating that no mapping was found for that particular datatype.
-</ul>
-<p>
-Another way to think of the typemap mechanism is that it always tries to apply the most specific typemap that can be found for any particular datatype. When searching, it starts with the most specific and works its way out to the most general specification. If nothing is found it gives up and returns a NULL pointer.<p>
-<a name="n28"></a><h3> How many typemaps are there?</h3>
-All typemaps are identified by an operation string such as "in", "out", "memberin", etc... A number of typemaps are defined by other parts of SWIG, but you can create any sort of typemap that you wish by simply picking a new name and using it when making calls to <tt>typemap_lookup()</tt> and <tt>typemap_check()</tt>. <p>
-<a name="n7"></a><h2> File management</h2>
-The following functions are provided for managing files within SWIG. <p>
-<p>
-<h6> void add_directory(char *dirname);</h6>
-<dl>
-<dt><dd>
-<dt><dd>Adds a new directory to the search path used to locate SWIG library files. This is the C equivalent of the <tt>swig</tt> <tt>-I</tt> option.
-<dt><dd>
-</dl>
-<h6> int insert_file(char *filename, FILE *output);</h6>
-<dl>
-<dt><dd>
-<dt><dd>Searches for a file and copies it into the given output stream. The search process goes through the SWIG library mechanism which first checks the current directory, then in various parts of the SWIG library for a match. Returns -1 if the file is not found. Language modules often use this function to insert supporting code. Usually these code fragments are given a `<tt>.swg</tt>' suffix and are placed in the SWIG library.
-<dt><dd>
-</dl>
-<h6> int get_file(char *filename, String &str);</h6>
-<dl>
-<dt><dd>
-<dt><dd> Searches for a file and returns its contents in the String <tt>str.</tt>Returns a -1 if the file is not found.
-</dl>
-<p>
-<h6> int checkout_file(char *source, char *dest);</h6>
-<dl>
-<dt><dd>
-<dt><dd>Copies a file from the SWIG library into the current directory. <tt>dest </tt>is the filename of the desired file. This function will not replace a file that already exists. The primary use of this function is to give the user supporting code. For example, we could check out a Makefile if none exists. Returns -1 on failure.
-<dt><dd>
-</dl>
-<h6> int include_file(char *filename);</h6>
-<dl>
-<dt><dd>
-<dt><dd>The C equivalent of the SWIG <tt>%include</tt> directive. When called, SWIG will attempt to open <tt>filename</tt> and start parsing all of its contents. If successful, parsing of the new file will take place immediately. When the end of the file is reached, the parser switches back to the input file being read prior to this call. Returns -1 if the file is not found.
-</dl>
-<a name="n8"></a><h2> Naming Services</h2>
-The naming module provides methods for generating the names of wrapper functions, accessor functions, and other aspects of SWIG. Each function returns a new name that is a syntactically correct C identifier where invalid characters have been converted to a "_". <p>
-<p>
-<h6> char *name_wrapper(char *fname, char *prefix);</h6>
-<dl>
-<dt><dd>Returns the name of a wrapper function. By default, it will be "<tt>_wrap_prefixfname</tt>".
-<dt><dd>
-</dl>
-<h6> char *name_member(char *mname, char *classname;</h6>
-<dl>
-<dt><dd>Returns the name of a C++ accessor function. Normally, this is "<tt>classname_mname</tt>".
-<dt><dd>
-</dl>
-<h6> char *name_get(char *vname);</h6>
-<dl>
-<dt><dd>Returns the name of a function to get the value of a variable or class data member. Normally "<tt>vname_get</tt>" is returned.
-<dt><dd>
-</dl>
-<h6> char *name_set(char *vname);</h6>
-<dl>
-<dt><dd>Returns the name of a function to set the value of a variable or class data member. Normally, "<tt>vname_set</tt>" is returned.
-<dt><dd>
-</dl>
-<h6> char *name_construct(char *classname);</h6>
-<dl>
-<dt><dd>Returns the name of a constructor function. Normally returns "<tt>new_classname</tt>".
-<dt><dd>
-</dl>
-<h6> char *name_destroy(char *classname);</h6>
-<dl>
-<dt><dd>Returns the name of a destructor function. Normally returns "<tt>delete_classname</tt>".
-<dt><dd>
-</dl>
-Each function may also accept an optional parameter of <tt>AS_IS</tt>. This suppresses the conversion of illegal characters (a process that is sometimes required). For example :<p>
-<p>
-<blockquote><pre>char *name = name_member("foo","bar",AS_IS); // Produce a name, but don't change
- // illegal characters.
-
-</pre></blockquote>
-It is critical that language modules use the naming functions. These function are used throughout SWIG and provide a centralized mechanism for keeping track of functions that have been generated, managing multiple files, and so forth. In future releases, it may be possible to change the naming scheme used by SWIG. Using these functions should insure future compatibility.<p>
-<a name="n9"></a><h2> Code Generation Functions</h2>
-The following functions are used to emit code that is generally useful and used in essentially every SWIG language module.<p>
-<p>
-<h6> int emit_args(DataType *t, ParmList *l, WrapperFunction &f);</h6>
-<dl>
-<dt><dd>Creates all of the local variables used for function arguments and return value. <tt>t</tt> is the return datatype of the function, <tt>l</tt> is the parameter list holding all of the function arguments. <tt>f</tt> is a WrapperFunction object where the local variables will be created.
-<dt><dd>
-</dl>
-<h6> void emit_func_call(char *name, DataType *t, ParmList *l, WrapperFunction &f);</h6>
-<dl>
-<dt><dd>Creates a function call to a C function. <tt>name</tt> is the name of the C function, <tt>t</tt> is the return datatype, <tt>l</tt> is the function parameters and <tt>f</tt> is a WrapperFunction object. The code generated by this function assumes that one has first called <tt>emit_args()</tt>.
-<dt><dd>
-</dl>
-<h6> void emit_banner(FILE *file);</h6>
-<dl>
-<dt><dd>Emits the SWIG banner comment to the output file.
-</dl>
-<p>
-<h6> void emit_set_get(char *name, char *rename, DataType *t);</h6>
-<dl>
-<dt><dd>Given a variable of type <tt>t</tt>, this function creates two functions to set and get the value. These functions are then wrapped like normal C functions. <tt>name</tt> is the real name of the variable. <tt>rename</tt> is the renamed version of the variable.
-<dt><dd>
-</dl>
-<h6> void emit_ptr_equivalence(FILE *file);</h6>
-<dl>
-<dt><dd>To keep track of datatypes, SWIG maintains an internal table of "equivalent" datatypes. This table is updated by typedef, class definitions, and other C constructs. This function emits code compatible with the type-checker that is needed to make sure pointers work correctly. Typically this function is called after an interface file has been parsed completely.
-</dl>
-<a name="n10"></a><h2> Writing a Real Language Module</h2>
-Whew, assuming you've made it this far, we're ready to write a real language module. In this example, we'll develop a simple Tcl module. Tcl has been chosen because it has a relatively simple C API that is well documented and easy to understand. The module developed here is not the same as the real SWIG Tcl module (which is significantly more complicated). <p>
-<a name="n29"></a><h3> The header file</h3>
-We will start with the same header file as before :<p>
-<p>
-<blockquote><pre>// File : mylang.h
-// A simple SWIG Language module
-
-class MYLANG : public Language {
-private:
- char *module;
-public :
- MYLANG() {
- module = 0;
- };
- // Virtual functions required by the SWIG parser
- void parse_args(int, char *argv[]);
- void parse();
- void create_function(char *, char *, DataType *, ParmList *);
- void link_variable(char *, char *, DataType *);
- void declare_const(char *, char *, DataType *, char *);
- void initialize(void);
- void headers(void);
- void close(void);
- void set_module(char *,char **);
- void create_command(char *, char *);
-};
-
-</pre></blockquote>
-<a name="n30"></a><h3> Command Line Options and Basic Initialization</h3>
-Command line options are parsed using the <tt>parse_args()</tt> method :<p>
-<blockquote><pre>
-// ------------------------------------------------------------------------
-// A simple SWIG Language module
-//
-// ------------------------------------------------------------------------
-
-#include "swig.h"
-#include "mylang.h"
-
-static char *usage = "\
-My Language Options\n\
- -module name - Set name of module\n\n";
-
-// ---------------------------------------------------------------------
-// MYLANG::parse_args(int argc, char *argv[])
-//
-// Parse my command line options and initialize by variables.
-// ---------------------------------------------------------------------
-
-void MYLANG::parse_args(int argc, char *argv[]) {
- // Look for certain command line options
- for (int i = 1; i < argc; i++) {
- if (argv[i]) {
- if (strcmp(argv[i],"-module") == 0) {
- if (argv[i+1]) {
- set_module(argv[i+1],0);
- mark_arg(i);
- mark_arg(i+1);
- i++;
- } else {
- arg_error();
- }
- } else if (strcmp(argv[i],"-help") == 0) {
- fprintf(stderr,"%s\n", usage);
- }
- }
- }
- // Set location of SWIG library
- strcpy(LibDir,"tcl");
-
- // Add a symbol to the parser for conditional compilation
- add_symbol("SWIGTCL",0,0);
-
- // Add typemap definitions
- typemap_lang = "tcl";
-}
-
-</pre></blockquote>
-Parsing command line options follows the same conventions as for writing a C++ main program with one caveat. For each option that your language module parses, you need to call the function <tt>mark_arg()</tt>. This tells the SWIG main program that your module found a valid option and used it. If you don't do this, SWIG will exit with an error message about unrecognized command line options.<p>
-<p>
-After processing command line options, you next need to set the variable <tt>LibDir</tt> with the name of the subdirectory your language will use to find files in the SWIG library. Since we are making a new Tcl module, we'll just set this to "<tt>tcl</tt>".<p>
-<p>
-Next, we may want to add a symbol to SWIG's symbol table. In this case we're adding "<tt>SWIGTCL</tt>" to indicate that we're using Tcl. SWIG modules can use this for conditional compilation and detecting your module using <tt>#ifdef</tt>. <p>
-<p>
-Finally, we need to set the variable <tt>typemap_lang</tt>. This should be assigned a name that you would like to use for all typemap declarations. When a user gives a typemap, they would use this name as the target language.<p>
-<a name="n31"></a><h3> Starting the parser</h3>
-To start the SWIG parser, the <tt>parse()</tt> method is used :<p>
-<p>
-<blockquote><pre>// ---------------------------------------------------------------------
-// void MYLANG::parse()
-//
-// Start parsing an interface file for MYLANG.
-// ---------------------------------------------------------------------
-
-void MYLANG::parse() {
-
- fprintf(stderr,"Making wrappers for Tcl\n");
- headers(); // Emit header files and other supporting code
-
- // Tell the parser to first include a typemap definition file
-
- if (include_file("lang.map") == -1) {
- fprintf(stderr,"Unable to find lang.map!\n");
- SWIG_exit(1);
- }
- yyparse(); // Run the SWIG parser
-}
-</pre></blockquote>
-<p>
-This function should print some kind of message to the user indicating what language is being targeted. The <tt>headers()</tt> method is called (see below) to emit support code and header files. Finally, we make a call to <tt>yyparse()</tt>. This starts the SWIG parser and does not return until the entire interface file has been read. <p>
-<p>
-In our implementation, we have also added code to immediately include a file `<tt>lang.map</tt>'. This file will contain typemap definitions to be used by our module and is described in detail later. <p>
-<a name="n32"></a><h3> Emitting headers and support code</h3>
-Prior to emitting any code, our module should emit standard header files and support code. This is done using the <tt>headers()</tt> method :<p>
-<blockquote><pre>// ---------------------------------------------------------------------
-// MYLANG::headers(void)
-//
-// Generate the appropriate header files for MYLANG interface.
-// ----------------------------------------------------------------------
-
-void MYLANG::headers(void)
-{
- emit_banner(f_header); // Print the SWIG banner message
- fprintf(f_header,"/* Implementation : My TCL */\n\n");
-
- // Include header file code fragment into the output
- if (insert_file("header.swg",f_header) == -1) {
- fprintf(stderr,"Fatal Error. Unable to locate 'header.swg'.\n");
- SWIG_exit(1);
- }
-
- // Emit the default SWIG pointer type-checker (for strings)
- if (insert_file("swigptr.swg",f_header) == -1) {
- fprintf(stderr,"Fatal Error. Unable to locate 'swigptr.swg'.\n");
- SWIG_exit(1);
- }
-}
-</pre></blockquote>
-In this implementation, we emit the standard SWIG banner followed by a comment indicating which language module is being used. After that, we are going to include two different files. `<tt>header.swg'</tt> is a file containing standard declarations needed to build a Tcl extension. For our example, it will look like this :<p>
-<p>
-<blockquote><pre>/* File : header.swg */
-#include <tcl.h>
-
-</pre></blockquote>
-The file `<tt>swigptr.swg'</tt> contains the standard SWIG pointer-type checking library. This library contains about 300 lines of rather nasty looking support code that define the following 3 functions :<p>
-<p>
-<h6> void SWIG_RegisterMapping(char *type1, char *type, void *(*cast)(void *))</h6>
-<dl>
-<dt><dd>Creates a mapping between C datatypes <tt>type1</tt> and <tt>type2</tt>. This is registered with the runtime type-checker and is similiar to a typedef. <tt>cast</tt> is an optional function pointer defining a method for proper pointer conversion (if needed). Normally, cast is only used when converting between base and derived classes in C++ and is needed for proper implementation of multiple inheritance.
-</dl>
-<p>
-<h6> void SWIG_MakePtr(char *str, void *ptr, char *type);</h6>
-<dl>
-<dt><dd>Makes a string representation of a C pointer. The result is stored in <tt>str</tt> which is assumed to be large enough to hold the result. <tt>ptr</tt> contains the pointer value and <tt>type</tt> is a string code corresponding to the datatype.
-<dt><dd>
-</dl>
-<h6> char *SWIG_GetPtr(char *str, void **ptr, char *type);</h6>
-<dl>
-<dt><dd>Extracts a pointer from its string representation, performs type-checking, and casting. <tt>str</tt> is the string containing the pointer-value representation, <tt>ptr</tt> is the address of the pointer that will be returned, and <tt>type </tt>is the string code corresponding to the datatype. If a type-error occurs, the function returns a <tt>char *</tt> corresponding to the part of the input string that was invalid, otherwise the function returns NULL. If a NULL pointer is given for <tt>type</tt>, the function will accept a pointer of any type.
-</dl>
-<p>
-We will use these functions later.<p>
-<a name="n33"></a><h3> Setting a module name</h3>
-The <tt>set_module()</tt> method is used whenever the <tt>%module</tt> directive is encountered.<p>
-<blockquote><pre>
-// ---------------------------------------------------------------------
-// MYLANG::set_module(char *mod_name,char **mod_list)
-//
-// Sets the module name. Does nothing if it's already set (so it can
-// be overriddent as a command line option).
-//
-// mod_list is a NULL-terminated list of additional modules to initialize
-// and is only provided if the user specifies something like this :
-// %module foo, mod1, mod2, mod3, mod4
-//----------------------------------------------------------------------
-
-void MYLANG::set_module(char *mod_name, char **mod_list) {
- if (module) return;
- module = new char[strlen(mod_name)+1];
- strcpy(module,mod_name);
- // Make sure the name conforms to Tcl naming conventions
- for (char *c = module; (*c); c++)
- *c = tolower(*c);
- toupper(module);
-}
-
-
-</pre></blockquote>
-This function may, in fact, be called multiple times in the course of processing. Normally, we only allow a module name to be set once and ignore all subsequent calls however.<p>
-<a name="n34"></a><h3> Final Initialization</h3>
-The initialization of a module takes several steps--parsing command line options, printing standard header files, starting the parser, and setting the module name. The final step in initialization is calling the <tt>initialize()</tt> method :<p>
-<p>
-<blockquote><pre>// --------------------------------------------------------------------
-// MYLANG::initialize(void)
-//
-// Produces an initialization function. Assumes that the module
-// name has already been specified.
-// ---------------------------------------------------------------------
-
-void MYLANG::initialize()
-{
- // Check if a module has been defined
- if (!module) {
- fprintf(stderr,"Warning. No module name given!\n");
- module = "swig";
- }
-
- // Generate a CPP symbol containing the name of the initialization function
- fprintf(f_header,"#define SWIG_init %s_Init\n\n\n", module);
-
- // Start generating the initialization function
- fprintf(f_init,"int SWIG_init(Tcl_Interp *interp) {\n");
- fprintf(f_init,"\t if (interp == 0) return TCL_ERROR;\n");
-}
-
-</pre></blockquote>
-The <tt>initialize()</tt> method should create the module initialization function by emitting code to <tt>f_init</tt> as shown. By this point, we should already know the name of the module, but should check just in case. The preferred style of creating the initialization function is to create a C preprocessor symbol <tt>SWIG_init</tt>. Doing so may look weird, but it turns out that many SWIG library files may want to know the name of the initialization function. If we define a symbol for it, these files can simply assume that it's called <tt>SWIG_init()</tt> and everything will work out (okay, so it's a hack).<p>
-<a name="n35"></a><h3> Cleanup </h3>
-When an interface file has finished parsing, we need to clean everything up. This is done using the <tt>close()</tt> method :<p>
-<p>
-<blockquote><pre>// ---------------------------------------------------------------------
-// MYLANG::close(void)
-//
-// Wrap things up. Close initialization function.
-// ---------------------------------------------------------------------
-
-void MYLANG::close(void)
-{
- // Dump the pointer equivalency table
- emit_ptr_equivalence(f_init);
-
- // Finish off our init function and print it to the init file
- fprintf(f_init,"\t return TCL_OK;\n");
- fprintf(f_init,"}\n");
-}
-
-</pre></blockquote>
-The <tt>close()</tt> method should first call <tt>emit_ptr_equivalence()</tt> if the SWIG pointer type checker has been used. This dumps out support code to make sure the type-checker works correctly. Afterwards, we simply need to terminate our initialization function as shown. After this function has been called, SWIG dumps out all of its documentation files and exits.<p>
-<a name="n36"></a><h3> Creating Commands</h3>
-Now, we're moving into the code generation part of SWIG. The first step is to make a function to create scripting language commands. This is done using the <tt>create_command()</tt> function :<p>
-<p>
-<blockquote><pre>// ----------------------------------------------------------------------
-// MYLANG::create_command(char *cname, char *iname)
-//
-// Creates a Tcl command from a C function.
-// ----------------------------------------------------------------------
-void MYLANG::create_command(char *cname, char *iname) {
- // Create a name for the wrapper function
- char *wname = name_wrapper(cname,"");
-
- // Create a Tcl command
- fprintf(f_init,"\t Tcl_CreateCommand(interp,\"%s\",%s, (ClientData) NULL,
- (Tcl_CmdDeleteProc *) NULL);\n", iname, wname);
-}
-</pre></blockquote>
-<p>
-For our Tcl module, this just calls Tcl_CreateCommand to make a new scripting language command. <p>
-<a name="n37"></a><h3> Creating a Wrapper Function</h3>
-The most complicated part of writing a language module is the process of creating wrapper functions. This is done using the <tt>create_function()</tt> method as shown here :<p>
-<blockquote><pre>
-// ----------------------------------------------------------------------
-// MYLANG::create_function(char *name, char *iname, DataType *d, ParmList *l)
-//
-// Create a function declaration and register it with the interpreter.
-// ----------------------------------------------------------------------
-
-void MYLANG::create_function(char *name, char *iname, DataType *t, ParmList *l)
-{
- String source, target;
- char *tm;
- String cleanup, outarg;
- WrapperFunction f;
-
- // Make a wrapper name for this function
- char *wname = name_wrapper(iname,"");
-
- // Now write the wrapper function itself
- f.def << "static int " << wname << "(ClientData clientData, Tcl_Interp *interp, int
-argc, char *argv[]) {\n";
-
- // Emit all of the local variables for holding arguments.
- int pcount = emit_args(t,l,f);
-
- // Get number of optional/default arguments
- int numopt = l->numopt();
-
- // Emit count to check the number of arguments
- f.code << tab4 << "if ((argc < " << (pcount-numopt) + 1 << ") || (argc > "
- << l->numarg()+1 << ")) {\n"
- << tab8 << "Tcl_SetResult(interp, \"Wrong # args.\",TCL_STATIC);\n"
- << tab8 << "return TCL_ERROR;\n"
- << tab4 << "}\n";
-
- // Now walk the function parameter list and generate code to get arguments
- int j = 0; // Total number of non-optional arguments
-
- for (int i = 0; i < pcount ; i++) {
- Parm &p = (*l)[i]; // Get the ith argument
- source = "";
- target = "";
-
- // Produce string representation of source and target arguments
- source << "argv[" << j+1 << "]";
- target << "_arg" << i;
- if (!p.ignore) {
- if (j >= (pcount-numopt)) // Check if parsing an optional argument
- f.code << tab4 << "if argc >" << j+1 << ") {\n";
-
- // Get typemap for this argument
- tm = typemap_lookup("in",typemap_lang,p.t,p.name,source,target,&f);
- if (tm) {
- f.code << tm << "\n";
- f.code.replace("$arg",source); // Perform a variable replacement
- } else {
- fprintf(stderr,"%s : Line %d. No typemapping for datatype %s\n",
- input_file,line_number, p.t->print_type());
- }
- if (j >= (pcount-numopt))
- f.code << tab4 << "} \n";
- j++;
- }
-
- // Check to see if there was any sort of a constaint typemap
- if ((tm = typemap_lookup("check",typemap_lang,p.t,p.name,source,target))) {
- f.code << tm << "\n";
- f.code.replace("$arg",source);
- }
-
- // Check if there was any cleanup code (save it for later)
- if ((tm = typemap_lookup("freearg",typemap_lang,p.t,p.name,target,
- "interp->result"))) {
- cleanup << tm << "\n";
- cleanup.replace("$arg",source);
- }
- if ((tm = typemap_lookup("argout",typemap_lang,p.t,p.name,target,
- "interp->result"))) {
- outarg << tm << "\n";
- outarg.replace("$arg",source);
- }
- }
-
- // Now write code to make the function call
- emit_func_call(name,t,l,f);
-
- // Return value if necessary
- if ((t->type != T_VOID) || (t->is_pointer)) {
- if ((tm = typemap_lookup("out",typemap_lang,t,name,"_result","interp->result"))) {
- // Yep. Use it instead of the default
- f.code << tm << "\n";
- } else {
- fprintf(stderr,"%s : Line %d. No return typemap for datatype %s\n",
- input_file,line_number,t->print_type());
- }
- }
-
- // Dump argument output code;
- f.code << outarg;
-
- // Dump the argument cleanup code
- f.code << cleanup;
-
- // Look for any remaining cleanup. This processes the %new directive
- if (NewObject) {
- if ((tm = typemap_lookup("newfree",typemap_lang,t,iname,"_result",""))) {
- f.code << tm << "\n";
- }
- }
-
- // Special processing on return value.
- if ((tm = typemap_lookup("ret",typemap_lang,t,name,"_result",""))) {
- f.code << tm << "\n";
- }
-
- // Wrap things up (in a manner of speaking)
- f.code << tab4 << "return TCL_OK;\n}";
-
- // Substitute the cleanup code (some exception handlers like to have this)
- f.code.replace("$cleanup",cleanup);
-
- // Emit the function
- f.print(f_wrappers);
-
- // Now register the function with the language
- create_command(iname,iname);
-}
-</pre></blockquote>
-<p>
-Creating a wrapper function really boils down to 3 components :<p>
-<p>
-<ul>
-<li>Emit local variables and handling input arguments.
-<li>Call the real C function.
-<li>Convert the return value to a scripting language representation.
-</ul>
-<p>
-In our implementation, most of this work is done using typemaps. In fact, the role of the C++ code is really just to process typemaps in the appropriate order and to combine strings in the correct manner. The following typemaps are used in this procedure :<p>
-<p>
-<ul>
-<li>"in". This is used to convert function arguments from Tcl to C.
-<li>"out". This is used to convert the return value from C to Tcl.
-<li>"check". This is used to apply constraints to the input values.
-<li>"argout". Used to return values through function parameters.
-<li>"freearg". Used to clean up arguments after a function call (possibly to release memory, etc...)
-<li>"ret". Used to clean up the return value of a C function (possibly to release memory).
-<li>"newfree" this is special processing applied when the <tt>%new</tt> directive has been used. Usually its used to clean up memory.
-</ul>
-<p>
-It may take awhile for this function to sink in, but its operation will hopefully become more clear shortly. <p>
-<a name="n38"></a><h3> Manipulating Global Variables</h3>
-To provide access to C global variables, the <tt>link_variable()</tt> method is used. In the case of Tcl, only <tt>int</tt>, <tt>double</tt>, and <tt>char * </tt>datatypes can be safely linked.<p>
-<p>
-<blockquote><pre>// -----------------------------------------------------------------------
-// MYLANG::link_variable(char *name, char *iname, DataType *t)
-//
-// Create a Tcl link to a C variable.
-// -----------------------------------------------------------------------
-
-void MYLANG::link_variable(char *name, char *iname, DataType *t) {
- char *tm;
-
- // Uses a typemap to stick code into the module initialization function
- if ((tm = typemap_lookup("varinit",typemap_lang,t,name,name,iname))) {
- String temp = tm;
- if (Status & STAT_READONLY)
- temp.replace("$status"," | TCL_LINK_READ_ONLY");
- else
- temp.replace("$status","");
- fprintf(f_init,"%s\n",(char *) temp);
- } else {
- fprintf(stderr,"%s : Line %d. Unable to link with variable type %s\n",
- input_file,line_number,t->print_type());
- }
-}
-</pre></blockquote>
-<p>
-In this case, the procedure is looking for a typemap "varinit". We'll use the code specified with this typemap to create variable links. If no typemap is supplied or the user gives an unsupported datatypes, a warning message will be generated.<p>
-<p>
-It is also worth noting that the <tt>Status</tt> variable contains information about whether or not a variable is read-only or not. To test for this, use the technique shown in the code above. Read-only variables may require special processing as shown.<p>
-<a name="n39"></a><h3> Constants</h3>
-Finally, creating constants is accomplished using the <tt>declare_const()</tt> method. For Tcl, we could do this :<p>
- <p>
-<blockquote><pre>// -----------------------------------------------------------------------
-// MYLANG::declare_const(char *name, char *iname, DataType *type, char *value)
-//
-// Makes a constant.
-// ------------------------------------------------------------------------
-
-void MYLANG::declare_const(char *name, char *iname, DataType *type, char *value) {
-
- char *tm;
- if ((tm = typemap_lookup("const",typemap_lang,type,name,name,iname))) {
- String str = tm;
- str.replace("$value",value);
- fprintf(f_init,"%s\n", (char *) str);
- } else {
- fprintf(stderr,"%s : Line %d. Unable to create constant %s = %s\n",
- input_file, line_number, type->print_type(), value);
- }
-}
-
-</pre></blockquote>
-We take the same approach used to create variables. In this case, the `<tt>const</tt>' typemap specifies the special processing.<p>
-<p>
-The value of a constant is a string produced by the SWIG parser. It may contain an arithmetic expression such as "3 + 4*(7+8)". Because of this, it is critical to use this string in a way that allows it to be evaluated by the C compiler (this will be apparent when the typemaps are given).<p>
-<a name="n40"></a><h3> A Quick Intermission</h3>
-We are now done writing all of the methods for our language class. Of all of the methods, <tt>create_function()</tt> is the most complicated and tends to do most of the work. We have also ignored issues related to documentation processing and C++ handling (although C++ will work with the functions we have defined so far).<p>
-<p>
-While our C++ implementation is done, we still do not have a working language module. In fact, if we run SWIG on the following interface file :<p>
-<p>
-<blockquote><pre>/* File : example.i */
-%module example
-%{
-/* Put headers and other declarations here */
-%}
-
-// A function
-extern double foo(double a, double b);
-
-// A variable
-extern int bar;
-
-// A constant
-#define SPAM 42
-
-</pre></blockquote>
-we get the following errors :<p>
-<p>
-<blockquote><pre>[beazley@guinness lang]$ ./myswig example.i
-Making wrappers for My Tcl
-example.i : Line 9. No typemapping for datatype double
-example.i : Line 9. No typemapping for datatype double
-example.i : Line 9. No return typemap for datatype double
-example.i : Line 12. Unable to link with variable type int
-example.i : Line 16. Unable to create constant int = 42
-[beazley@guinness lang]$
-
-</pre></blockquote>
-The reason for this is that we have not yet defined any processing for real datatypes. For example, our language module has no idea how to convert doubles into Tcl strings, how to link with C variables and so on. To do this, we need to write a collection of typemaps.<p>
-<a name="n41"></a><h3> Writing the default typemaps</h3>
-In our earlier <tt>parse()</tt> method, there is a statement to include the file `<tt>lang.map</tt>'. We will use this file to write typemaps for our new language module. The `<tt>lang.map</tt>' file will actually go through the SWIG parser so we can write our typemaps using the normal <tt>%typemap</tt> directive. This approach makes it easy for us to debug and test our module because the typemaps can be developed and tested without having to repeatedly recompile the C++ part of the module. <p>
-<p>
-Without further delay, here is the typemap file for our module (you might want to sit down) :<p>
-<p>
-<blockquote><pre>// ----------------------------------------------------------------------
-// lang.map
-//
-// This file defines all of the type-mappings for our language (TCL).
-// A typemap of 'SWIG_DEFAULT_TYPE' should be used to create default
-// mappings.
-// ----------------------------------------------------------------------
-
-/**************************** FUNCTION INPUTS ****************************/
-
-// Integers
-%typemap(in) int SWIG_DEFAULT_TYPE,
- short SWIG_DEFAULT_TYPE,
- long SWIG_DEFAULT_TYPE,
- unsigned int SWIG_DEFAULT_TYPE,
- unsigned short SWIG_DEFAULT_TYPE,
- unsigned long SWIG_DEFAULT_TYPE,
- signed char SWIG_DEFAULT_TYPE,
- unsigned char SWIG_DEFAULT_TYPE
-{
- int temp;
- if (Tcl_GetInt(interp, $source, &temp) == TCL_ERROR) return TCL_ERROR;
- $target = ($type) temp;
-}
-
-// Floating point
-%typemap(in) float SWIG_DEFAULT_TYPE,
- double SWIG_DEFAULT_TYPE
-{
- double temp;
- if (Tcl_GetDouble(interp, $source, &temp) == TCL_ERROR) return TCL_ERROR;
- $target = ($type) temp;
-}
-
-// Strings
-%typemap(in) char * SWIG_DEFAULT_TYPE
-{
- $target = $source;
-}
-
-// void *
-%typemap(in) void * SWIG_DEFAULT_TYPE
-{
- if (SWIG_GetPtr($source,(void **) &$target, (char *) 0)) {
- Tcl_SetResult(interp,"Type error. Expected a pointer",TCL_STATIC);
- return TCL_ERROR;
- }
-}
-
-// User defined types and all other pointers
-%typemap(in) User * SWIG_DEFAULT_TYPE
-{
- if (SWIG_GetPtr($source,(void **) &$target, "$mangle")) {
- Tcl_SetResult(interp,"Type error. Expected a $mangle",TCL_STATIC);
- return TCL_ERROR;
- }
-}
-
-/**************************** FUNCTION OUTPUTS ****************************/
-
-// Signed integers
-%typemap(out) int SWIG_DEFAULT_TYPE,
- short SWIG_DEFAULT_TYPE,
- long SWIG_DEFAULT_TYPE,
- signed char SWIG_DEFAULT_TYPE
-{
- sprintf($target,"%ld", (long) $source);
-}
-
-// Unsigned integers
-%typemap(out) unsigned SWIG_DEFAULT_TYPE,
- unsigned short SWIG_DEFAULT_TYPE,
- unsigned long SWIG_DEFAULT_TYPE,
- unsigned char SWIG_DEFAULT_TYPE
-{
- sprintf($target,"%lu", (unsigned long) $source);
-}
-
-// Floating point
-%typemap(out) double SWIG_DEFAULT_TYPE,
- float SWIG_DEFAULT_TYPE
-{
- Tcl_PrintDouble(interp,(double) $source,interp->result);
-}
-
-// Strings
-%typemap(out) char *SWIG_DEFAULT_TYPE
-{
- Tcl_SetResult(interp,$source,TCL_VOLATILE);
-}
-
-// Pointers
-%typemap(out) User *SWIG_DEFAULT_TYPE
-{
- SWIG_MakePtr($target,(void *) $source, "$mangle");
-}
-
-/**************************** VARIABLE CREATION ****************************/
-
-// Integers
-%typemap(varinit) int SWIG_DEFAULT_TYPE,
- unsigned int SWIG_DEFAULT_TYPE
-{
- Tcl_LinkVar(interp, "$target", (char *) &$source, TCL_LINK_INT $status);
-}
-
-// Doubles
-%typemap(varinit) double SWIG_DEFAULT_TYPE {
- Tcl_LinkVar(interp,"$target", (char *) &$source, TCL_LINK_DOUBLE $status);
-}
-
-// Strings
-%typemap(varinit) char * SWIG_DEFAULT_TYPE {
- Tcl_LinkVar(interp,"$target", (char *) &$source, TCL_LINK_STRING $status);
-}
-
-/****************************** CONSTANTS **********************************/
-
-// Signed Integers
-%typemap(const) int SWIG_DEFAULT_TYPE,
- short SWIG_DEFAULT_TYPE,
- long SWIG_DEFAULT_TYPE,
- signed char SWIG_DEFAULT_TYPE
-{
- static char *_wrap_$target;
- _wrap_$target = (char *) malloc(40);
- sprintf(_wrap_$target,"%ld",$value);
- Tcl_LinkVar(interp,"$target", (char *) &_wrap_$target, TCL_LINK_STRING |
-TCL_LINK_READ_ONLY);
-}
-
-// Unsigned integers
-%typemap(const) unsigned SWIG_DEFAULT_TYPE,
- unsigned short SWIG_DEFAULT_TYPE,
- unsigned long SWIG_DEFAULT_TYPE,
- unsigned char SWIG_DEFAULT_TYPE
-{
- static char *_wrap_$target;
- _wrap_$target = (char *) malloc(40);
- sprintf(_wrap_$target,"%lu",$value);
- Tcl_LinkVar(interp,"$target", (char *) &_wrap_$target, TCL_LINK_STRING |
-TCL_LINK_READ_ONLY);
-}
-
-// Doubles and floats
-%typemap(const) double SWIG_DEFAULT_TYPE,
- float SWIG_DEFAULT_TYPE
-{
- static char *_wrap_$target;
- _wrap_$target = (char *) malloc(40);
- sprintf(_wrap_$target,"%f",$value);
- Tcl_LinkVar(interp,"$target", (char *) &_wrap_$target, TCL_LINK_STRING |
-TCL_LINK_READ_ONLY);
-}
-
-// Strings
-%typemap(const) char *SWIG_DEFAULT_TYPE
-{
- static char *_wrap_$target = "$value";
- Tcl_LinkVar(interp,"$target", (char *) &_wrap_$target, TCL_LINK_STRING |
-TCL_LINK_READ_ONLY);
-}
-
-// Pointers
-%typemap(const) User *SWIG_DEFAULT_TYPE
-{
- static char *_wrap_$target;
- _wrap_$target = (char *) malloc(20+strlen("$mangle"));
- SWIG_MakePtr(_wrap_$target, (void *) $value, "$mangle");
- Tcl_LinkVar(interp,"$target", (char *) &_wrap_$target, TCL_LINK_STRING |
-TCL_LINK_READ_ONLY);
-}
-
-</pre></blockquote>
-Now that we have our typemaps file, we are done and can start producing a variety of interesting Tcl extension modules. Should errors arrise, one will either have to pry into the C++ module or the typemaps file for a correction. <p>
-<a name="n42"></a><h3> The SWIG library and installation issues</h3>
-To make a new SWIG module generally usable, you will want to perform the following steps :<p>
-<p>
-<ul>
-<li>Put the new binary in a publicly accessible location (ie. <tt>/usr/local/bin</tt>).
-<li>Make a subdirectory for your language in the SWIG library. The library should match up with the name you assigned to the <tt>LibDir</tt> variable in <tt>parse_args()</tt>.
-<li>Copy the file `<tt>lang.map</tt>' to the SWIG library directory. Your new version of SWIG will now be able to find it no matter what directory SWIG is executed from.
-<li>Provide some documentation about how your module works.
-</ul>
-<p>
-SWIG extensions are only able to target a single scripting language. If you would like to make your module part of the full version of SWIG, you will need to modify the file `<tt>swigmain.cxx</tt>' in the <tt>SWIG1.1/Modules</tt> directory. To do this, follow these steps :<p>
-<p>
-<ul>
-<li>Add a <tt>#include "lang.h"</tt> to the<tt> swigmain.cxx</tt> file.
-<li>Create a command line option for your module and write code to create an instance of your language (just copy the technique used for the other languages).
-<li>Modify <tt>Modules/Makefile</tt> to include your module as part of its compilation process.
-<li>Rebuild SWIG by typing `make'.
-</ul>
-<a name="n11"></a><h2> C++ Processing</h2>
-Language modules have the option to provide special processing for C++ classes. Usually this is to provide some sort of object-oriented interface such as shadow classes. The process of developing these extensions is highly technical and the best approach may be to copy pieces from other SWIG modules that provide object oriented support.<p>
-<a name="n43"></a><h3> How C++ processing works</h3>
-The wrapping of C++ classes follows a "file" metaphor. When a class is encountered, the following steps are performed :<p>
-<p>
-<ul>
-<li>Open a new class.
-<li>Inherit from base classes.
-<li>Add members to the class (functions, variables, constants, etc...)
-<li>Close the class and emit object-oriented code.
-</ul>
-<p>
-As a class is constructed, a language module may need to keep track of a variety of data such as whether constructors or destructors have been given, are there any data members, have datatypes been renamed, and so on. It is not always a clear-cut process.<p>
-<a name="n44"></a><h3> Language extensions</h3>
-Providing additional support for object-oriented programming requires the use of the following Language extensions. These are additional methods that can be defined for the Language class.<p>
-<p>
-<h6> void cpp_open_class(char *name, char *rename, char *ctype, int strip);</h6>
-<dl>
-<dt><dd>Opens a new class. <tt>name</tt> is the name of the class, <tt>rename</tt> is the renamed version of the class (or NULL if not renamed), <tt>ctype</tt> is the class type (<tt>struct</tt>, <tt>class</tt>, <tt>union</tt>), and <tt>strip</tt> is a flag indicating whether or not its safe to drop the leading type specifier (this is often unsafe for ANSI C).
-<dt><dd>
-</dl>
-<h6> void cpp_inherit(char **baseclass, int mode = INHERIT_ALL);</h6>
-<dl>
-<dt><dd>Inherits from base classes. <tt>baseclass</tt> is a NULL terminated array of class names corresponding to all of the base classes of an object. <tt>mode</tt> is an inheritance mode that is the or'd value of <tt>INHERIT_FUNC</tt> , <tt>INHERIT_VAR</tt>, <tt>INHERIT_CONST</tt>, or <tt>INHERIT_ALL</tt>.
-<dt><dd>
-</dl>
-<h6> void cpp_member_func(char *name, char *iname, DataType *t, ParmList *l);</h6>
-<dl>
-<dt><dd>Creates a member function. <tt>name</tt> is the real name of the member, <tt>iname</tt> is the renamed version (NULL if not renamed), <tt>t</tt> is the return datatype, and <tt>l</tt> is the function parameter list.
-<dt><dd>
-</dl>
-<h6> void cpp_static_func(char *name, char *iname, DataType *t, ParmList *l);</h6>
-<dl>
-<dt><dd>Create a static member function. The calling conventions are the same as for <tt>cpp_member_func()</tt>.
-<dt><dd>
-</dl>
-<h6> void cpp_variable(char *name, char *iname, DataType *t);</h6>
-<dl>
-<dt><dd>Creates a member variable. <tt>name</tt> is the real name of the member, <tt>iname</tt> is the renamed version (NULL is not renamed). <tt>t</tt> is the type of the member.
-<dt><dd>
-</dl>
-<h6> void cpp_static_var(char *name, char *iname, DataType *t);</h6>
-<dl>
-<dt><dd>Creates a static member variable. The calling convention is the same as for <tt>cpp_variable()</tt>.
-<dt><dd>
-</dl>
-<h6> void cpp_declare_const(char *name, char *iname, DataType *type, char *value);</h6>
-<dl>
-<dt><dd>Creates a constant inside a C++ class. Normally this is an enum or member declared as const. <tt>name</tt> is the real name, <tt>iname</tt> is the renamed version (NULL if not renamed), <tt>type</tt> is the type of the constant, and <tt>value</tt> is a string containing the value.
-<dt><dd>
-</dl>
-<h6> void cpp_constructor(char *name, char *iname, ParmList *l);</h6>
-<dl>
-<dt><dd>Creates a constructor. <tt>name</tt> is the name of the constructor, <tt>iname</tt> is the renamed version, and <tt>l</tt> is the function parameter list. Normally, <tt>name</tt> is the same name as the class. If not, this may actually be a member function with no declared return type (assumed to be an int in C++).
-<dt><dd>
-</dl>
-<h6> void cpp_destructor(char *name, char *newname);</h6>
-<dl>
-<dt><dd>Creates a destructor. <tt>name</tt> is the real name of the destructor (usually the same name as the class), and <tt>newname</tt> is the renamed version (NULL if not renamed).
-<dt><dd>
-</dl>
-<h6> void cpp_close_class();</h6>
-<dl>
-<dt><dd>Closes the current class. Language modules should finish off code generation for a class once this has been called.
-<dt><dd>
-</dl>
-<h6> void cpp_cleanup();</h6>
-<dl>
-<dt><dd>Called after all C++ classes have been generated. Only used to provide some kind of global cleanup for all classes.
-</dl>
-<a name="n45"></a><h3> Hints</h3>
-Special C++ code generation is not for the weak of heart. Most of SWIG's built in modules have been developed for well over a year and object oriented support has been in continual development. If writing a new language module, looking at the implementation for Python, Tcl, or Perl5 would be a good start.<p>
-<a name="n12"></a><h2> Documentation Processing</h2>
-The documentation system operates (for the most part), independently of the language modules. However, language modules are still responsible for generating a "usage" string describing how each function, variable, or constant is to be used in the target language.<p>
-<a name="n46"></a><h3> Documentation entries</h3>
-Each C/C++ declaration in an interface file gets assigned to a "Documentation Entry" that is described by the <tt>DocEntry</tt> object :<p>
-<p>
-<blockquote><pre>class DocEntry {
-public:
- String usage; // Short description
- String cinfo; // Information about C interface (optional).
- String text; // Supporting text (optional)
-};
-
-</pre></blockquote>
-The <tt>usage</tt> string is used to hold the calling sequence for the function. The <tt>cinfo</tt> field is used to provide additional information about the underlying C code. <tt>text</tt> is filled in with comment text.<p>
-<p>
-The global variable <tt>doc_entry</tt> always contains the documentation entry for the current declaration being processed. Language modules can choose to update the documentation by referring to and modifying its fields.<p>
-<a name="n47"></a><h3> Creating a usage string</h3>
-To create a documentation usage string, language modules need to modify the `usage' field of <tt>doc_entry</tt>. This can be done by creating a function like this :<p>
-<p>
-<blockquote><pre>// ---------------------------------------------------------------------------
-// char *TCL::usage_string(char *iname, DataType *t, ParmList *l),
-//
-// Generates a generic usage string for a Tcl function.
-// ---------------------------------------------------------------------------
-
-char * TCL::usage_string(char *iname, DataType *, ParmList *l) {
-
- static String temp;
- Parm *p;
- int i, numopt,pcount;
-
- temp = "";
- temp << iname << " ";
-
- /* Now go through and print parameters */
- i = 0;
- pcount = l->nparms;
- numopt = l->numopt();
- p = l->get_first();
- while (p != 0) {
- if (!p->ignore) {
- if (i >= (pcount-numopt))
- temp << "?";
-
- /* If parameter has been named, use that. Otherwise, just print a type */
-
- if ((p->t->type != T_VOID) || (p->t->is_pointer)) {
- if (strlen(p->name) > 0) {
- temp << p->name;
- }
- else {
- temp << "{ " << p->t->print_type() << " }";
- }
- }
- if (i >= (pcount-numopt))
- temp << "?";
- temp << " ";
- i++;
- }
- p = l->get_next();
- }
- return temp;
-}
-</pre></blockquote>
-<p>
-Now, within the function to create a wrapper function, include code such as the following :<p>
-<p>
-<blockquote><pre>// Fill in the documentation entry
-doc_entry->usage << usage_string(iname,t,l);
-
-</pre></blockquote>
-To produce full documentation, each language module needs to fill in the documentation usage string for all declarations. Looking at existing SWIG modules can provide more information on how this should be implemented.<p>
-<a name="n48"></a><h3> Writing a new documentation module</h3>
-Writing a new documentation module is roughly the same idea as writing a new Language class. To do it, you need to implement a "Documentation Object" by inheriting from the following base class and defining all of the virtual methods :<p>
-<p>
-<blockquote><pre>class Documentation {
-public:
- virtual void parse_args(int argc, char **argv) = 0;
- virtual void title(DocEntry *de) = 0;
- virtual void newsection(DocEntry *de, int sectnum) = 0;
- virtual void endsection() = 0;
- virtual void print_decl(DocEntry *de) = 0;
- virtual void print_text(DocEntry *de) = 0;
- virtual void separator() = 0;
- virtual void init(char *filename) = 0;
- virtual void close(void) = 0;
- virtual void style(char *name, char *value) = 0;
-};
-
-
-</pre></blockquote>
-<h6> void parse_args(int argc, char **argv);</h6>
-<dl>
-<dt><dd>Parses command line options. Any special options you want to provide should be placed here.
-<dt><dd>
-</dl>
-<h6> void title(DocEntry *de;</h6>
-<dl>
-<dt><dd>Produces documentation output for a title.
-<dt><dd>
-</dl>
-<h6> void newsection(DocEntry *de, int sectnum;</h6>
-<dl>
-<dt><dd>Called whenever a new section is created. The documentation system is hierarchical in nature so each call to this function goes down one level in the hierarchy.
-<dt><dd>
-</dl>
-<h6> void endsection();</h6>
-<dl>
-<dt><dd>Ends the current section. Moves up one level in the documentation hierarchy.
-<dt><dd>
-</dl>
-<h6> void print_decl(DocEntry *de);</h6>
-<dl>
-<dt><dd>Creates documentation for a C declaration (function, variable, or constant).
-<dt><dd>
-</dl>
-<h6> void print_text(DocEntry *de);</h6>
-<dl>
-<dt><dd>Prints documentation that has been given with the <tt>%text %{ %}</tt> directive.
-<dt><dd>
-</dl>
-<h6> void separator();</h6>
-<dl>
-<dt><dd>Prints an optional separator between sections.
-<dt><dd>
-</dl>
-<h6> void init(char *filename);</h6>
-<dl>
-<dt><dd>Initializes the documentation system. This function is called after command line options have been parsed. <tt>filename</tt> is the file where documentation should be placed.
-<dt><dd>
-</dl>
-<h6> void close(void);</h6>
-<dl>
-<dt><dd>Closes the documentation file. All remaining output should be complete and files closed upon exit.
-<dt><dd>
-</dl>
-<h6> void style(char *name, char *value);</h6>
-<dl>
-<dt><dd>Called to set style parameters. This function is called by the <tt>%style</tt> and <tt>%localstyle</tt> directives. It is also called whenever style parameters are given after a section directive.
-</dl>
-<a name="n49"></a><h3> Using a new documentation module</h3>
-Using a new documentation module requires a change to SWIG's main program. If you are writing your own main() program, you can use a new documentation module as follows :<p>
-<p>
-<blockquote><pre>#include <swig.h>
-#include "swigtcl.h" // Language specific header
-#include "mydoc.h" // New Documentation module
-
-extern int SWIG_main(int, char **, Language *, Documentation *);
-int main(int argc, char **argv) {
-
- TCL *l = new TCL; // Create a new Language object
- MyDoc *d = new MyDoc; // New documentation object
- init_args(argc, argv); // Initialize args
- return SWIG_main(argc, argv, l, d);
-}
-</pre></blockquote>
-<a name="n50"></a><h3> Where to go for more information</h3>
-To find out more about documentation modules, look at some of the existing SWIG modules contained in the <tt>SWIG1.1/SWIG</tt> directory. The ASCII and HTML modules are good starting points for finding more information. <p>
-<a name="n13"></a><h2> The Future of SWIG</h2>
-SWIG's C++ API is the most rapidly evolving portion of SWIG. While interface-file compatibility will be maintained as much as possible in future releases, the internal structure of SWIG is likely to change significantly in the future. This will possibly have many ramifications on the construction of language modules. Here are a few significant changes that are coming :<p>
-<p>
-
-<dl>
-<dt>1. A complete reorganization of the SWIG type system. Datatypes will be represented in a more flexible manner that provide full support for arrays, function pointers, classes, structures, and types possibly coming from other languages (such as Fortran).
-<dt>2. Objectification of functions, variables, constants, classes, etc... Currently many of SWIG's functions take multiple arguments such as functions being described by name, return datatype, and parameters. These attributes will be consolidated into a single "Function" object, "Variable" object, "Constant" object, and so forth.
-<dt>3. A complete rewrite of the SWIG parser. This will be closely tied to the change in datatype representation among other things.
-<dt>4. Increased reliance on typemaps. Many of SWIG's older modules do not rely on typemaps, but this is likely to change. Typemaps provide a more concise implementation and are easier to maintain. Modules written for 1.1 that adopt typemaps now will be much easier to integrate into future releases.
-<dt>5. A possible reorganization of object-oriented code generation. The layered approach will probably remain in place however.
-<dt>6. Better support for multiple-files (exporting, importing, etc...)
-
-</dl>
-<p>
-In planning for the future, much of a language's functionality can be described in terms of typemaps. Sticking to this approach will make it significantly easier to move to new releases. I anticipate that there will be few drastic changes to the Language module presented in this section (other than changes to many of the calling mechanisms).<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:17 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Index.html b/swigweb/Doc1.1/HTML/Index.html
deleted file mode 100644
index b7662ea..0000000
--- a/swigweb/Doc1.1/HTML/Index.html
+++ /dev/null
@@ -1,559 +0,0 @@
-
-<html>
-<head>
-<title> SWIG 1.1 Users Manual - Topic Index </title>
-</head>
-<body bgcolor="#ffffff">
-
-<h1> Alphabetical Topic Index </h1>
-<h2> - A - </h2>
-<blockquote>
-
-<a href="Python.html#n53">A complete application</a> (9 SWIG and Python)<br>
-<a href="Advanced.html#n7">A few dynamic loading gotchas</a> (11 Advanced Topics)<br>
-<a href="Tcl.html#n49">A few helper functions</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n10">A general interface building strategy</a> (3 SWIG Basics)<br>
-<a href="Python.html#n46">A mathematical function plotter</a> (9 SWIG and Python)<br>
-<a href="Extending.html#n40">A Quick Intermission</a> (12 Extending SWIG)<br>
-<a href="Python.html#n29">A simple example</a> (9 SWIG and Python)<br>
-<a href="Typemaps.html#n16">A simple example</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Perl5.html#n5">A simple Perl example</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n67">A simple shadow class</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n31">A simple SWIG interface file</a> (8 SWIG and Perl5)<br>
-<a href="Perl5.html#n37">A simple typemap example</a> (8 SWIG and Perl5)<br>
-<a href="Introduction.html#n5">A SWIG example</a> (1 Introduction)<br>
-<a href="Extending.html#n5">A tour of SWIG datatypes</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n30">A Typemap Implementation</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n5">About the examples</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n5">About the Examples</a> (9 SWIG and Python)<br>
-<a href="Preface.html#n3">About this manual</a> (Preface)<br>
-<a href="Python.html#n37">Accessing array data</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n43">Accessing array structure members</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n62">Accessing array structure members</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n8">Accessing arrays</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n6">Accessing arrays and other strange objects</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n36">Accessing member data</a> (10 SWIG and Tcl)<br>
-<a href="Documentation.html#n7">Adding Additional Text</a> (5 Documentation System)<br>
-<a href="SWIG.html#n40">Adding member functions to C structures</a> (3 SWIG Basics)<br>
-<a href="Python.html#n66">Adding native Python functions to a SWIG module</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n55">Adding new methods</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n71">Adding new methods</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n17">Additional SWIG options</a> (10 SWIG and Tcl)<br>
-<a href="Documentation.html#n9">An Example</a> (5 Documentation System)<br>
-<a href="Tcl.html#n50">An OpenGL package</a> (10 SWIG and Tcl)<br>
-<a href="Typemaps.html#n5">Applying constraints to input values</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n27">Applying constraints to new datatypes</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Exceptions.html#n9">Applying exception handlers to specific datatypes.</a> (7 Exception Handling)<br>
-<a href="SWIG.html#n38">Array members</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n30">Arrays</a> (3 SWIG Basics)<br>
-<a href="Documentation.html#n10">ASCII Documentation</a> (5 Documentation System)<br>
-<a href="Python.html#n31">Automated shadow class generation</a> (9 SWIG and Python)<br>
-<a href="Introduction.html#n10">Automatic documentation generation</a> (1 Introduction)<br></blockquote>
-<h2> - B - </h2>
-<blockquote>
-
-<a href="Perl5.html#n4">Basic Perl interface</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n3">Basic Tcl Interface</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n6">Binary trees in Tcl</a> (10 SWIG and Tcl)<br>
-<a href="Preface.html#n6">Bug reports</a> (Preface)<br>
-<a href="Tcl.html#n42">Building a C data structure in Tcl</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n20">Building a dynamic module with MakeMaker</a> (8 SWIG and Perl5)<br>
-<a href="Perl5.html#n11">Building a Perl5 interface to MATLAB</a> (8 SWIG and Perl5)<br>
-<a href="Introduction.html#n15">Building a Perl5 module</a> (1 Introduction)<br>
-<a href="Introduction.html#n16">Building a Python module</a> (1 Introduction)<br>
-<a href="Python.html#n45">Building a simple 2D imaging class</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n9">Building a simple OpenGL module</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n21">Building a static version of Perl</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n44">Building an object oriented C interface</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n7">Building C/C++ data structures with Tk</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n52">Building large multi-module systems</a> (9 SWIG and Python)<br>
-<a href="Introduction.html#n19">Building libraries and modules</a> (1 Introduction)<br>
-<a href="Tcl.html#n13">Building new kinds of Tcl interfaces (in Tcl)</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n2">Building Perl Extensions under Windows 95/NT</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n2">Building Python Extensions under Windows 95/NT</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n3">Building scripting language extensions</a> (2 Scripting Languages)<br>
-<a href="Tcl.html#n2">Building Tcl/Tk Extensions under Windows 95/NT</a> (10 SWIG and Tcl)<br></blockquote>
-<h2> - C - </h2>
-<blockquote>
-
-<a href="SWIG.html#n39">C constructors and destructors</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n40">C files</a> (10 SWIG and Tcl)<br>
-<a href="Documentation.html#n21">C Information</a> (5 Documentation System)<br>
-<a href="SWIG.html#n14">C Preprocessor directives</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n6">C syntax, but not a C compiler</a> (1 Introduction)<br>
-<a href="Tcl.html#n32">C++ Classes</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n28">C++ Classes</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n44">C++ example</a> (3 SWIG Basics)<br>
-<a href="Extending.html#n11">C++ Processing</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n6">C++ support</a> (3 SWIG Basics)<br>
-<a href="Documentation.html#n13">C++ Support</a> (5 Documentation System)<br>
-<a href="SWIG.html#n68">Categories</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n37">Changing member data</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n19">Character Strings</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n37">Character strings and structures</a> (3 SWIG Basics)<br>
-<a href="Library.html#n17">Checking in library files</a> (4 Multiple files and the SWIG library)<br>
-<a href="Library.html#n15">Checking out library files</a> (4 Multiple files and the SWIG library)<br>
-<a href="Documentation.html#n3">Choosing a documentation format</a> (5 Documentation System)<br>
-<a href="SWIG.html#n62">Class methods</a> (3 SWIG Basics)<br>
-<a href="Extending.html#n35">Cleanup</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n77">Code blocks</a> (3 SWIG Basics)<br>
-<a href="Extending.html#n9">Code Generation Functions</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n9">Code Insertion</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n66">Combining Tcl/Tk Extensions</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n30">Command Line Options and Basic Initialization</a> (12 Extending SWIG)<br>
-<a href="Documentation.html#n16">Comment Formatting variables</a> (5 Documentation System)<br>
-<a href="Documentation.html#n18">Comment placement and formatting</a> (5 Documentation System)<br>
-<a href="SWIG.html#n13">Comments</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n7">Common typemap methods</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n22">Compilation problems</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n22">Compilation problems and compiling with C++</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n19">Compilation problems and compiling with C++</a> (9 SWIG and Python)<br>
-<a href="Extending.html#n20">Compiling</a> (12 Extending SWIG)<br>
-<a href="Perl5.html#n19">Compiling a dynamic module</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n16">Compiling a dynamic module</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n19">Compiling a dynamic module (Unix)</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n2">Compiling a SWIG extension</a> (12 Extending SWIG)<br>
-<a href="Python.html#n32">Compiling modules with shadow classes</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n8">Conditional compilation</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n12">Configuration management with SWIG</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n39">Constants</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n21">Constants</a> (3 SWIG Basics)<br>
-<a href="Python.html#n25">Constants</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n9">Constants</a> (2 Scripting Languages)<br>
-<a href="Tcl.html#n29">Constants</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n27">Constants</a> (8 SWIG and Perl5)<br>
-<a href="Typemaps.html#n26">Constraint methods</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="SWIG.html#n60">Constructors and destructors</a> (3 SWIG Basics)<br>
-<a href="Python.html#n72">Constructors and Destructors</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n45">Constructors and destructors</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n57">Converting a Tcl list to a char **</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n58">Converting Python list to a char **</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n41">Converting a Perl5 array to a char **</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n59">Converting a Python file object to a FILE *</a> (9 SWIG and Python)<br>
-<a href="Typemaps.html#n34">Copying a typemap</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n65">Creating a new package initialization library</a> (10 SWIG and Tcl)<br>
-<a href="Typemaps.html#n32">Creating a new typemap</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n47">Creating a usage string</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n37">Creating a Wrapper Function</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n17">Creating arrays</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n36">Creating Commands</a> (12 Extending SWIG)<br>
-<a href="Library.html#n7">Creating Library Files</a> (4 Multiple files and the SWIG library)<br>
-<a href="Typemaps.html#n37">Creating local variables</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Advanced.html#n1">Creating multi-module packages</a> (11 Advanced Topics)<br>
-<a href="Tcl.html#n33">Creating new objects</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n31">Creating read-only variables</a> (3 SWIG Basics)<br>
-<a href="Preface.html#n4">Credits</a> (Preface)<br>
-<a href="Introduction.html#n22">Cross platform woes</a> (1 Introduction)<br></blockquote>
-<h2> - D - </h2>
-<blockquote>
-
-<a href="Exceptions.html#n7">Debugging and other interesting uses for %except</a> (7 Exception Handling)<br>
-<a href="Documentation.html#n15">Default Formatting</a> (5 Documentation System)<br>
-<a href="SWIG.html#n34">Default/optional arguments</a> (3 SWIG Basics)<br>
-<a href="Exceptions.html#n5">Defining different exception handlers</a> (7 Exception Handling)<br>
-<a href="SWIG.html#n73">Defining symbols</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n33">Deleting a typemap</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n35">Deleting objects</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n24">Derived types, structs, and classes</a> (3 SWIG Basics)<br>
-<a href="Documentation.html#n8">Disabling all documentation</a> (5 Documentation System)<br>
-<a href="Extending.html#n46">Documentation entries</a> (12 Extending SWIG)<br>
-<a href="Introduction.html#n18">Documentation generation</a> (1 Introduction)<br>
-<a href="Extending.html#n12">Documentation Processing</a> (12 Extending SWIG)<br>
-<a href="Tcl.html#n68">Dynamic loading</a> (10 SWIG and Tcl)<br>
-<a href="Advanced.html#n2">Dynamic Loading of C++ modules</a> (11 Advanced Topics)<br></blockquote>
-<h2> - E - </h2>
-<blockquote>
-
-<a href="Extending.html#n32">Emitting headers and support code</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n50">Enums and constants</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n9">Event driven C programming</a> (1 Introduction)<br>
-<a href="Python.html#n9">Exception handling</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n13">Exception handling</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n10">Exception handling</a> (10 SWIG and Tcl)<br>
-<a href="Exceptions.html#n3">Exception handling with longjmp()</a> (7 Exception Handling)<br>
-<a href="Python.html#n44">Extending and fixing the gd module</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n14">Extending the Tcl Netscape Plugin</a> (10 SWIG and Tcl)<br></blockquote>
-<h2> - F - </h2>
-<blockquote>
-
-<a href="Extending.html#n7">File management</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n34">Final Initialization</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n18">Floating Point</a> (3 SWIG Basics)<br>
-<a href="Documentation.html#n6">Formatting</a> (5 Documentation System)<br>
-<a href="Python.html#n48">From C to SWIG to Python</a> (9 SWIG and Python)<br>
-<a href="Extending.html#n22">Function Parameters</a> (12 Extending SWIG)<br>
-<a href="Documentation.html#n4">Function usage and argument names</a> (5 Documentation System)<br>
-<a href="Tcl.html#n27">Functions</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n23">Functions</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n25">Functions</a> (8 SWIG and Perl5)<br></blockquote>
-<h2> - G - </h2>
-<blockquote>
-
-<a href="SWIG.html#n4">Getting down to business</a> (3 SWIG Basics)<br>
-<a href="Python.html#n39">Getting even more serious about array access</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n9">Getting serious</a> (8 SWIG and Perl5)<br>
-<a href="Perl5.html#n18">Getting the right header files</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n15">Getting the right header files</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n84">Getting the right header files</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n18">Getting the right header files and libraries</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n28">Global variables</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n26">Global variables</a> (8 SWIG and Perl5)<br>
-<a href="Perl5.html#n36">Graphical Web-Statistics in Perl5</a> (8 SWIG and Perl5)<br>
-<a href="Perl5.html#n30">Graphs</a> (8 SWIG and Perl5)<br></blockquote>
-<h2> - H - </h2>
-<blockquote>
-
-<a href="Exceptions.html#n4">Handling C++ exceptions</a> (7 Exception Handling)<br>
-<a href="Exceptions.html#n2">Handling exceptions in C code</a> (7 Exception Handling)<br>
-<a href="Perl5.html#n12">Handling output values (the easy way)</a> (8 SWIG and Perl5)<br>
-<a href="Introduction.html#n8">Hands off code generation</a> (1 Introduction)<br>
-<a href="Extending.html#n24">Hash Tables</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n45">Hints</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n43">How C++ processing works</a> (12 Extending SWIG)<br>
-<a href="Scripting.html#n2">How does a scripting language talk to C?</a> (2 Scripting Languages)<br>
-<a href="Documentation.html#n2">How it works</a> (5 Documentation System)<br>
-<a href="Extending.html#n28">How many typemaps are there?</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n88">How to avoid creating the interface from hell</a> (3 SWIG Basics)<br>
-<a href="Preface.html#n10">How to avoid reading the manual</a> (Preface)<br>
-<a href="Typemaps.html#n13">How to break everything with a typemap</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="SWIG.html#n87">How to cope with C++</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n23">How to survive this manual</a> (1 Introduction)<br>
-<a href="Documentation.html#n11">HTML Documentation</a> (5 Documentation System)<br></blockquote>
-<h2> - I - </h2>
-<blockquote>
-
-<a href="Documentation.html#n20">Ignoring comments</a> (5 Documentation System)<br>
-<a href="SWIG.html#n69">Implementations and Protocols</a> (3 SWIG Basics)<br>
-<a href="Python.html#n11">Implementing C callback functions in Python</a> (9 SWIG and Python)<br>
-<a href="Typemaps.html#n11">Implementing constraints with typemaps</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n43">Implementing methods in C</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n7">Implementing methods in Perl</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n40">Implementing special Python methods in C</a> (9 SWIG and Python)<br>
-<a href="Library.html#n4">Including files on the command line</a> (4 Multiple files and the SWIG library)<br>
-<a href="Perl5.html#n54">Inheritance</a> (8 SWIG and Perl5)<br>
-<a href="SWIG.html#n52">Inheritance</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n66">Inheritance</a> (3 SWIG Basics)<br>
-<a href="Python.html#n77">Inheritance and shadow classes</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n79">Initialization blocks</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n78">Inlined code blocks</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n11">Input format</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n21">Input Methods</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n23">Input/Output Methods</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Advanced.html#n3">Inside the SWIG type-checker</a> (11 Advanced Topics)<br>
-<a href="SWIG.html#n61">Instance methods</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n17">Integers</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n1">Introduction</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Documentation.html#n1">Introduction</a> (5 Documentation System)<br>
-<a href="Preface.html#n1">Introduction</a> (Preface)<br>
-<a href="Extending.html#n1">Introduction</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n3">Introduction to typemaps</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Tcl.html#n34">Invoking member functions</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n55">Iterators</a> (8 SWIG and Perl5)<br></blockquote>
-<h2> - L - </h2>
-<blockquote>
-
-<a href="Extending.html#n44">Language extensions</a> (12 Extending SWIG)<br>
-<a href="Documentation.html#n12">LaTeX Documentation</a> (5 Documentation System)<br>
-<a href="Library.html#n6">Library example</a> (4 Multiple files and the SWIG library)<br>
-<a href="Introduction.html#n3">Life after SWIG</a> (1 Introduction)<br>
-<a href="Introduction.html#n2">Life before SWIG</a> (1 Introduction)<br>
-<a href="SWIG.html#n16">Limitations in the Parser (and various things to keep in mind)</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n67">Limitations to this approach</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n29">Linking to complex variables</a> (3 SWIG Basics)<br>
-<a href="Scripting.html#n13">Linking with shared libraries</a> (2 Scripting Languages)<br></blockquote>
-<h2> - M - </h2>
-<blockquote>
-
-<a href="Tcl.html#n41">Making a quick a dirty Tcl module</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n35">Making a quick and dirty Python module</a> (9 SWIG and Python)<br>
-<a href="Library.html#n12">malloc.i</a> (4 Multiple files and the SWIG library)<br>
-<a href="Typemaps.html#n4">Managing input and output parameters</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n29">Managing special data-types with helper functions</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n38">Manipulating Global Variables</a> (12 Extending SWIG)<br>
-<a href="Tcl.html#n60">Mapping C structures into Tcl Lists</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n61">Mapping Python tuples into small arrays</a> (9 SWIG and Python)<br>
-<a href="Python.html#n73">Member data</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n48">Member data</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n63">Member data</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n46">Member functions</a> (3 SWIG Basics)<br>
-<a href="Python.html#n49">Merging modules</a> (9 SWIG and Python)<br>
-<a href="Python.html#n78">Methods that return new objects</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n49">Module and package names</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n68">Module names</a> (9 SWIG and Python)<br>
-<a href="Python.html#n22">Modules</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n3">Modules, packages, and classes</a> (8 SWIG and Perl5)<br>
-<a href="Library.html#n10">More about the SWIG library</a> (4 Multiple files and the SWIG library)<br>
-<a href="Exceptions.html#n8">More Examples</a> (7 Exception Handling)<br>
-<a href="Typemaps.html#n28">Motivations for using typemaps</a> (6 Pointers, Constraints, and Typemaps)<br></blockquote>
-<h2> - N - </h2>
-<blockquote>
-
-<a href="Tcl.html#n56">Name based type conversion</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n57">Name based type conversion</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n40">Name based type conversion</a> (8 SWIG and Perl5)<br>
-<a href="Extending.html#n8">Naming Services</a> (12 Extending SWIG)<br>
-<a href="Python.html#n76">Nested objects</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n52">Nested Objects</a> (8 SWIG and Perl5)<br>
-<a href="SWIG.html#n41">Nested structures</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n7">Non-intrusive interface building</a> (1 Introduction)<br></blockquote>
-<h2> - O - </h2>
-<blockquote>
-
-<a href="Perl5.html#n51">Object Ownership</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n71">Object ownership</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n7">Objective-C</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n59">Objective-C Example</a> (3 SWIG Basics)<br>
-<a href="Preface.html#n9">Organization of this manual</a> (Preface)<br>
-<a href="SWIG.html#n72">Other issues</a> (3 SWIG Basics)<br>
-<a href="Python.html#n12">Other odds and ends</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n42">Other things to note about structures</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n22">Output Methods</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="SWIG.html#n33">Overriding call by reference</a> (3 SWIG Basics)<br></blockquote>
-<h2> - P - </h2>
-<blockquote>
-
-<a href="Typemaps.html#n18">Packing a data structure</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="SWIG.html#n56">Partial class definitions</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n27">Passing complex datatypes by value</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n39">Performance concerns and disabling the object oriented interface</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n79">Performance concerns and hints</a> (9 SWIG and Python)<br>
-<a href="Advanced.html#n11">Performance of the type-checker</a> (11 Advanced Topics)<br>
-<a href="Perl5.html#n38">Perl5 typemaps</a> (8 SWIG and Perl5)<br>
-<a href="Library.html#n13">Placing the files in the library</a> (4 Multiple files and the SWIG library)<br>
-<a href="Python.html#n47">Plotting an unstructured mesh</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n47">Pointer handling</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n63">Pointer handling</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n65">Pointer handling</a> (9 SWIG and Python)<br>
-<a href="Typemaps.html#n15">Pointer Library Functions</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Perl5.html#n28">Pointers</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n30">Pointers</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n26">Pointers</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n3">Pointers and complex objects</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n35">Pointers to functions</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n75">Predefined Symbols</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n1">Preliminaries</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n1">Preliminaries</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n1">Preliminaries</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n81">Preparing a C program for SWIG</a> (3 SWIG Basics)<br>
-<a href="Python.html#n42">Preparing a module</a> (9 SWIG and Python)<br>
-<a href="Preface.html#n8">Prerequisites</a> (Preface)<br>
-<a href="Extending.html#n14">Prerequisites</a> (12 Extending SWIG)<br>
-<a href="Python.html#n74">Printing</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n52">Problems with the OpenGL interface</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n49">Protection</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n64">Protection</a> (3 SWIG Basics)<br>
-<a href="Python.html#n8">Putting it all together</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n35">Putting it all together</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n4">Python shadow classes</a> (9 SWIG and Python)<br>
-<a href="Python.html#n55">Python typemaps</a> (9 SWIG and Python)<br></blockquote>
-<h2> - R - </h2>
-<blockquote>
-
-<a href="Python.html#n17">Rebuilding the Python interpreter (aka. static linking)</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n51">References</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n67">Referring to other classes</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n38">Relationship with pointers</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n10">Remapping C datatypes with typemaps</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n58">Remapping constants</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n14">Remapping datatypes with typemaps</a> (8 SWIG and Perl5)<br>
-<a href="SWIG.html#n70">Renaming</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n54">Renaming</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n32">Renaming declarations</a> (3 SWIG Basics)<br>
-<a href="Extending.html#n18">Required C++ compiler</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n17">Required files</a> (12 Extending SWIG)<br>
-<a href="Tcl.html#n45">Required files</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n28">Return by value</a> (3 SWIG Basics)<br>
-<a href="Perl5.html#n48">Return values</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n59">Returning values in arguments</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n23">Run time pointer type checking</a> (3 SWIG Basics)<br>
-<a href="Perl5.html#n17">Running SWIG</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n14">Running SWIG</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n1">Running SWIG</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n16">Running SWIG</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n25">Running SWIG from Developer Studio</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n20">Running SWIG from Developer Studio</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n23">Running SWIG from Developer Studio</a> (8 SWIG and Perl5)<br>
-<a href="Advanced.html#n4">Runtime support (and potential problems)</a> (11 Advanced Topics)<br></blockquote>
-<h2> - S - </h2>
-<blockquote>
-
-<a href="Perl5.html#n32">Sample Perl Script</a> (8 SWIG and Perl5)<br>
-<a href="Typemaps.html#n36">Scope</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n33">Setting a module name</a> (12 Extending SWIG)<br>
-<a href="Tcl.html#n23">Setting a package prefix</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n8">Shadow classes</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n70">Shadow classes</a> (10 SWIG and Tcl)<br>
-<a href="Scripting.html#n11">Shadow classes</a> (2 Scripting Languages)<br>
-<a href="Perl5.html#n53">Shadow Functions</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n75">Shadow Functions</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n4">Shared libraries and dynamic loading</a> (2 Scripting Languages)<br>
-<a href="Introduction.html#n17">Shortcuts</a> (1 Introduction)<br>
-<a href="SWIG.html#n2">Simple C functions, variables, and constants</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n25">Simple constraint example</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="SWIG.html#n22">Simple pointers</a> (3 SWIG Basics)<br>
-<a href="Python.html#n6">Solving a simple heat-equation</a> (9 SWIG and Python)<br>
-<a href="Documentation.html#n17">Sorting</a> (5 Documentation System)<br>
-<a href="Typemaps.html#n38">Special variables</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Python.html#n64">Standard typemaps</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n62">Standard typemaps</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n46">Standard typemaps</a> (8 SWIG and Perl5)<br>
-<a href="Extending.html#n31">Starting the parser</a> (12 Extending SWIG)<br>
-<a href="Library.html#n9">Static initialization of multiple modules</a> (4 Multiple files and the SWIG library)<br>
-<a href="Scripting.html#n12">Static linking</a> (2 Scripting Languages)<br>
-<a href="Tcl.html#n21">Static linking</a> (10 SWIG and Tcl)<br>
-<a href="SWIG.html#n47">Static members</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n31">Structures</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n27">Structures</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n29">Structures and C++ classes</a> (8 SWIG and Perl5)<br>
-<a href="Scripting.html#n10">Structures and classes</a> (2 Scripting Languages)<br>
-<a href="SWIG.html#n5">Structures, unions, and object oriented C programming</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n11">Summary</a> (1 Introduction)<br>
-<a href="Python.html#n41">Summary (so far)</a> (9 SWIG and Python)<br>
-<a href="SWIG.html#n43">Supported C++ features</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n15">SWIG Directives</a> (3 SWIG Basics)<br>
-<a href="Introduction.html#n12">SWIG for Windows and Macintosh</a> (1 Introduction)<br>
-<a href="Introduction.html#n13">SWIG interface file</a> (1 Introduction)<br>
-<a href="Preface.html#n7">SWIG is free</a> (Preface)<br>
-<a href="Introduction.html#n21">SWIG on the Power Macintosh</a> (1 Introduction)<br>
-<a href="Introduction.html#n20">SWIG on Windows 95/NT</a> (1 Introduction)<br>
-<a href="Extending.html#n15">SWIG Organization</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n3">SWIG output</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n12">SWIG Output</a> (3 SWIG Basics)<br>
-<a href="Preface.html#n2">SWIG resources</a> (Preface)<br>
-<a href="SWIG.html#n57">SWIG, C++, and the Legislation of Morality</a> (3 SWIG Basics)<br></blockquote>
-<h2> - T - </h2>
-<blockquote>
-
-<a href="Documentation.html#n19">Tabs and other annoyances</a> (5 Documentation System)<br>
-<a href="Tcl.html#n54">Tcl typemaps</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n15">Tcl8.0 features</a> (10 SWIG and Tcl)<br>
-<a href="Library.html#n11">tclsh.i</a> (4 Multiple files and the SWIG library)<br>
-<a href="SWIG.html#n53">Templates</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n74">The #if directive</a> (3 SWIG Basics)<br>
-<a href="Exceptions.html#n1">The %except directive</a> (7 Exception Handling)<br>
-<a href="Library.html#n2">The %extern directive</a> (4 Multiple files and the SWIG library)<br>
-<a href="Library.html#n3">The %import directive</a> (4 Multiple files and the SWIG library)<br>
-<a href="Library.html#n1">The %include directive</a> (4 Multiple files and the SWIG library)<br>
-<a href="Python.html#n34">The C++ code</a> (9 SWIG and Python)<br>
-<a href="Extending.html#n21">The DataType class</a> (12 Extending SWIG)<br>
-<a href="Documentation.html#n14">The Final Word?</a> (5 Documentation System)<br>
-<a href="SWIG.html#n58">The future of C++ and SWIG</a> (3 SWIG Basics)<br>
-<a href="Extending.html#n13">The Future of SWIG</a> (12 Extending SWIG)<br>
-<a href="Python.html#n13">The gory details of shadow classes</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n15">The gory details on shadow classes</a> (8 SWIG and Perl5)<br>
-<a href="Extending.html#n29">The header file</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n19">The idea (in a nutshell)</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n4">The Language class (simple version)</a> (12 Extending SWIG)<br>
-<a href="Python.html#n3">The low-level Python/C interface</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n33">The MATLAB engine interface</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n4">The object oriented interface</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n16">The organization of this chapter</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n76">The output of SWIG</a> (3 SWIG Basics)<br>
-<a href="Tcl.html#n71">The step-by-step process for making a plugin extension.</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n23">The String Class</a> (12 Extending SWIG)<br>
-<a href="Introduction.html#n14">The swig command</a> (1 Introduction)<br>
-<a href="SWIG.html#n82">The SWIG interface file</a> (3 SWIG Basics)<br>
-<a href="Library.html#n5">The SWIG library</a> (4 Multiple files and the SWIG library)<br>
-<a href="Extending.html#n42">The SWIG library and installation issues</a> (12 Extending SWIG)<br>
-<a href="Introduction.html#n4">The SWIG package</a> (1 Introduction)<br>
-<a href="Typemaps.html#n2">The SWIG Pointer Library</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Advanced.html#n6">The SWIG runtime library</a> (11 Advanced Topics)<br>
-<a href="Python.html#n70">The this pointer</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n1">The two language view of the world</a> (2 Scripting Languages)<br>
-<a href="Extending.html#n26">The typemap C API.</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n65">The use of id</a> (3 SWIG Basics)<br>
-<a href="Library.html#n16">The world's fastest way to write a Makefile</a> (4 Multiple files and the SWIG library)<br>
-<a href="Extending.html#n25">The WrapperFunction class</a> (12 Extending SWIG)<br>
-<a href="Documentation.html#n5">Titles, sections, and subsections</a> (5 Documentation System)<br>
-<a href="Tcl.html#n69">Turning a SWIG module into a Tcl Package.</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n44">Turning Perl references into C pointers</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n69">Two classes</a> (9 SWIG and Python)<br>
-<a href="Advanced.html#n9">Type casting</a> (11 Advanced Topics)<br>
-<a href="Advanced.html#n8">Type equivalence</a> (11 Advanced Topics)<br>
-<a href="SWIG.html#n26">Typedef</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n36">Typedef and structures</a> (3 SWIG Basics)<br>
-<a href="Typemaps.html#n12">Typemap examples</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n35">Typemap matching rules</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Perl5.html#n39">Typemap variables</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n56">Typemap variables</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n55">Typemap variables</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n11">Typemaps</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n6">Typemaps (from C)</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n14">Typemaps and the future</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n10">Typemaps and the SWIG Library</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Typemaps.html#n9">Typemaps for handling arrays</a> (6 Pointers, Constraints, and Typemaps)<br></blockquote>
-<h2> - U - </h2>
-<blockquote>
-
-<a href="Python.html#n38">Use Python for control, C for performance</a> (9 SWIG and Python)<br>
-<a href="Python.html#n51">Use static linking</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n61">Useful functions</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n45">Useful functions</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n63">Useful Functions</a> (9 SWIG and Python)<br>
-<a href="Python.html#n36">Using our new module</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n20">Using a dynamic module</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n49">Using a new documentation module</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n24">Using different names</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Python.html#n50">Using dynamic loading</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n24">Using NMAKE</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n26">Using NMAKE</a> (10 SWIG and Tcl)<br>
-<a href="Python.html#n21">Using NMAKE</a> (9 SWIG and Python)<br>
-<a href="Typemaps.html#n20">Using some typemaps</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Python.html#n43">Using the gd module</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n51">Using the OpenGL module</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n72">Using the plugin</a> (10 SWIG and Tcl)<br>
-<a href="Exceptions.html#n6">Using The SWIG exception library</a> (7 Exception Handling)<br>
-<a href="Python.html#n60">Using typemaps to return arguments</a> (9 SWIG and Python)<br>
-<a href="Perl5.html#n42">Using typemaps to return values</a> (8 SWIG and Perl5)<br>
-<a href="Python.html#n18">Using your module</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n24">Using [incr Tcl] namespaces</a> (10 SWIG and Tcl)<br></blockquote>
-<h2> - V - </h2>
-<blockquote>
-
-<a href="Python.html#n24">Variable Linking</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n8">Variable linking</a> (2 Scripting Languages)<br>
-<a href="SWIG.html#n20">Variables</a> (3 SWIG Basics)<br></blockquote>
-<h2> - W - </h2>
-<blockquote>
-
-<a href="Perl5.html#n50">What gets created?</a> (8 SWIG and Perl5)<br>
-<a href="Extending.html#n27">What happens on typemap lookup?</a> (12 Extending SWIG)<br>
-<a href="SWIG.html#n25">What happens when SWIG encounters an unknown datatype?</a> (3 SWIG Basics)<br>
-<a href="Python.html#n54">What is a typemap?</a> (9 SWIG and Python)<br>
-<a href="Tcl.html#n53">What is a typemap?</a> (10 SWIG and Tcl)<br>
-<a href="Typemaps.html#n31">What is a typemap?</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Introduction.html#n1">What is SWIG?</a> (1 Introduction)<br>
-<a href="SWIG.html#n85">What to do with main()</a> (3 SWIG Basics)<br>
-<a href="Preface.html#n5">What's new?</a> (Preface)<br>
-<a href="Python.html#n33">Where to go for more information</a> (9 SWIG and Python)<br>
-<a href="Extending.html#n50">Where to go for more information</a> (12 Extending SWIG)<br>
-<a href="Perl5.html#n16">Where to go from here?</a> (8 SWIG and Perl5)<br>
-<a href="Advanced.html#n10">Why a name based approach?</a> (11 Advanced Topics)<br>
-<a href="Advanced.html#n5">Why doesn't C++ inheritance work between modules?</a> (11 Advanced Topics)<br>
-<a href="SWIG.html#n83">Why use separate interface files?</a> (3 SWIG Basics)<br>
-<a href="Python.html#n30">Why write shadow classes in Python?</a> (9 SWIG and Python)<br>
-<a href="Scripting.html#n6">Will adding a scripting language to my C program make it unmanagable?</a> (2 Scripting Languages)<br>
-<a href="Scripting.html#n5">Will scripting languages make my C program inefficient?</a> (2 Scripting Languages)<br>
-<a href="Library.html#n8">Working with library files</a> (4 Multiple files and the SWIG library)<br>
-<a href="SWIG.html#n86">Working with the C preprocessor</a> (3 SWIG Basics)<br>
-<a href="SWIG.html#n80">Wrapper code blocks</a> (3 SWIG Basics)<br>
-<a href="Scripting.html#n7">Wrapper functions</a> (2 Scripting Languages)<br>
-<a href="Python.html#n7">Wrapping a C library</a> (9 SWIG and Python)<br>
-<a href="Library.html#n14">Wrapping a library file</a> (4 Multiple files and the SWIG library)<br>
-<a href="Perl5.html#n10">Wrapping C libraries and other packages</a> (8 SWIG and Perl5)<br>
-<a href="Tcl.html#n46">Wrapping gl.h</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n47">Wrapping glu.h</a> (10 SWIG and Tcl)<br>
-<a href="Tcl.html#n48">Wrapping the aux library</a> (10 SWIG and Tcl)<br>
-<a href="Perl5.html#n34">Wrapping the MATLAB matrix functions</a> (8 SWIG and Perl5)<br>
-<a href="Extending.html#n19">Writing a main program</a> (12 Extending SWIG)<br>
-<a href="Tcl.html#n64">Writing a main program and Tcl_AppInit()</a> (10 SWIG and Tcl)<br>
-<a href="Extending.html#n48">Writing a new documentation module</a> (12 Extending SWIG)<br>
-<a href="Extending.html#n10">Writing a Real Language Module</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n6">Writing new typemaps</a> (6 Pointers, Constraints, and Typemaps)<br>
-<a href="Extending.html#n41">Writing the default typemaps</a> (12 Extending SWIG)<br>
-<a href="Typemaps.html#n8">Writing typemap code</a> (6 Pointers, Constraints, and Typemaps)<br></blockquote>
-
-<p><hr>
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:18 1997 </address>
-</body>
-</html>
\ No newline at end of file
diff --git a/swigweb/Doc1.1/HTML/Introduction.html b/swigweb/Doc1.1/HTML/Introduction.html
deleted file mode 100644
index 98cfce9..0000000
--- a/swigweb/Doc1.1/HTML/Introduction.html
+++ /dev/null
@@ -1,323 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Introduction</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>1 Introduction</h1><p><ul>
-<li> <a href="#n1">What is SWIG?</a>
-<li> <a href="#n2">Life before SWIG</a>
-<li> <a href="#n3">Life after SWIG</a>
-<li> <a href="#n4">The SWIG package</a>
-<li> <a href="#n5">A SWIG example</a>
-<li> <a href="#n6">C syntax, but not a C compiler</a>
-<li> <a href="#n7">Non-intrusive interface building</a>
-<li> <a href="#n8">Hands off code generation</a>
-<li> <a href="#n9">Event driven C programming</a>
-<li> <a href="#n10">Automatic documentation generation</a>
-<li> <a href="#n11">Summary</a>
-<li> <a href="#n12">SWIG for Windows and Macintosh</a>
-</ul>
-
-<a name="n1"></a><h2> What is SWIG?</h2>
-SWIG is a code development tool that makes it possible to quickly build powerful scripting language interfaces to C, C++, or Objective-C programs. In a nutshell, SWIG is a compiler that takes C declarations and turns them into the "glue" needed to access them from common scripting languages including Perl, Python, and Tcl. SWIG usually requires no modifications to existing C code and can often be used to build a working interface in a matter of minutes. This makes it possible to do a number of interesting things including :<p>
-<p>
-<ul>
-<li>Building powerful interfaces to existing C programs.
-<li>Rapid prototyping and application development.
-<li>Interactive debugging.
-<li>Making a graphical user interface (using Tk for example).
-<li>Powerful testing of C libraries and programs (using scripts).
-<li>Building high performance C modules for scripting languages.
-<li>Making C programming more enjoyable (or tolerable depending on your point of view)
-<li>Impressing your friends.
-</ul>
-<p>
-There are some computer scientists who seem to believe that the only way to solve complicated problems is to create software of epic proportions and to have some sort of "grand" software design. Unfortunately this seems to lead to solutions that are even more complicated than the original problem. This, in turn enables the user to forget about the original problem and spend their time cursing at their machine (hence, the term "enabling technology"). SWIG, on the other hand, was developed because I was fed up with how much time I was wasting trying to develop flexible scientific applications. I wanted a tool that would let me use scripting languages to glue different things together, but didn't get in the way of the real problems I was working on. I wanted a simple tool that scientists and engineers could use to put together applications involving number crunching, data analysis, and visualization without having to worry about tedious systems programming, making substantial modifications to existing code, trying to figure out a big monolithic computing "environment," or having to get a second degree in computer science. In short, I wanted to have a tool that would improve application development, but stay out of the way as much as possible.<p>
-<a name="n2"></a><h2> Life before SWIG</h2>
-SWIG was developed to make my life easier as a C programmer. While C is great for high performance and systems programming, trying to make an interactive and highly flexible C program is a nightmare (in fact, it's much worse than that). The real problem is that for every C program I wrote, I needed to have some sort of interface, but being more interested in other problems, I would always end up writing a really bad interface that was hard to extend, hard to modify, and hard to use. I suppose I could have tried to do something fancy using X11, but who has time to waste weeks or months trying to come up with an interface that is probably going to end up being larger than the original C code? There are more interesting problems to work on.<p>
-<p>
-The real problem, perhaps, is that most C programs end up being structured as follows :<p>
-<p>
-<ul>
-<li>A collection of functions and variables.
-<li>A <tt>main()</tt> program that starts everything up.
-<li>A bunch of hacks added to make it usable.
-</ul>
-<p>
-The <tt>main()</tt> program may be written to handle command line arguments or to read data from <tt>stdin</tt>, but either way, modifying or extending the program to do something new requires changing the C code, recompiling, and testing. If you make a mistake, you need to repeat this cycle until things work. Of course, as more and more features are added, your C program turns into a hideous unintelligible mess that is even more difficult to modify than it was before (Of course, if you're lucky, your project starts out as an unintelligible mess).<p>
-<a name="n3"></a><h2> Life after SWIG</h2>
-With SWIG, I was hoping to avoid many of the headaches of working with C programs, by structuring things as follows :<p>
-<p>
-<ul>
-<li>A collection of functions and variables.
-<li>A nice interpreted interface language that can be used to access everything.
-</ul>
-<p>
-With this model, you keep all of the functionality of your C program, but access it through a scripting language interface instead of writing more C code. This is nice because you are given full freedom to call functions in any order, access variables, and write scripts to do all sorts of interesting things. If you want to change something, just modify a script, and rerun it. If you're trying to debug a collection of functions, you can call them individually and see what they do. If you're trying to build a package out of various components, you can just glue everything together with a scripting language and have a common interface to all of the various pieces. <p>
-<p>
-SWIG tries to make the integration between scripting languages and C as painless as possible. This allows you to focus on the underlying C program and using the high-level scripting language interface, but not the tedious and complex chore of making the two languages talk to each other.<p>
-<p>
-I like this model of programming. While it's certainly no "silver-bullet", it has made programming alot more enjoyable and has enabled us to solve complicated problems that would have been unneccessarily difficult using only C.<p>
-<a name="n4"></a><h2> The SWIG package</h2>
-SWIG is a compiler that takes ANSI C declarations and turns them into a file containing the C code for binding C functions, variables, and constants to a scripting language (SWIG also supports C++ class and Objective-C interface definitions). Input is specified in the form of an "interface file" containing declarations (input can also be given from C source files provided they are sufficiently clean). The SWIG parser takes this input file and passes it on to a code generation and documentation module. These modules produce an interface for a particular scripting language along with a document describing the interface that was created. Different scripting languages are supported by writing new back-end modules to the system.<p>
-<p><center><img src="ch1.1.png"></center><p>
-<p>
-<a name="n5"></a><h2> A SWIG example</h2>
-The best way to illustrate SWIG is with a simple example. Consider the following C code: <p>
-<p>
-<blockquote><pre>/* File : example.c */
-
-double My_variable = 3.0;
-
-/* Compute factorial of n */
-int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
-}
-
-/* Compute n mod m */
-int my_mod(int n, int m) {
- return(n % m);
-}
-</pre></blockquote>
-<p>
-Suppose that you wanted to access these functions and the global variable <tt>My_variable</tt> from Tcl. We start by making a SWIG interface file as shown below (by convention, these files carry a .i suffix) : <p>
-<a name="n13"></a><h3> SWIG interface file</h3>
-<blockquote><pre>
-/* File : example.i */
-%module example
-%{
-/* Put headers and other declarations here */
-%}
-
-extern double My_variable;
-extern int fact(int);
-extern int my_mod(int n, int m);
-</pre></blockquote>
-<p>
-The interface file contains ANSI C function prototypes and variable declarations. The <tt>%module</tt> directive defines the name of the module that will be created by SWIG. The <tt>%{,%}</tt> block provides a location for inserting additional code such as C header files or additional C functions. <p>
-<a name="n14"></a><h3> The swig command</h3>
-SWIG is invoked using the <tt>swig</tt> command. We can use this to build a Tcl module (under Linux) as follows :<p>
-<p>
-<blockquote><pre>unix > swig -tcl example.i
-Generating wrappers for Tcl.
-unix > gcc -c -fpic example.c example_wrap.c -I/usr/local/include
-unix > gcc -shared example.o example_wrap.o -o example.so
-unix > tclsh
-% load ./example.so
-% fact 4
-24
-% my_mod 23 7
-2
-% expr $My_variable + 4.5
-7.5
-%
-</pre></blockquote>
- <p>
-The <tt>swig</tt> command produced a new file called <tt>example_wrap.c</tt> that should be compiled along with the <tt>example.c</tt> file. Most operating systems and scripting languages now support dynamic loading of modules. In our example, our Tcl module has been compiled into a shared library that can be loaded into Tcl and used. When loaded, Tcl will now have our new functions and variables added to it. Taking a careful look at the file <tt>example_wrap.c</tt> reveals a hideous mess, but fortunately you almost never need to worry about it.<p>
-<a name="n15"></a><h3> Building a Perl5 module</h3>
-Now, let's turn these functions into a Perl5 module. Without making any changes type the following (shown for Solaris):<p>
-<p>
-<p>
-<blockquote><pre>unix > swig -perl5 example.i
-Generating wrappers for Perl5
-unix > gcc -c example.c example_wrap.c \
- -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
-unix> ld -G example.o example_wrap.o -o example.so # This is for Solaris
-unix > perl5.003
-use example;
-print example::fact(4), "\n";
-print example::my_mod(23,7), "\n";
-print $example::My_variable + 4.5, "\n";
-<ctrl-d>
-24
-2
-7.5
-unix >
-</pre></blockquote>
-<a name="n16"></a><h3> Building a Python module</h3>
-Finally, let's build a module for Python1.4 (shown for Irix).<p>
-<p>
-<blockquote><pre>unix > swig -python example.i
-Generating wrappers for Python
-unix > gcc -c example.c example_wrap.c -I/usr/local/include/python1.4
-unix > ld -shared example.o example_wrap.o -o examplemodule.so # Irix
-unix > Python
-Python 1.4 (Sep 10 1996) [GCC 2.7.0]
-Copyright 1991-1996 Stichting Mathematisch Centrum,
-Amsterdam
->>> import example
->>> example.fact(4)
-24
->>> example.my_mod(23,7)
-2
->>> example.cvar.My_variable + 4.5
-7.5
-</pre></blockquote>
-<a name="n17"></a><h3> Shortcuts</h3>
-To the truly lazy programmer, one may wonder why we needed the extra interface file at all. As it turns out, we can often do without it. For example, we could also build a Perl5 module by just running SWIG on the C source and specifying a module name as follows<p>
-<p>
-<blockquote><pre>% swig -perl5 -module example example.c
-unix > gcc -c example.c example_wrap.c \
- -I/usr/local/lib/perl5/sun4-solaris/5.003/CORE
-unix> ld -G example.o example_wrap.o -o example.so
-unix > perl5.003
-use example;
-print example::fact(4), "\n";
-print example::my_mod(23,7), "\n";
-print $example::My_variable + 4.5, "\n";
-<ctrl-d>
-24
-2
-7.5
-</pre></blockquote>
-<p>
-Of course, there are some restrictions as SWIG is not a full C/C++ parser. If you make heavy use of the C preprocessor, complicated declarations, or C++, giving SWIG a raw source file probably isn't going to work very well (in this case, you would probably want to use a separate interface file). <p>
-<p>
-SWIG also supports a limited form of conditional compilation. If we wanted to make a combination SWIG/C header file, we might do the following :<p>
-<p>
-<blockquote><pre>/* File : example.h */
-#ifdef SWIG
-%module example
-%include tclsh.i
-#endif
-extern double My_variable;
-extern int fact(int);
-extern int my_mod(int n, int m);
-
-</pre></blockquote>
-<a name="n18"></a><h3> Documentation generation</h3>
-In addition to producing an interface, SWIG also produces documentation. For our simple example, the documentation file may look like this :<p>
-<blockquote><pre>
-example_wrap.c
-
-[ Module : example, Package : example ]
-
-$My_variable
- [ Global : double My_variable ]
-
-fact(n);
- [ returns int ]
-
-my_mod(n,m);
- [ returns int ]
-
-get_time();
- [ returns char * ]
-
-</pre></blockquote>
-<p>
-C comments can be used to provide additional descriptions. SWIG can even grab these out of C source files in a variety of ways. For example, if we process <tt>example.c</tt> as follows :<p>
-<p>
-<blockquote><pre>swig -perl5 -Sbefore -module example example.c
-
-</pre></blockquote>
-We will get a documentation file that looks like this (with our C comments added) :<p>
-<blockquote><pre>
-example_wrap.c
-
-[ Module : example, Package : example ]
-
-
-$My_variable
- [ Global : double My_variable ]
-
-fact(n);
- [ returns int ]
- Compute factorial of n
-
-my_mod(n,m);
- [ returns int ]
- Compute n mod m
-
-</pre></blockquote>
-<a name="n19"></a><h3> Building libraries and modules</h3>
-In addition to generating wrapper code, SWIG provides extensive support for handling multiple files and building interface libraries. For example, our <tt>example.i</tt> file, could be used in another interface as follows :<p>
-<p>
-<blockquote><pre>%module foo
-%include example.i // Get definitions from example.i
-
-... Now more declarations ...
-
-</pre></blockquote>
-In a large system, an interface might be built from a variety of pieces like this :<p>
-<p>
-<blockquote><pre>%module package
-
-%include network.i
-%include file.i
-%include graphics.i
-%include objects.i
-%include simulation.i
-
-</pre></blockquote>
-SWIG comes with a library of existing functions known as the SWIG library. The library contains a mix of language independent and language dependent functionality. For example, the file `<tt>array.i</tt>' provides access to C arrays while the file `<tt>wish.i</tt>' includes specialized code for rebuilding the Tcl wish interpreter. Using the library, you can use existing modules to build up your own personalized environment for building interfaces. If changes are made to any of the components, they will appear automatically the next time SWIG is run. <p>
-<a name="n6"></a><h2> C syntax, but not a C compiler</h2>
-SWIG uses ANSI C syntax, but is not a full ANSI C compiler. By using C syntax, I hope to make SWIG easy to use with most C programs, easy to learn, and easy to remember. Other tools tend to use a precise interface definition language, but I personally find this approach to be painful. When I want to build an interface to a collection of several hundred C functions, I don't necessarily want to write a special interface definition for each one. Nor do I want to have to go dig up the manual because I can't remember the syntax.<p>
-<p>
-On the other hand, using C syntax can be ambiguous. For example, if you have the following declaration <p>
-<p>
-<blockquote><pre>int foo(double *a);
-
-</pre></blockquote>
-We don't really know if <tt>a</tt> is an array of some fixed size, a dynamically allocated block of memory, a single value, or an output value of the function. For the most part, SWIG takes a literal approach (<tt>a</tt> is obviously a <tt>double *</tt>) and leaves it up to the user to use the function in a correct manner. Fortunately, there are several ways to help SWIG out using additional directives and "helper" functions. Thus, the input to SWIG is often a mix of C declarations, special directives and hints. Like Perl programming, there is almost always more than one way to do almost anything.<p>
-<p>
-SWIG does not currently parse every conceivable type of C declaration that it might encounter in a C/C++ file. Many things may be difficult or impossible to integrate with a scripting language (C++ templates for example). Thus, SWIG may not recognize advanced C/C++ constructs. I make no apologies for this--SWIG was designed to access C, but was never intended to magically turn scripting languages into some sort of bizarre C++ interpreter. Of course, SWIG's parser is always being improved so currently unsupported features may be supported in later releases.<p>
-<a name="n7"></a><h2> Non-intrusive interface building</h2>
-When used as I intended, SWIG requires minimal modification to existing C code. This makes SWIG extremely easy to use with existing packages, but also promotes software reuse and modularity. By making the C code independent of the high level interface, you can change the interface and reuse the code in other applications. In a similar spirit, I don't believe that there is any one "best" scripting language--use whichever one you like (they're all pretty good). There's no real reason why a particular application couldn't support multiple scripting language interfaces to serve different needs (or to have no scripting language interface at all).<p>
-<a name="n8"></a><h2> Hands off code generation</h2>
-SWIG is designed to produce working code that needs no hand-modification (in fact, if you look at the output, you probably won't want to modify it). Ideally, SWIG should be invoked automatically inside a Makefile just as one would call the C compiler. You should think of your scripting language interface being defined entirely by the input to SWIG, not the resulting output file. While this approach may limit flexibility for hard-core hackers, it allows others to forget about the low-level implementation details. This is my goal.<p>
-<a name="n9"></a><h2> Event driven C programming</h2>
-By adding a scripting language interface to a program, SWIG encourages an event-driven style of programming (although it may not be immediately obvious). An event driven program basically consists of a large-collection of functions (called callback functions), and an infinite loop that just sits and waits for the user to do something. When the user does something like type a command, hit a key, or move the mouse the program will call a function to perform an operation--this is an event. Of course, unless you've been living in cave for the last 20 years, you've used this kind of approach when running any sort of graphical user interface.<p>
-<p>
-While you may not be using SWIG to develop a GUI, the underlying concept is the same. The scripting language acts as an event-loop waiting for you to issue commands. Unlike a traditional C application (that may use command line options), there is no longer a fixed sequence of operations. Functions may be issued in any order and at any time. Of course, this flexibility is exactly what we want! <p>
-<p>
-However, there are a number of things to keep in mind when developing an application with SWIG :<p>
-<p>
-<ul>
-<li>Functions may be called at any time and in any order. It is always a good idea for functions to check their arguments and internal state to see if it's legal to proceed (Not doing so usually results in mysterious crashes later on).
-<li>Code should be structured as a collection of independent modules, not a huge mess of interrelated functions and variables (ie. spaghetti code).
-<li>Global variables should be used with care.
-<li>Careful attention to the naming of variables and functions may be required to avoid namespace conflicts when combining packages.
-</ul>
-<p>
-While it may be hard (or impossible) to address all these problems in a legacy code, I believe that using SWIG encourages all of the above qualities when developing new applications. This results in code that is more reliable, more modular, and easier to integrate into larger packages. By providing a non-intrusive, easy to use tool, it is possible to develop highly reliable event-driven code from the start--not as a hack to be added later. As a final sales pitch, in the initial application for which SWIG was developed, code reliability and flexibility has increased substantially while code size has decreased by more than 25%. I believe this is a good thing.<p>
-<a name="n10"></a><h2> Automatic documentation generation</h2>
-SWIG makes it very easy to build large interactive C programs, but it can sometimes be hard to remember what C functions are available and how they are called in the scripting language interface. To address this problem, SWIG automatically generates a documentation file in a number of different formats. C comments can be used to provide additional descriptions of each function, and documentation can be grouped into a hierarchy of sections and subsections. The documentation file is intended to provide a reasonable description of the scripting language interface. While it's no competition for a full-blown C code documentation generator, the documentation system can do a reasonable job of documenting an interface.<p>
-<a name="n11"></a><h2> Summary</h2>
-At this point, you know about 95% of everything you need to know to start using SWIG. First, functions and variables are specified using ANSI C, C++, or Objective-C syntax. These may appear in a separate interface file or you can use a C source file (if it is sufficiently clean). SWIG requires no modifications to existing C code so it's easy to get started. To build a module, use the <tt>swig</tt> command with an appropriate target language option. This generates a C file that you need to compile with the rest of your code and you're ready to go. <p>
-<p>
-I don't consider there to be a "right" or "wrong" way to use SWIG, although I personally use separate interface files for a variety of reasons :<p>
-<p>
-<ul>
-<li>It helps keep me organized.
-<li>It's usually not necessary to wrap every single C function in a program.
-<li>SWIG provides a number of directives that I tend to use alot.
-<li>Having a special interface file makes it clear where the scripting language interface is defined. If you decide to change something in the interface, it's easy to track down if you have special file.
-</ul>
-<p>
-Of course, your mileage may vary. <p>
-<a name="n12"></a><h2> SWIG for Windows and Macintosh</h2>
-SWIG has been primarily developed and designed to work with Unix-based applications. However, most of the scripting languages supported by SWIG are available on a variety of other platforms including Windows 95/NT and Macintosh. SWIG generated code is mostly compatible with these versions (and SWIG itself can now run on these platforms). <p>
-<a name="n20"></a><h3> SWIG on Windows 95/NT</h3>
-The Windows 95/NT port of SWIG (provided by Kevin Butler), is a straightforward translation of the Unix version. At this time it is only known to work with Microsoft Visual C++ 4.x, but there is nothing to prevent its use with other compilers (at least not that I'm aware of). SWIG should be invoked from the MS-DOS prompt in exactly the same manner as in Unix. SWIG can also be used in NMAKE build files and added to Visual C++ projects under the custom build setting. As of this writing, SWIG is known to work with Windows versions of Tcl/Tk, Python, and Perl (including the ActiveWare Perl for Win32 port). SWIG makes extensive use of long filenames, so it is unlikely that the SWIG compiler will operate correctly under Windows 3.1 or DOS (the wrapper code generated by SWIG may compile however).<p>
-<a name="n21"></a><h3> SWIG on the Power Macintosh</h3>
-A Macintosh port of SWIG is also available, but is highly experimental at this time. It only works on PowerPC based Macintosh systems running System 7 or later. Modules can be compiled with the Metrowerks Code Warrior compiler, but support for other compilers is unknown. Due to the lack of command line options on the Mac, SWIG has been packaged in a Tcl/Tk interface that allows various settings and command line options to be specified with a graphical user interface. Underneath the hood, SWIG is identical to the Unix/Windows version. It recognizes the same set of options and generates identical code. Any SWIG command line option listed in this manual can be given to the Mac version under "Advanced Options" shown in the figure. At this writing, SWIG is only known to support Mac versions of Tcl/Tk. Work on Macintosh versions of Python and Perl is underway.<p>
-<p>Click <a href="ch1.2.png">here</a> to see a Macintosh screen shot.<p>
-<p>
-<p>
-<a name="n22"></a><h3> Cross platform woes</h3>
-While SWIG and various freely available scripting languages are supported on different platforms, developing cross platform applications with these tools is still immature and filled with pitfalls. In fact, it's probably only recommended for true masochists. Despite this, it's interesting to think about using freely available tools to provide common interfaces to C/C++ code. I believe that SWIG may help, but it is by no means a cross-platform solution by itself. <p>
-<a name="n23"></a><h3> How to survive this manual</h3>
-This manual was written to support the Unix version of SWIG. However, all of the main concepts and usage of SWIG also apply to the Windows and Macintosh versions. You should be forewarned that most of the examples are Unix-centric and may not compile correctly on other machines. However, most of the examples provided with the SWIG distribution have now been tested under both Unix and Windows-NT. When applicable, I will try to point out incompatibilities, but make no promises... <p>
-<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:50 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Library.html b/swigweb/Doc1.1/HTML/Library.html
deleted file mode 100644
index 93f713f..0000000
--- a/swigweb/Doc1.1/HTML/Library.html
+++ /dev/null
@@ -1,225 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Multiple Files and the SWIG Library</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>4 Multiple files and the SWIG library</h1><p><ul>
-<li> <a href="#n1">The %include directive</a>
-<li> <a href="#n2">The %extern directive</a>
-<li> <a href="#n3">The %import directive</a>
-<li> <a href="#n4">Including files on the command line</a>
-<li> <a href="#n5">The SWIG library</a>
-<li> <a href="#n6">Library example</a>
-<li> <a href="#n7">Creating Library Files</a>
-<li> <a href="#n8">Working with library files</a>
-<li> <a href="#n9">Static initialization of multiple modules</a>
-<li> <a href="#n10">More about the SWIG library</a>
-</ul>
-
-For increased modularity and convenience, it is usually useful to break an interface specification up into multiple files or modules. SWIG provides a number of features for doing just this.<p>
-<a name="n1"></a><h2> The %include directive</h2>
-The <tt>%include</tt> directive inserts code from another file into the current interface file. It is primarily used to build a package from a collection of smaller modules. For example :<p>
-<p>
-<blockquote><pre>// File : interface.i
-%module package
-%include equations.i
-%include graphics.i
-%include fileio.i
-%include data.i
-%include network.c
-%include "../Include/user.h"
-</pre></blockquote>
-<p>
-When used in this manner, SWIG will create a single wrapper file containing all of the included functions. <p>
-<p>
-The <tt>%include</tt> directive can process SWIG interface files, C header files, and C source files (provided they are sufficiently clean). When processing a C source file, SWIG will automatically declare all functions it finds as "extern". Thus, use of a header file may not be required in this case.<p>
-<a name="n2"></a><h2> The %extern directive</h2>
-The <tt>%extern</tt> directive is like <tt>%include</tt> except that it only scans a file for type and class information. It does not actually wrap anything found in the input file. This directive is primarily used for handling class hierarchies and multiple modules. For example :<p>
-<p>
-<blockquote><pre>%module derived
-%extern baseclass.h // Grab definition of a base class
-
-// Now wrap a derived class
-class Derived : public BaseClass {
-public:
- ...
-};
-
-</pre></blockquote>
-This interface file would grab the member functions and data from a baseclass, but only use them in the specification of a derived class. <tt>%extern</tt> processing of files is also useful for picking up common typedefs and definitions in a large package.<p>
-<a name="n3"></a><h2> The %import directive</h2>
-The <tt>%extern</tt> directive is used to gather declarations from files that you don't want to wrap into an interface. Unfornunately, the exact role of these files is not always clear. They could just contain definitions, or they might correspond to an entrirely different SWIG module. The <tt>%import</tt> directive is a stronger version of <tt>%extern</tt> that tells SWIG that all of the declarations in the file are indeed, in an entirely different module. This information may affect the code generated by various language modules since they will have a better idea of where things are defined and how they are to be used.<p>
-<a name="n4"></a><h2> Including files on the command line</h2>
-Much like the C or C++ compiler, SWIG can also include library files on the command line using the <tt>-l</tt> option as shown<p>
-<p>
-<blockquote><pre>
-# Include a library file at compile time
-% swig -tcl -lwish.i interface.i
-
-</pre></blockquote>
-This approach turns out to be particularly useful for debugging and building extensions to different kinds of languages. When libraries are specified in this manner, they are included after all of the declarations in <tt>interface.i</tt> have been wrapped. Thus, this does not work if you are trying to include common declarations, typemaps, and other files.<p>
-<a name="n5"></a><h2> The SWIG library </h2>
-SWIG comes with a library of functions that can be used to build up more complex interfaces. As you build up a collection of modules, you may also find yourself with a large number of interface files. While the <tt>%include</tt> directive can be used to insert files, it also searches the files installed in the SWIG library (think of this as the SWIG equivalent of the C library). When you use <tt>%include</tt>, SWIG will search for the file in the following order :<p>
-<p>
-<ul>
-<li>The current directory
-<li>Directories specified with the -I option
-<li>.<tt>/swig_lib</tt>
-<li><tt>/usr/local/lib/swig_lib</tt> (or wherever you installed SWIG)
-</ul>
-<p>
-Within each directory, you can also create subdirectories for each target language. If found, SWIG will search these directories first, allowing the creation of language-specific implementations of a particular library file.<p>
-<p>
-You can override the location of the SWIG library by setting the <tt>SWIG_LIB</tt> environment variable.<p>
-<a name="n6"></a><h2> Library example</h2>
-The SWIG library is really a repository of "useful modules" that can be used to build better interfaces. To use a library file, you can simply use the <tt>%include </tt>directive with the name of a library file. For example :<p>
-<p>
-<blockquote><pre>%module example
-
-%include pointer.i // Grab the SWIG pointer library
-
-// a+b --> c
-extern double add(double a, double b, double *c);
-
-</pre></blockquote>
-In this example, we are including the SWIG pointer library that adds functions for manipulating C pointers. These added functions become part of your module that can be used as needed. For example, we can write a Tcl script like this that involves both the <tt>add()</tt> function and two functions from the <tt>pointer.i</tt> library :<p>
-<p>
-<blockquote><pre>set c [ptrcreate double 0] ;# Create a double * for holding the result
-add 4 3.5 $c ;# Call our C function
-puts [ptrvalue $c] ;# Print out the result
-</pre></blockquote>
-<a name="n7"></a><h2> Creating Library Files</h2>
-It is easy to create your own library files. To illustrate the process, we consider two different library files--one to build a new <tt>tclsh</tt> program, and one to add a few memory management functions.<p>
-<a name="n11"></a><h3> tclsh.i</h3>
-To build a new <tt>tclsh</tt> application, you need to supply a <tt>Tcl_AppInit()</tt> function. This can be done using the following SWIG interface file (simplified somewhat for clarity) :<p>
-<blockquote><pre>
-// File : tclsh.i
-%{
-#if TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION >= 4
-int main(int argc, char **argv) {
- Tcl_Main(argc, argv, Tcl_AppInit);
- return(0);
-}
-#else
-extern int main();
-#endif
-int Tcl_AppInit(Tcl_Interp *interp){
- int SWIG_init(Tcl_Interp *);
-
- if (Tcl_Init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- /* Now initialize our functions */
-
- if (SWIG_init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- return TCL_OK;
-}
-%}
-</pre></blockquote>
-In this case, the entire file consists of a single code block. This code will be inserted directly into the resulting wrapper file, providing us with the needed <tt>Tcl_AppInit()</tt> function.<p>
-<a name="n12"></a><h3> malloc.i</h3>
-Now suppose we wanted to write a file <tt>malloc.i</tt> that added a few memory management functions. We could do the following :<p>
-<p>
-<blockquote><pre>// File : malloc.i
-%{
-#include <malloc.h>
-%}
-
-%typedef unsigned int size_t
-void *malloc(size_t nbytes);
-void *realloc(void *ptr, size_t nbytes);
-void free(void *);
-</pre></blockquote>
-<p>
-In this case, we have a general purpose library that could be used whenever we needed access to the <tt>malloc()</tt> functions. Since this interface file is language independent, we can use it anywhere.<p>
-<a name="n13"></a><h3> Placing the files in the library</h3>
-While both of our examples are SWIG interface files, they are quite different in functionality since <tt>tclsh.i</tt> would only work with Tcl while <tt>malloc.i</tt> would work with any of the target languages. Thus, we should put these files into the SWIG library as follows :<p>
-<blockquote><pre><tt>
-./swig_lib/malloc.i
-./swig_lib/tcl/tclsh.i
-</tt></pre></blockquote>
-<p>
-When used in other interface files, this allows us to use <tt>malloc.i</tt> with any target language while <tt>tclsh.i</tt> will only be accessible if creating for wrappers for Tcl (ie. when creating a Perl5 module, SWIG will not look in the <tt>tcl</tt> subdirectory.<p>
-<p>
-It should be noted that language specific libraries can mask general libraries. For example, if you wanted to make a Perl specific modification to <tt>malloc.i</tt>, you could make a special version and call it <tt>./swig_lib/perl5/malloc.i</tt>. When using Perl, you'd get this version, while all other target languages would use the general purpose version.<p>
-<a name="n8"></a><h2> Working with library files</h2>
-There are a variety of additional methods for working with files in the SWIG library described next.<p>
-<a name="n14"></a><h3> Wrapping a library file</h3>
-If you would like to wrap a file in the SWIG library, simply give SWIG the name of the appropriate library file on the command line. For example :<p>
-<p>
-<blockquote><pre>unix > swig -python pointer.i
-
-</pre></blockquote>
-If the file <tt>pointer.i</tt> is not in the current directory, SWIG will look it up in the library, generate wrapper code, and place the output in the current directory. This technique can be used to quickly make a module out of a library file regardless of where you are working.<p>
-<a name="n15"></a><h3> Checking out library files</h3>
-At times, it is useful to check a file out of the library and copy it into the working directory. This allows you to modify the file or to simply retrieve useful files. To check a file out of the library, run SWIG as follows :<p>
-<p>
-<blockquote><pre>unix > swig -co -python array.i
-array.i checked out from the SWIG library
-unix >
-
-</pre></blockquote>
-The library file will be placed in the current directory unless a file with the same name already exists (in which case nothing is done). <p>
-<p>
-The SWIG library is not restricted to interface files. Suppose you had a cool Perl script that you liked to use alot. You could place this in the SWIG library. Now whenever you wanted to use it, you could retrieve it by issuing :<p>
-<p>
-<blockquote><pre>unix > swig -perl5 -co myscript.pl
-myscript.pl checked out from the SWIG library
-
-</pre></blockquote>
-Support files can also be checked out within an interface file using the <tt>%checkout</tt> directive.<p>
-<p>
-<blockquote><pre>%checkout myscript.pl
-
-</pre></blockquote>
-This will attempt to copy the file <tt>myscript.pl</tt> to the current directory when SWIG is run. If the file already exists, nothing is done.<p>
-<a name="n16"></a><h3> The world's fastest way to write a Makefile</h3>
-Since the SWIG library is not restricted to SWIG interface files, it can be used to hold other kinds of useful files. For example, if you need a quick Makefile for building Tcl extensions, type the following:<p>
-<blockquote><pre>
-unix> swig -tcl -co Makefile
-Makefile checked out from the SWIG library
-
-</pre></blockquote>
-During installation, SWIG creates a collection of preconfigured Makefiles for various scripting languages. If you need to make a new module, just check out one of these Makefiles, make a few changes, and you should be ready to compile and extension for your system.<p>
-<a name="n17"></a><h3> Checking in library files</h3>
-It is also possible to check files into the SWIG library. If you've made an interesting interface that you would like to keep around, simply type :<p>
-<p>
-<blockquote><pre>unix > swig -ci -python cool.i
-
-</pre></blockquote>
-and the file `<tt>cool.i</tt>' will be placed in the Python section of the library. If your interface file is general purpose, you can install it into the general library as follows :<p>
-<p>
-<blockquote><pre>unix > swig -ci ../cool.i
-
-</pre></blockquote>
-When files are checked in, they are placed into the directory defined by the <tt>SWIG_LIB</tt> variable that was used during SWIG compilation or the <tt>SWIG_LIB</tt> environment variable (if set). If you don't know what the value of this variable is, type the following to display its location.<p>
-<p>
-<blockquote><pre>unix > swig -swiglib
-/usr/local/lib/swig_lib
-unix >
-</pre></blockquote>
-<p>
-In order to check files into the library, you must have write permission on the library directory. For this reason, one of the primary uses for the <tt>-ci</tt> option is to provide a simple mechanism for installing SWIG extensions. If these extensions need to install library files, that can be done by simply running SWIG.<p>
-<a name="n9"></a><h2> Static initialization of multiple modules</h2>
-When using static linking, some language modules allow multiple modules to be initialized as follows :<p>
-<p>
-<blockquote><pre>%module package, equations, graphics, fileio, data, network, user
-
-... More declarations ...
-
-</pre></blockquote>
-The module list can contain SWIG generated modules or third-party applications. Refer to the appropriate language chapter for a detailed description of this feature.<p>
-<a name="n10"></a><h2> More about the SWIG library</h2>
-Full documentation about the SWIG library is included in the SWIG source distribution. In fact, the documentation is automatically generated by SWIG, which leads us to the next section...<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:54 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Perl5.html b/swigweb/Doc1.1/HTML/Perl5.html
deleted file mode 100644
index cdcafb8..0000000
--- a/swigweb/Doc1.1/HTML/Perl5.html
+++ /dev/null
@@ -1,1919 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>SWIG and Perl5</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>8 SWIG and Perl5</h1><p><ul>
-<li> <a href="#n1">Preliminaries</a>
-<li> <a href="#n2">Building Perl Extensions under Windows 95/NT</a>
-<li> <a href="#n3">Modules, packages, and classes</a>
-<li> <a href="#n4">Basic Perl interface</a>
-<li> <a href="#n5">A simple Perl example</a>
-<li> <a href="#n6">Accessing arrays and other strange objects</a>
-<li> <a href="#n7">Implementing methods in Perl</a>
-<li> <a href="#n8">Shadow classes</a>
-<li> <a href="#n9">Getting serious</a>
-<li> <a href="#n10">Wrapping C libraries and other packages</a>
-<li> <a href="#n11">Building a Perl5 interface to MATLAB</a>
-<li> <a href="#n12">Handling output values (the easy way)</a>
-<li> <a href="#n13">Exception handling</a>
-<li> <a href="#n14">Remapping datatypes with typemaps</a>
-<li> <a href="#n15">The gory details on shadow classes</a>
-<li> <a href="#n16">Where to go from here?</a>
-</ul>
-
-In this chapter, we discuss SWIG's support of Perl5. While the Perl5 module is one of the earliest SWIG modules, it has continued to evolve and has been improved greatly with the help of SWIG users. For the best results, it is recommended that SWIG be used with Perl5.003 or later. Earlier versions are problematic and SWIG generated extensions may not compile or run correctly.<p>
-<a name="n1"></a><h2> Preliminaries</h2>
-In order for this section to make much sense, you will need to have Perl5.002 (or later) installed on your system. You should also determine if your version of Perl has been configured to use dynamic loading or not. SWIG will work with or without it, but the compilation process will be different.<p>
-<a name="n17"></a><h3> Running SWIG</h3>
-To build a Perl5 module, run swig using the <tt>-perl5</tt> option as follows :<p>
-<blockquote><pre>
-swig -perl5 example.i
-
-</pre></blockquote>
-This will produce 3 files. The first file, <tt>example_wrap.c</tt> contains all of the C code needed to build a Perl5 module. The second file, <tt>example.pm</tt> contains supporting Perl code needed to properly load the module into Perl. The third file will be a documentation file (the exact filename depends on the documentation style). To finish building a module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program (and possibly Perl itself). There are several methods for doing this.<p>
-<a name="n18"></a><h3> Getting the right header files</h3>
-In order to compile, you will need to use the following Perl5 header files :<p>
-<blockquote><pre>
-#include "Extern.h"
-#include "perl.h"
-#include "XSUB.h"
-</pre></blockquote>
-<p>
-These are usually located in a directory like this<p>
-<p>
-<blockquote><pre>/usr/local/lib/perl5/arch-osname/5.003/CORE
-</pre></blockquote>
-<p>
-The SWIG configuration script will try to find this directory, but it's not entirely foolproof. You may have to dig around yourself.<p>
-<a name="n19"></a><h3> Compiling a dynamic module</h3>
-To compile a dynamically loadable module, you will need to do something like the following, <p>
-<blockquote><pre>
-% gcc example.c
-% gcc example_wrap.c -I/usr/local/lib/perl5/arch-osname/5.003/CORE
- -Dbool=char -c
-% ld -shared example.o example_wrap.o -o example.so # Irix
-</pre></blockquote>
-<p>
-The name of the shared object file must match the module name used in the SWIG interface file. If you used `<tt>%module example</tt>', then the target should be named `<tt>example.so</tt>', `<tt>example.sl</tt>', or the appropriate name on your system (check the man pages for the linker).<p>
-<p>
-Unfortunately, the process of building dynamic modules varies on every single machine. Both the C compiler and linker may need special command line options. SWIG tries to guess how to build dynamic modules on your machine in order to run its example programs. Again, the configure script isn't foolproof .<p>
-<a name="n20"></a><h3> Building a dynamic module with MakeMaker</h3>
-It is also possible to use Perl to build dynamically loadable modules for you using the MakeMaker utility. To do this, write a simple Perl script such as the following :<p>
-<p>
-<blockquote><pre># File : Makefile.PL
-use ExtUtils::MakeMaker;
-WriteMakefile(
- `NAME' => `example', # Name of package
- `LIBS' => [`-lm'], # Name of custom libraries
- `OBJECT' => `example.o example_wrap.o' # Object files
-);
-
-</pre></blockquote>
-Now, to build a module, simply follow these steps :<p>
-<p>
-<blockquote><pre>% perl Makefile.PL
-% make
-% make install
-</pre></blockquote>
-<p>
-This is the preferred approach if you building general purpose Perl5 modules for distribution. More information about MakeMaker can be found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen, and Randal Schwartz.<p>
-<a name="n21"></a><h3> Building a static version of Perl</h3>
-If you machine does not support dynamic loading, or if you've tried to use it without success, you can build a new version of the Perl interpreter with your SWIG extensions added to it. To build a static extension, you first need to invoke SWIG as follows :<p>
-<p>
-<blockquote><pre>% swig -perl5 -static example.i
-</pre></blockquote>
-<p>
-By default SWIG includes code for dynamic loading, but the <tt>-static</tt> option takes it out.<p>
-<p>
-Next, you will need to supply a <tt>main()</tt> function that initializes your extension and starts the Perl interpreter. While, this may sound daunting, SWIG can do this for you automatically as follows :<p>
-<blockquote><pre>
-%module example
-
-extern double My_variable;
-extern int fact(int);
-
-// Include code for rebuilding Perl
-%include perlmain.i
-</pre></blockquote>
-<p>
-The same thing can be accomplished by running SWIG as follows :<p>
-<p>
-<blockquote><pre>% swig -perl5 -static -lperlmain.i example.i
-
-</pre></blockquote>
-The <tt>permain.i</tt> file inserts Perl's <tt>main()</tt> function into the wrapper code and automatically initializes the SWIG generated module. If you just want to make a quick a dirty module, this may be the easiest way. By default, the <tt>perlmain.i</tt> code does not initialize any other Perl extensions. If you need to use other packages, you will need to modify it appropriately. You can do this by just copying <tt>perlmain.i</tt> out of the SWIG library, placing it in your own directory, and modifying it to suit your purposes.<p>
-<p>
-To build your new Perl executable, follow the exact same procedure as for a dynamic module, but change the link line as follows :<p>
-<blockquote><pre>
-% ld example.o example_wrap.o -L/usr/local/lib/perl5/arch/5.003/CORE \
- -lperl -lsocket -lnsl -lm -o myperl
-</pre></blockquote>
-<p>
-This will produce a new version of Perl called <tt>myperl</tt>. It should be functionality identical to Perl with your C/C++ extension added to it. Depending on your machine, you may need to link with additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc...<p>
-<a name="n22"></a><h3> Compilation problems and compiling with C++</h3>
-In some cases, you may get alot of error messages about the `<tt>bool</tt>' datatype when compiling a SWIG module. If you experience this problem, you can try the following :<p>
-<p>
-<ul>
-<li>Use <tt>-DHAS_BOOL</tt> when compiling the SWIG wrapper code
-<li>Or use <tt>-Dbool=char</tt> when compiling.
-</ul>
-<p>
-Compiling dynamic modules for C++ is also a tricky business. When compiling C++ modules, you may need to link using the C++ compiler such as :<p>
-<blockquote><pre>
-unix > c++ -shared example_wrap.o example.o -o example.so
-</pre></blockquote>
-<p>
-It may also be necessary to link against the <tt>libgcc.a</tt>, <tt>libg++.a</tt>, and <tt>libstdc++.a</tt> libraries (assuming g++). C++ may also complain about one line in the Perl header file "<tt>perl.h</tt>" and the invalid use of the "explicit" keyword. To work around this problem, put the option <tt>-Dexplicit=</tt> in your compiler flags.<p>
-<p>
-If all else fails, put on your wizard cap and start looking around in the header files. Once you've figured out how to get one module to compile, you can compile just about all other modules.<p>
-<a name="n2"></a><h2> Building Perl Extensions under Windows 95/NT</h2>
-Building a SWIG extension to Perl under Windows 95/NT is roughly similar to the process used with Unix. Normally, you will want to produce a DLL that can be loaded into the Perl interpreter. This section assumes you are using SWIG with Microsoft Visual C++ 4.x although the procedure may be similar with other compilers. SWIG currently supports the ActiveWare Perl for Win32 port and Perl 5.004. If using the ActiveWare version, all Perl extensions must be compiled using C++!<p>
-<a name="n23"></a><h3> Running SWIG from Developer Studio</h3>
-If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process roughly requires these steps :<p>
-<p>
-<ul>
-<li>Open up a new workspace and use the AppWizard to select a DLL project.
-<li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't exist yet--Developer studio will keep a reference to it around.
-<li>Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
-<li>Enter "SWIG" in the description field.
-<li>Enter "<tt>swig -perl5 -o $(ProjDir)\$(InputName)_wrap.cxx $(InputPath)</tt>" in the "Build command(s) field"
-<li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>xx" in the "Output files(s) field".
-<li>Next, select the settings for the entire project and go to "C++:Preprocessor". Add the include directories for your Perl 5 installation under "Additional include directories".
-<li>Define the symbols WIN32 and MSWIN32 under preprocessor options. If using the ActiveWare port, also define the symbol PERL_OBJECT. Note that all extensions to the ActiveWare port must be compiled with the C++ compiler since Perl has been encapsulated in a C++ class.
-<li>Finally, select the settings for the entire project and go to "Link Options". Add the Perl library file to your link libraries. For example "perl.lib". Also, set the name of the output file to match the name of your Perl module (ie. example.dll).
-<li>Build your project.
-</ul>
-<p>
-Now, assuming all went well, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Perl extension, simply run Perl and use the use command as normal. For example :<p>
-<p>
-<blockquote><pre>
-DOS > perl
-use example;
-$a = example::fact(4);
-print "$a\n";
-
-</pre></blockquote>
-It appears that DLL's will work if they are placed in the current working directory. To make a generally DLL available, it should be place (along with its support files) in the <tt>Lib\Auto\[module] </tt>sub-directory of the Perl directory where [module] is the name of your module.<p>
-<a name="n24"></a><h3> Using NMAKE</h3>
-Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE. To do this, make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. Now, just write a short Makefile like this :<p>
-<p>
-<blockquote><pre># Makefile for building an ActiveWare Perl for Win32 extension
-# Note : Extensions must be compiled with the C++ compiler!
-
-SRCS = example.cxx
-IFILE = example
-INTERFACE = $(IFILE).i
-WRAPFILE = $(IFILE)_wrap.cxx
-
-# Location of the Visual C++ tools (32 bit assumed)
-
-TOOLS = c:\msdev
-TARGET = example.dll
-CC = $(TOOLS)\bin\cl.exe
-LINK = $(TOOLS)\bin\link.exe
-INCLUDE32 = -I$(TOOLS)\include
-MACHINE = IX86
-
-# C Library needed to build a DLL
-
-DLLIBC = msvcrt.lib oldnames.lib
-
-# Windows libraries that are apparently needed
-WINLIB = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib
-winspool.lib
-
-# Libraries common to all DLLs
-LIBS = $(DLLIBC) $(WINLIB)
-
-# Linker options
-LOPT = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO /
-MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
-
-# C compiler flags
-
-CFLAGS = /Z7 /Od /c /W3 /nologo
-
-# Perl 5.004
-PERL_INCLUDE = -Id:\perl5\lib\CORE
-PERLLIB = d:\perl5\lib\CORE\perl.lib
-PERLFLAGS = /DWIN32 /DMSWIN32 /DWIN32IO_IS_STDIO
-
-# ActiveWare
-PERL_INCLUDE = -Id:\perl -Id:\perl\inc
-PERL_LIB = d:\perl\Release\perl300.lib
-PERLFLAGS = /DWIN32 /DMSWIN32 /DPERL_OBJECT
-
-perl::
- ..\..\swig -perl5 -o $(WRAPFILE) $(INTERFACE)
- $(CC) $(CFLAGS) $(PERLFLAGS) $(PERL_INCLUDE) $(SRCS) $(WRAPFILE)
- set LIB=$(TOOLS)\lib
- $(LINK) $(LOPT) -out:example.dll $(LIBS) $(PERLLIB) example.obj
-example_wrap.obj
-</pre></blockquote>
-<p>
-To build the extension, run NMAKE (note that you may be to run <tt>vcvars32</tt> before doing this to set the correct environment variables). This is a simplistic Makefile, but hopefully its enough to get you started. <p>
-<a name="n3"></a><h2> Modules, packages, and classes</h2>
-When you create a SWIG extension, everything gets thrown together into a single Perl5 module. The name of the module is determined by the <tt>%module</tt> directive. To use the module, do the following :<p>
-<p>
-<blockquote><pre>% perl5
-use example; # load the example module
-print example::fact(4),"\n" # Call a function in it
-24
-</pre></blockquote>
-<p>
-Usually, a module consists of a collection of code that is contained within a single file. A package, on the other hand, is the Perl equivalent of a namespace. A package is alot like a module, except that it is independent of files. Any number of files may be part of the same package--or a package may be broken up into a collection of modules if you prefer to think about it in this way.<p>
-<p>
-By default, SWIG installs its functions into a package with the same name as the module. This can be changed by giving SWIG the -package option :<p>
-<p>
-<blockquote><pre>% swig -perl5 -package FooBar example.i
-</pre></blockquote>
-<p>
-In this case, we still create a module called `<tt>example</tt>', but all of the functions in that module will be installed into the package `<tt>FooBar</tt>.' For example :<p>
-<p>
-<blockquote><pre>use example; # Load the module like before
-print FooBar::fact(4),"\n"; # Call a function in package FooBar
-</pre></blockquote>
-<p>
-Perl supports object oriented programming using packages. A package can be thought of as a namespace for a class containing methods and data. The reader is well advised to consult "Programming Perl, 2nd Ed." by Wall, Christiansen, and Schwartz for most of the gory details. <p>
-<a name="n4"></a><h2> Basic Perl interface</h2>
-<a name="n25"></a><h3> Functions</h3>
-C functions are converted into new Perl commands (or subroutines). Default/optional arguments are also allowed. An interface file like this :<p>
-<p>
-<blockquote><pre>%module example
-int foo(int a);
-double bar (double, double b = 3.0);
-...
-
-</pre></blockquote>
-Will be used in Perl like this :<p>
-<p>
-<blockquote><pre>use example;
-$a = &example::foo(2);
-$b = &example::bar(3.5,-1.5);
-$c = &example::bar(3.5); # Use default argument for 2nd parameter
-
-</pre></blockquote>
-Okay, this is pretty straightforward...enough said.<p>
-<a name="n26"></a><h3> Global variables</h3>
-Global variables are handled using pure magic--well, Perl's magic variable mechanism that is. In a nutshell, it is possible to make certain Perl variables "magical" by attaching methods for getting and setting values among other things. SWIG generates a pair of functions for accessing C global variables and attaches them to a Perl variable of the same name. Thus, an interface like this <p>
-<p>
-<blockquote><pre>%module example;
-...
-double Spam;
-...
-
-</pre></blockquote>
-is accessed as follows :<p>
-<p>
-<blockquote><pre>use example;
-print $example::Spam,"\n";
-$example::Spam = $example::Spam + 4
-# ... etc ...
-
-</pre></blockquote>
-SWIG supports global variables of all C datatypes including pointers and complex objects.<p>
-<a name="n27"></a><h3> Constants</h3>
-Constants are created as read-only magical variables and operate in exactly the same manner.<p>
-<a name="n28"></a><h3> Pointers</h3>
-SWIG represents pointers as blessed references. A blessed reference is the same as a Perl reference except that it has additional information attached to it indicating what kind of reference it is. That is, if you have a C declaration like this :<p>
-<p>
-<blockquote><pre>Matrix *new_Matrix(int n, int m);
-</pre></blockquote>
-<p>
-SWIG will return a value as if you had done this :<p>
-<blockquote><pre>
-$ptr = new_Matrix(int n, int m); # Save pointer return result
-bless $ptr, "MatrixPtr"; # Bless it as a MatrixPtr
-</pre></blockquote>
-<p>
-SWIG uses the "blessing" to check the datatype of various pointers. In the event of a mismatch, an error or warning message will be generated.<p>
-<p>
-To check to see if a value is the NULL pointer, use the <tt>defined()</tt> command :<p>
-<blockquote><pre>
-if (defined($ptr)) {
- print "Not a NULL pointer.";
-} else {
- print "Is a NULL pointer.";
-}
-
-</pre></blockquote>
-To create a NULL pointer, you should pass the <tt>undef </tt>value to a function. <p>
-<p>
-The "value" of a Perl reference is not the same as the underlying C pointer that SWIG wrapper functions return. Suppose that <tt>$a</tt> and <tt>$b</tt> are two references that point to the same C object. In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they are different references. Thus, it is a mistake to check the equality of <tt>$a </tt>and <tt>$b</tt> to check the equality of two C pointers. The correct method to check equality of C pointers is to dereference them as follows :<p>
-<p>
-<blockquote><pre>if ($$a == $$b) {
- print "a and b point to the same thing in C";
-} else {
- print "a and b point to different objects.";
-}
-
-</pre></blockquote>
-It is easy to get burned by references in more subtle ways. For example, if you are storing a hash table of objects, it may be best to use the actual C pointer value rather than the Perl reference as a key. Since each Perl reference to the same C object may be different, it would be impossible to find anything in the hash without this. As a general rule, the best way to avoid problems with references is to make sure hash tables, comparisons, and other pointer operations use the value of the reference (ie. <tt>$$a</tt>), not the reference itself.<p>
-<a name="n29"></a><h3> Structures and C++ classes</h3>
-For structures and classes, SWIG produces a set of accessor functions for member functions and member data. For example :<p>
-<p>
-<blockquote><pre>%module vector
-
-class Vector {
-public:
- double x,y,z;
- Vector();
- ~Vector();
- double magnitude();
-};
-
-</pre></blockquote>
-This gets turned into the following collection of Perl functions :<p>
-<blockquote><pre>vector::Vector_x_get($obj);
-vector::Vector_x_set($obj,$x);
-vector::Vector_y_get($obj);
-vector::Vector_y_set($obj,$y);
-vector::Vector_z_get($obj);
-vector::Vector_z_set($obj,$z);
-vector::new_Vector();
-vector::delete_Vector($obj);
-vector::Vector_magnitude($obj);
-
-</pre></blockquote>
-To use the class, simply use these functions. As it turns out, SWIG has a mechanism for creating shadow classes that hides these functions and uses an object oriented interface instead--keep reading.<p>
-<a name="n5"></a><h2> A simple Perl example</h2>
-In the next few sections, use of the Perl5 module will be illustrated through a series of increasingly complex examples. In the example, we will write some simple graph algorithms to illustrate how C and Perl can interact with each other. <p>
-<a name="n30"></a><h3> Graphs</h3>
-A directed graph is simply a collection of nodes (or vertices) that are connected to each other by a collection of edges :<p>
-<p>
-<center><img src="ch8.1.png"></center><p><p>
-<p>
-To represent simple graphs, we can use the following C data structures :<p>
-<p>
-<blockquote><pre>/* File : graph.h */
-/* Simple data structures for directed graph of Nodes and Edges */
-
-struct Edge;
-typedef struct Node {
- int v; /* Vertex number */
- struct Edge *adj; /* Adjacency List */
-} Node;
-
-typedef struct Edge {
- Node *node; /* Connecting Node */
- double w; /* Weight (optional) */
- struct Edge *next; /* Next edge */
-} Edge;
-
-</pre></blockquote>
-Each node contains a unique number v for identifying it, and a linked list of other nodes that are nearby. This linked list is managed by the <tt>Edge</tt> structure. Associated with each edge is an optional weighting factor. This could be something like miles between cities, bandwidth, or some other numerical property about a particular link. Okay, enough talk about data structures for now.<p>
-<p>
-To construct nodes and add edges, we can use the following C code :<p>
-<p>
-<blockquote><pre>/* File : graph.c */
-/* Directed graph functions */
-
-#include "graph.h"
-static int node_count = 0; /* Number of nodes created */
-
-/* Create a new Node */
-Node *new_Node() {
- Node *node;
- node = (Node *) malloc(sizeof(Node));
- node->v = node_count++; /* Bump up the count */
- node->adj = (Edge *) 0;
- return node;
-}
-
-/* Add an "edge" to another node. */
-
-Edge *Node_addedge(Node *mynode, Node *othernode, double w) {
- Edge *edge;
- edge = (Edge *) malloc(sizeof(Edge));
- edge->node = othernode;
- edge->w = w;
- edge->next = mynode->adj; /* add to my adjacency list */
- mynode->adj = edge;
- return edge;
-}
-
-</pre></blockquote>
-<a name="n31"></a><h3> A simple SWIG interface file</h3>
-So far, the code doesn't do much, but it's enough to wrap into Perl5 module. Since the C code is fairly simple right now, we can do this by creating the following interface file :<p>
-<blockquote><pre>
-%module graph
-%{
-#include "graph.h"
-%}
-%include graph.h // Get structure definition
-%include graph.c // Get support functions
-</pre></blockquote>
-<p>
-We'll call our module "graph" and simply read in both the files <tt>graph.h</tt> and <tt>graph.c</tt> to build an interface. <p>
-<a name="n32"></a><h3> Sample Perl Script</h3>
-Once compiled, we can now start using our new module. All of the C functions found in <tt>graph.h</tt> and <tt>graph.c</tt> can be called normally . Even though we are using pointers, this is not a problem. Here is a very simple script :<p>
-<blockquote><pre>
-# Perl code to use our graph code
-
-use graph;
-package graph;
-
-# Create some nodes
-$n0 = new_Node();
-$n1 = new_Node();
-$n2 = new_Node();
-
-# Make some edges
-Node_addedge($n0,$n1,0); # 0 -> 1
-Node_addedge($n0,$n2,0); # 0 -> 2
-Node_addedge($n1,$n2,0); # 1 -> 2
-Node_addedge($n2,$n0,0); # 2 -> 0
-
-# A procedure to print out a node and its adjacency list
-sub print_node {
- my $node = shift;
- print "Node : ", Node_v_get($node), ", Adj : ";
- my $adj = Node_adj_get($node);
- while (defined($adj)) { # This checks for a NULL pointer
- my $anode = Edge_node_get($adj);
- my $v = Node_v_get($anode);
- print "$v ";
- $adj = Edge_next_get($adj); # Move to next node
- }
- print "\n";
-}
-
-# Print out node information
-print_node($n0);
-print_node($n1);
-print_node($n2);
-
-</pre></blockquote>
-When executed, this script produces the following output :<p>
-<p>
-<blockquote><pre>Node : 0, Adj : 2 1
-Node : 1, Adj : 2
-Node : 2, Adj : 0
-
-</pre></blockquote>
-<p>
-While our two C functions are used in the script, SWIG also created a collection of accessor functions for managing the two C data structures. The functions <tt>Node_v_get()</tt>, <tt>Node_adj_get()</tt>, <tt>Edge_node_get()</tt>, and <tt>Edge_next_get()</tt> are used to access the corresponding members of our <tt>Node</tt> and <tt>Edge</tt> structures. As arguments, these functions simply take a pointer to the corresponding structure.<p>
-<p>
-There are a few other things to notice about the code.<p>
-<p>
-<ul>
-<li>Pointers to complex objects are manipulated like ordinary scalar values, but in reality they are blessed references. For all practical purposes, you should think of them as funny opaque objects (in other words, don't worry about it).
-<li>To check for a NULL pointer, use the expression <tt>defined($ptr)</tt>. This will return true if a pointer is non-NULL, false if it isn't. In our example, we use this to walk down a linked list of pointers until we reach a NULL value.
-</ul>
-<p>
-Even though the original C code was rather useless by itself, we have used it to build a simple graph in Perl along with a debugging function for printing out node information. In fact, without making any modifications to the C code, we can use this to build up something more complex such as a database of cities and mileages. <p>
-<p>
-<em>Some cities and mileages</em><p>
-<p>
-Here's a slightly more complicated Perl script to read in the above mileage table and turn it into a graph:<p>
-<p>
-<blockquote><pre># Read a file with cities into a graph
-
-use graph;
-package graph;
-
-%Cities = (); # Hash table mapping cities to nodes
-%Nodes = (); # Mapping of Node indicies to cities
-sub read_cities {
- my $filename = shift;
- open(CITIES,$filename);
- while (<CITIES>) {
- chop;
- my @a = split(/, +/);
- my $node1;
- my $node2;
- # Check to see if a given city is already a node
- if (!exists $Cities{$a[0]}) {
- $node1 = new_Node();
- $Cities{$a[0]} = $node1;
- my $node_num = Node_v_get($node1);
- $Nodes{$node_num} = $a[0];
- } else {
- $node1 = $Cities{$a[0]};
- }
- if (!exists $Cities{$a[1]}) {
- $node2 = new_Node();
- $Cities{$a[1]} = $node2;
- my $node_num = Node_v_get($node2);
- $Nodes{$node_num} = $a[1];
- } else {
- $node2 = $Cities{$a[1]};
- }
- # Add edges
- Node_addedge($node1,$node2,$a[2]);
- Node_addedge($node2,$node1,$a[2]);
- }
-}
-
-
-
-sub print_near {
- my $city = shift;
- if (exists $Cities{$city}) {
- my $node = $Cities{$city};
- print "Cities near $city : ";
- my $adj = Node_adj_get($node);
- while (defined($adj)) {
- my $anode = Edge_node_get($adj);
- my $v = Node_v_get($anode);
- print $Nodes{$v},", ";
- $adj = Edge_next_get($adj);
- }
- }
- print "\n";
-}
-read_cities("cities");
-print_near("Denver");
-print_near("Las Vegas");
-
-</pre></blockquote>
-This produces the following output :<p>
-<p>
-<blockquote><pre>Cities near Denver : Moab, Kansas City, Santa Fe, Cheyenne, Albuquerque,
-Cities near Las Vegas : Flagstaff, Los Angeles, Moab, Salt Lake City,
-
-</pre></blockquote>
-In this example, we are using the same functions as before, but we are now introducing two Perl hash tables. The <tt>%Cities</tt> hash is used to associate city names with a corresponding node in the graph. The <tt>%Nodes</tt> hash does exactly the opposite---mapping node numbers back to the names of cities. Both of these will come in quite handy for mapping things between the Perl world and the C world later.<p>
-<p>
-Before proceeding, let's stop and summarize what we have done. Given a couple of very simple C data structures for a graph, we have written a program that can read in a mileage table, construct a weighted graph of the data and print out a list of the cities that are nearby other cities. Yet, the C code knows nothing about the Perl interface or this whole mileage program we've built up around it. While we could have written the entire program in C, we would have had to write a main program, some code to read the input file, and a hash table structure to keep track of the mapping between nodes and cities. Perl, on the other hand, is very good at managing these tasks.<p>
-<a name="n6"></a><h2> Accessing arrays and other strange objects</h2>
-Now let's add some new functionality to our graph program from the previous example. In this case, we'll add a depth-first search algorithm to see if two nodes are connected to each other (possibly through many other nodes in-between). <p>
-<p>
-We'll first add the following constants to the file <tt>graph.h</tt><p>
-<blockquote><pre>
-/* File : graph.h */
-...
-#define MAX_NODES 1000
-#define UNSEEN -1
-</pre></blockquote>
-<p>
-Now, a modified version of <tt>graph.c</tt> :<p>
-<p>
-<blockquote><pre>/* File : graph.c */
-/* Directed graph functions */
-
-#include <stdio.h>
-#include "graph.h"
-
-int node_count = 0; /* Number of nodes created */
-int seen[MAX_NODES]; /* Used by the search function */
-
-...
-
-/* Function to search for node with given vertex number */
-static int visit(Node *n,int v) {
- Edge *e;
-
- if (seen[n->v] != UNSEEN) return UNSEEN; /* Cycle detected */
- if (n->v == v) return 1; /* Match found */
- e = n->adj;
- while (e) {
- seen[n->v] = e->node->v;
- if (visit(e->node,v) > 0) return 1;
- e = e->next;
- }
- return 0;
-}
-
-
-/* Depth-first search for a given node */
-int Node_search(Node *start, int v) {
- int i;
-
- for (i = 0; i < node_count; i++)
- seen[i] = UNSEEN;
- return visit(start,v);
-}
-
-</pre></blockquote>
-The idea here is simple, the function <tt>Node_search()</tt> takes a starting node and starts looking for a node with given vertex. Upon startup, the search function clears an array of values indicating whether a node has been seen or not. While this array is primarily used to detect cycles, it can also be used to store the path between two nodes as we proceed through the algorithm. Upon exit, we can then use the array to figure out how we got between the starting and ending node. Of course, this leads us to the question of how we access this array in Perl.<p>
-<p>
-As a general rule, handling arrays is somewhat problematic since the mapping between arrays and pointers may not be what you expect (even in C) and there is not necessarily a natural mapping between arrays in C and arrays in Perl (for example, if we've got a C array with 1 million elements in it, we almost certainly wouldn't want to convert it to a Perl array!).<p>
-<p>
-To access our array, we will write a C helper function that allows us to access invidual elements. However, rather than adding this function to the C code, we can insert it directly into our SWIG interface file. We will also strip the function names out of the <tt>.c</tt> file and put their prototypes in the header file : <p>
-<p>
-<blockquote><pre>%module graph
-%{
-#include "graph.h"
-%}
-%include graph.h
-
-%inline %{
-/* Get seen value for a particular node */
-int get_seen(int index) {
- extern int node_count;
- extern int seen[];
- if ((index < 0) || (index >= node_count)) return -1;
- else return seen[index];
-}
-%}
-</pre></blockquote>
-<p>
-This interface file illustrates one of the key points about SWIG--even though SWIG uses C syntax, wrapping arbitrary C code doesn't always result in a good interface. Almost any significant package will require the use of a few "helper" functions to get at certain data structures or to change the way in which a function is called. <p>
-<p>
-With our new C search function, we can now write a Perl function to find a route between two cities. This function simply takes the names of two cities, uses the <tt>Cities</tt> hash to look up their nodes and calls the C <tt>Node_search()</tt> function. Afterwards, we walk through the <tt>seen[]</tt> array using our helper function and print the route.<p>
-<blockquote><pre>
-sub find_route {
- my $start = shift;
- my $dest = shift;
- # Lookup nodes from names
- if ((!exists $Cities{$start}) || (!exists $Cities{$dest})) {
- return;
- }
- my $node1 = $Cities{$start};
- my $node2 = $Cities{$dest};
- print "$start --> $dest :\n";
-
- # Depth first search for a route between cities
- my $found = Node_search($node1,Node_v_get($node2));
- if ($found) {
- $v = Node_v_get($node1);
- while ($v != $UNSEEN) {
- print " $Nodes{$v}\n";
- $v = get_seen($v);
- }
- } else {
- print " You can't get there from here\n";
- }
-}
-
-read_cities("cities");
-find_route("Salt Lake City","Denver");
-</pre></blockquote>
-<p>
-Of course, depth first search isn't very good at finding an optimal route---obviously this output must be the very scenic route!<p>
-<p>
-<blockquote><pre>Salt Lake City --> Denver :
- Salt Lake City
- Twin Falls
- Boise
- Portland
- Eugene
- San Francisco
- Los Angeles
- Las Vegas
- Flagstaff
- Albuquerque
- Santa Fe
- Durango
- Moab
- Denver
-</pre></blockquote>
-<a name="n7"></a><h2> Implementing methods in Perl</h2>
-Obviously, our depth search algorithm isn't so useful in this specific application. Perhaps we would like to try a breadth-first search algorithm instead. We could choose to write it in C, but the breadth first search algorithm depends on the use of a queue to hold the list of nodes to visit. Thus, we'd have to write a queue data structure first. However, a Perl array smells alot like a queue if we manipulate it in the right way. So we can use Perl to come up with a quick and dirty breadth first search without dropping down into C :<p>
-<p>
-<blockquote><pre>%visit = ();
-sub breadth_search {
- my $node1 = shift;
- my $node2 = shift;
- my @queue;
- %visit = ();
- # Put starting node into queue
- push @queue, $node1;
- $visit{Node_v_get($node1)} = Node_v_get($node1);
- while (@queue) { # Loop until queue is empty
- my $n = shift @queue; # Pop off an node
- my $nv = Node_v_get($n);
- return 1 if ($$n == $$node2); # Exit if we found the destination
- # Put children onto the queue
- my $e = Node_adj_get($n);
- while (defined($e)) {
- my $m = Edge_node_get($e);
- my $v = Node_v_get($m);
- if (!exists $visit{$v}) {
- push @queue, $m;
- $visit{$v} = $nv;
- }
- $e = Edge_next_get($e);
- }
- }
- return 0;
-}
-
-sub find_route {
- my $start = shift;
- my $dest = shift;
- # Lookup nodes from names
- return if ((!exists $Cities{$start}) || (!exists $Cities{$dest}));
- print "$start --> $dest :\n";
- my $node1 = $Cities{$start};
- my $node2 = $Cities{$dest};
- my $found = breadth_search($node1,$node2);
- my @path;
- if ($found) {
- my $v = Node_v_get($node2);
- delete $visit{Node_v_get($node1)};
- while (exists($visit{$v})) {
- unshift @path,$Nodes{$v};
- $v = $visit{$v};
- }
- unshift @path,$start;
- foreach $c (@path) { print " $c\n";}
- } else {
- print " You can't get there from here\n";
- }
-}
-</pre></blockquote>
-<p>
-Our Perl implementation creates a queue using an array and manipulating it with shift and push operations. The global hash <tt>%visit</tt> is used to detect cycles and to determine how we got to each node. When we find a route, we can march backwards through the route to determine the entire path. When we run our new code, we get the following :<p>
-<p>
-<blockquote><pre>find_route("Salt Lake City", "Denver");
-Salt Lake City --> Denver :
- Salt Lake City
- Cheyenne
- Denver
-
-</pre></blockquote>
-Clearly this is a more efficient route--although admittedly not very scenic. If we wanted to get even more serious, we could add a priority search based on mileages. Later on we might implement these features in C for better performance. Either way, it is reasonably easy to manipulate complex structures in Perl and to mix them with C code (well, with a little practice perhaps). <p>
-<a name="n8"></a><h2> Shadow classes</h2>
-By now, you've probably noticed that examples have been using alot of accessor functions to get at the members of our <tt>Node</tt> and <tt>Edge</tt> structures. This tends to make the Perl code look rather cluttered (well, more than normal Perl code in any case) and it isn't very object oriented.<p>
-<p>
-With a little magic, SWIG can turn C structs and C++ classes into fully functional Perl classes that work in a more-or-less normal fashion. This transformation is done by writing an additional Perl layer that builds Perl classes on top of the low-level SWIG interface. These Perl classes are said to "shadow" an underlying C/C++ class. <p>
-<p>
-To have SWIG create shadow classes, use the <tt>-shadow </tt>option :<p>
-<p>
-<blockquote><pre>% swig -perl5 -shadow graph.i
-</pre></blockquote>
-<p>
-This will produce the same files as before except that the <tt>.pm</tt> file will now contain significantly more supporting Perl code. While there are some rather subtle aspects of this transformation, for now we'll omit the details and illustrate the changes in an example first (the use of shadow classes has been underlined)<p>
-<p>
-<blockquote><pre># Read a file with cities into a graph
-# Uses shadow classes
-
-use graph;
-package graph;
-
-%Cities = (); # Hash table mapping cities to nodes
-%Nodes = (); # Mapping of Node indicies to cities
-
-sub read_cities {
- my $filename = shift;
- open(CITIES,$filename);
- while (<CITIES>) {
- chop;
- my @a = split(/, +/);
- my $node1;
- my $node2;
- # Check to see if a given city is already a node
- if (!exists $Cities{$a[0]}) {
- $node1 = new_Node();
- $Cities{$a[0]} = $node1;
- $Nodes{$node1->{v}} = $a[0]; # Note access of `v'
- } else {
- $node1 = $Cities{$a[0]};
- }
- if (!exists $Cities{$a[1]}) {
- $node2 = new_Node;
- $Cities{$a[1]} = $node2;
- $Nodes{$node2->{v}} = $a[1];
- } else {
- $node2 = $Cities{$a[1]};
- }
- # Add edges
- Node_addedge($node1,$node2,$a[2]);
- Node_addedge($node2,$node1,$a[2]);
- }
-}
-
-%visit;
-sub breadth_search {
- my $node1 = shift;
- my $node2 = shift;
- my @queue;
- %visit = ();
- my $dest = $node2->{v};
- # Put starting node into queue
- push @queue, $node1;
- $visit{$node1->{v}} = $node1->{v};
- while (@queue) {
- my $n = shift @queue;
- return 1 if ($n->{v} == $node2->{v});
- # Put children onto the queue
- my $e = $n->{adj};
- while (defined($e)) {
- if (!exists $visit{$e->{node}->{v}}) {
- push @queue, $e->{node};
- $visit{$e->{node}->{v}} = $n->{v};
- }
- $e = $e->{next};
- }
- }
- return 0;
-}
-
-sub find_route {
- my $start = shift;
- my $dest = shift;
- # Lookup nodes from names
- return if ((!exists $Cities{$start}) || (!exists $Cities{$dest}));
- print "$start --> $dest :\n";
- my $node1 = $Cities{$start};
- my $node2 = $Cities{$dest};
- my $found = breadth_search($node1,$node2);
- my @path;
- if ($found) {
- my $v = $node2->{v};
- delete $visit{$node1->{v}};
- while (exists($visit{$v})) {
- unshift @path,$Nodes{$v};
- $v = $visit{$v};
- }
- unshift @path,$start;
- foreach $c (@path) {
- print " $c\n";
- }
- } else {
- print " You can't get there from here\n";
- }
-}
-read_cities("cities");
-
-find_route("Salt Lake City","Denver");
-</pre></blockquote>
-<p>
-For the most part, the code is the same except that we can now access members of complex data structures using <tt>-></tt> instead of the low level accessor functions. like before. However, this example is only scratching the surface of what can be done with shadow classes...keep reading.<p>
-<a name="n9"></a><h2> Getting serious</h2>
-Now that we've got a very simple example working, it's time to get really serious. Suppose that in addition to working with the mileage data of various cities, we want to make a graphical representation from geographical data (lattitude/longitude). To do this, we'll use SWIG to glue together a bunch of stuff. First, for the purposes of illustration, let's create a new C data structure for holding a geographical location with the assumption that we might want to use it in some C functions later :<p>
-<p>
-<blockquote><pre>/* File : location.h */
-/* Data structure for holding longitude and lattitude information */
-
-typedef struct Location {
- char *name;
- double lat_degrees;
- double lat_minutes;
- double lat_seconds;
- char lat_direction;
- double long_degrees;
- double long_minutes;
- double long_seconds;
- char long_direction;
-} Location;
-
-extern Location *new_Location(char *name);
-
-</pre></blockquote>
-We also probably want a C function for creating one of these objects:<p>
-<p>
-<blockquote><pre>/* File : location.c */
-#include <string.h>
-
-/* Make a new location */
-Location *new_Location(char *name) {
- Location *l;
- l = (Location *) malloc(sizeof(Location));
- l->name = (char *) malloc(strlen(name)+1);
- strcpy(l->name,name);
- return l;
-}
-</pre></blockquote>
-<p>
-Now let's make an interface file for this module :<p>
-<blockquote><pre>
-// File : location.i
-%module location
-%{
-#include "location.h"
-%}
-
-%include location.h
-
-</pre></blockquote>
-We could use this interface file to make an entirely new Perl5 module or we can combine it with the graph module. In this latter case, we simply need to put "<tt>%include location.i</tt>" in the file <tt>graph.i</tt>.<p>
-<p>
-Now, finally, we could write a Perl function to read data in the following format :<p>
-<p>
-<em>Geographic data</em><p>
-<blockquote><pre>sub read_locations {
- my $filename = shift;
- open(LOCATIONS,$filename);
- while (<LOCATIONS>) {
- chop;
- my @a = split(/, +/);
- my $loc;
- # Check to see if this is a city I know about
- if (exists $Cities{$a[0]}) {
- # Create a new location
- $loc = new_Location($a[0]);
- my @coords = split(' ',$a[1]);
- # A nice way to assign attributes to an object
- %$loc = (lat_degrees => $coords[0],
- lat_minutes => $coords[1],
- lat_seconds => $coords[2],
- lat_direction => $coords[3],
- long_degrees => $coords[4],
- long_minutes => $coords[5],
- long_seconds => $coords[6],
- long_direction => $coords[7]);
- my $v = $Cities{$a[0]}->{v};
- $Locations{$v} = $loc;
- }
- }
- close LOCATIONS;
-}
-</pre></blockquote>
-Again, we are using shadow classes which are allowing us to assign all of the attributes of a C structure in the same way as one would create a Perl hash table. We have also created the <tt>%Locations</tt> hash to associate node numbers with a given location object.<p>
-<p>
-Of course, having locations isn't too useful without a way to look at them so we'll grab the public domain <tt>gd</tt> library by Thomas Boutell. First, we'll write a simple C function to draw two locations and draw a line between them (some code has been omitted for clarity) :.<p>
-<p>
-<blockquote><pre>/* File : plot.c */
-#include <gd.h>
-#include <gdfonts.h>
-#include "location.h"
-double xmin,ymin,xmax,ymax; /* Plotting range */
-
-/* Make a plot of two locations with a line between them */
-void plot_cities(gdImagePtr im, Location *city1, Location *city2,
- int color) {
-...
- /* Convert the two locations into screen coordinates (bunch `o math) */
-...
- /* Draw the cities */
- gdImageString(im,gdFontSmall,...)
- gdImageString(im,gdFontSmall,...)
- gdImageLine(im,ix1,height-iy1,ix2,height-iy2,color);
-}
-</pre></blockquote>
-<p>
-Next, we'll wrap a few critical gd functions into Perl. We don't need the entire library so there's not much sense in wrapping the whole thing (it's easy enough to do if you really want to of course). We'll just wrap a couple of functions to illustrate how it can be used (one might also consider using the already existing gd module for Perl as well). <p>
-<p>
-<blockquote><pre>%module gd
-%{
-#include "gd.h"
-%}
-typedef struct gdImageStruct gdImage;
-typedef gdImage * gdImagePtr;
-
-/* Functions to manipulate images. */
-gdImagePtr gdImageCreate(int sx, int sy);
-int gdImageColorAllocate(gdImagePtr im, int r, int g, int b);
-%inline %{
- /* Shortcut for dumping a file */
- void dump_gif(gdImagePtr im, char *filename) {
- FILE *f;
- f = fopen(filename, "w");
- gdImageGif(im,f);
- fclose(f);
- }
-%}
-
-</pre></blockquote>
-We can now slap everything together using a new interface file like this. we'll keep the old graph module name so our existing scripts still work :<p>
-<blockquote><pre>
-// File : package.i
-%module graph
-%include graph.i // The original graph program
-%include location.i // The location data structure and functions
-%include gd.i // gd module
-%include plot.c // Function to plot cities
-</pre></blockquote>
-<p>
-Whew! After all of that work, we can do the following :<p>
-<p>
-<blockquote><pre>read_cities("cities");
-read_locations("locations");
-
-# Create a new image with gd
-$im = gdImageCreate(500,500);
-$white = gdImageColorAllocate($im,255,255,255);
-$black = gdImageColorAllocate($im,0,0,0);
-
-# Set plotting range (variables in the C code)
-$xmin = -130;
-$xmax = -90;
-$ymin = 30;
-$ymax = 50;
-
-# Make a plot of the entire graph
-@loc = each %Cities;
-while (@loc) {
- my $city = $loc[0];
- my $node = $Cities{$city};
- if (exists $Locations{$node->{v}}) {
- my $loc1 = $Locations{$node->{v}};
- my $e = $node->{adj};
- while (defined($e)) {
- if (exists $Locations{$e->{node}->{v}}) {
- my $loc2 = $Locations{$e->{node}->{v}};
- plot_cities($im,$loc1,$loc2,$black);
- }
- $e = $e->{next};
- }
- }
- @loc = each %Cities;
-}
-# Dump out a GIF file
-dump_gif($im,"test.gif");
-</pre></blockquote>
-<p>
-When run, we now get the following :<p>
-<p><center><img src="ch8.2.png"></center><p>
-<p>
-<p>
-Not too bad for just a little work....<p>
-<a name="n10"></a><h2> Wrapping C libraries and other packages</h2>
-SWIG can be used to build Perl interfaces to existing C libraries and packages. The general strategy for doing this is as follows :<p>
-<p>
-<ul>
-<li>Locate important header files for the package.
-<li>Copy them into a SWIG interface file.
-<li>Edit the interface file by removing problematic declarations, unneeded functions, and other clutter (this can often be found by just running SWIG).
-<li>Add support functions to improve the interface.
-</ul>
-<p>
-While SWIG can sometimes be used to simply process a raw header file, the results aren't always what you would expect. By working with a separate interface file, you get an opportunity to clean things up. If you're using a stable package, chances are that it's not going to change suddenly so there is really little problem in doing this. To illustrate the process, we will build a Perl5 interface to MATLAB in the next example.<p>
-<a name="n11"></a><h2> Building a Perl5 interface to MATLAB</h2>
-To illustrate the process, we can build a Perl5 interface to MATLAB by wrapping its C API. The MATLAB system consists of the MATLAB engine, and library of functions for creating and manipulating matrices, and a collection of utility function. A full description can be found in the "External Interface Guide" provided with MATLAB. Even if you don't have MATLAB, this section can provide some ideas on how to handle other libraries.<p>
-<a name="n33"></a><h3> The MATLAB engine interface</h3>
-The first step in building an interface will be to provide access to the MATLAB engine. This is a separate process that runs in the background, but we need to have some mechanism for starting it and issuing commands. The following functions are defined in the MATLAB interface.,<p>
-<p>
-<blockquote><pre><tt>int engClose(Engine *ep);
-int engEvalString(Engine *ep, char *string);
-Matrix *engGetMatrix(Engine *ep, char *name);
-int engPutMatrix(Engine *ep, Matrix *mp);
-Engine *engOpen(char *startcommand);
-void engOutputBuffer(Engine *ep, char *p, int size);
-
-</tt></pre></blockquote>
-While we could wrap these directly, each function requires an object "Engine". They could be a little annoying to use in Perl since we would have to pass a pointer to the engine with every command. This probably isn't necessary or desired. Thus, we could write some wrappers around these to produce a better interface as follows :<p>
-<p>
-<blockquote><pre>// engine.i : SWIG file for MATLAB engine
-%{
-#define BUFFER_SIZE 32768
-static Engine *eng = 0;
-static char ml_output[BUFFER_SIZE]; /* Result Buffer */
-%}
-
-%inline %{
-
-
-/* Initialize the MATLAB engine */
-int init(void) {
- if (eng) return -1; /* Already open */
- if (!(eng = engOpen("matlab42"))) {
- fprintf(stderr,"Unable to open matlab.\n");
- return -1;
- }
- engOutputBuffer(eng,ml_output,BUFFER_SIZE);
- return 0;
-}
-/* Execute a MATLAB command */
-char *matlab(char *c) {
- if (!eng) return "not initialized!";
- engEvalString(eng, c);
- return &ml_output[0];
-}
-
-/* Get a matrix from MATLAB */
-Matrix *GetMatrix(char *name) {
- if (!eng) return (Matrix *) 0;
- return(engGetMatrix(eng,name));
-}
-
-/* Send a matrix to MATLAB */
-int PutMatrix(Matrix *m) {
- if (!eng) return -1;
- return(engPutMatrix(eng,m));
-}
-%}
-
-</pre></blockquote>
-<a name="n34"></a><h3> Wrapping the MATLAB matrix functions</h3>
-Next, we need to build an interface to the MATLAB matrix manipulation library. This library contains about 30 functions to manipulate both real and complex valued matrices. Here we will only consider real-valued matrices. To provide access to the matrices, we'll write a different interface file with a list of the functions along with a few helper functions.<p>
-<blockquote><pre>
-//
-// mx.i : SWIG file for MATLAB matrix manipulation
-%inline %{
-/* Get an element from a matrix */
-double getr(Matrix *mat, int i, int j) {
- double *pr;
- int m;
- pr = mxGetPr(mat);
- m = mxGetM(mat);
- return pr[m*j + i];
-}
-/* Set an element of a matrix */
-void setr(Matrix *mat, int i, int j, double val) {
- double *pr;
- int m;
- pr = mxGetPr(mat);
- m = mxGetM(mat);
- pr[m*j + i] = val;
-}
-%}
-
-/* Now some MATLAB command */
-Matrix *mxCreateFull(int m, int n, int ComplexFlag);
-int mxGetM(Matrix *mat);
-int mxGetN(Matrix *mat);
-char *mxGetName(Matrix *mat);
-void mxSetName(Matrix *mat, char *name);
-double *mxGetPr(Matrix *mat);
-void mxSetPr(Matrix *mat, double *pr);
-double mxGetScalar(Matrix *mat);
-void mxFreeMatrix(Matrix *pm);
-</pre></blockquote>
-<a name="n35"></a><h3> Putting it all together</h3>
-Finally we are ready to put our interface together. There is no need to build a big monolithic interface file--we can simply build it up in pieces :<p>
-<p>
-<blockquote><pre>// matlab.i
-// Simple SWIG interface to MATLAB
-%module matlab
-%{
-#include "engine.h"
-%}
-%include engine.i
-%include mx.i
-</pre></blockquote>
-<p>
-Our module can be compiled as follows :<p>
-<p>
-<blockquote><pre>unix > swig -perl5 matlab.i
-unix > gcc -c matlab_wrap.c -I/usr/local/lib/perl5/arch-osname/5.003/CORE -Dbool=char
- -I$(MATLAB)/extern/include
-unix > ld -shared matlab_wrap.o -L$(MATLAB)/extern/lib -lmat -o matlab.so
-
-</pre></blockquote>
-Where<tt> $(MATLAB) </tt>is the location of the MATLAB installation (you may have to dig for this).<p>
-<p>
-With our new MATLAB module, we can now write Perl scripts that issue MATLAB commands. For example :<p>
-<p>
-<blockquote><pre>use matlab;
-matlab::init();
-matlab::matlab("x = -8:.25:8; \
- y = x; \
- [X,Y] = meshgrid(x,y); \
- R = sqrt(X.^2 + Y.^2)+eps; \
- Z = sin(R)./R; \
- mesh(Z); ");
-
-</pre></blockquote>
-Creates a simple 3D surface plot.<p>
-<a name="n36"></a><h3> Graphical Web-Statistics in Perl5</h3>
-Now, lets use our MATLAB module to generate plots of web-server hits for a given month. To do this, we'll use our MATLAB module, and create a special purpose function for processing days and hours. <p>
-<p>
-<blockquote><pre>// Simple C function for recording a hit
-%module webgraph
-%inline %
- void hit(double *m, int day, int hour) {
- if ((day >= 0) && (day <= 31)) {
- *(m+24*(day-1)+hour) += 1.0;
- }
- }
-%}
-
-</pre></blockquote>
-While we could write this function in Perl, it will be much faster in C. If we're processing a huge file, then the extra bit of performance will help us out. Once compiled, we can now write a Perl5 script like the following :<p>
-<p>
-<blockquote><pre>use matlab;
-use webgraph;
-
-# Initialize matlab engine
-matlab::init();
-# Make a matrix for all hits
-$m_all = matlab::mxCreateFull(24,31,0);
-matlab::mxSetName($m_all,"all");
-$all = matlab::mxGetPr($m_all); # Get double * of Matrix
-
-foreach $file (@ARGV) {
- open(FILE,$file);
- print "Processing ",$file,"\n";
- while (<FILE>) {
- @fields = split(/\s+/, $_);
- next if ($fields[8] != 200);
- @datetime = split(/\[|\/|:/, $fields[3]);
- if ($datetime[2] =~ /Apr/) {
- webgraph::hit($all, $datetime[1],$datetime[4]);
- }
- }
- # Dump temporary results
-} #foreach
-matlab::PutMatrix($m_all);
-matlab::matlab("figure(1); \
- surf(all); \
- view(40,40); \
- shading interp; \
- title('All hits'); \
- set(gca,'xlabel',text(0,0,'Day')); \
- set(gca,'ylabel',text(0,0,'Hour')); \
- print -dgif8 stats_all.gif");
-
-</pre></blockquote>
-When run on the web-server logs for the University of Utah, this script produces the following GIF file (showing hits per hour) :<p>
-<p><center><img src="ch8.3.png"></center><p>
-<p>
-<p>
-<a name="n12"></a><h2> Handling output values (the easy way)</h2>
-Some C libraries rely on functions that return values in their arguments. For example :<p>
-<p>
-<blockquote><pre>void fadd(double a, double b, double *result) {
- *result = a+b;
-}
-
-</pre></blockquote>
-By default, SWIG does not handle this case (leaving it up to you to figure out what to do about the <tt>result</tt> parameter). However, this problem is easily fixed using the <tt>typemaps.i</tt> library file (see the Typemaps chapter for more information). For example :<p>
-<p>
-<blockquote><pre>// SWIG interface file with output arguments
-%module example
-
-%include typemaps.i // Load the typemaps librayr
-%apply double *OUTPUT {double *result}; // Make "result" an output parameter
-
-void fadd(double a, double b, double *result);
-</pre></blockquote>
-<p>
-When used in a Perl script, the fadd function now takes 2 parameters and returns the result.<p>
-<p>
-<blockquote><pre>$a = fadd(3,4); # $a gets the value of double *result
-
-</pre></blockquote>
-When multiple output arguments are involved, a Perl array of values will be returned instead. It is also possible to use Perl references as function values. This is done as shown :<p>
-<p>
-<blockquote><pre>// SWIG interface file with output arguments
-%module
-%include typemaps.i
-
-%apply double *REFERENCE {double *result}; // Make "result" a Perl reference
-
-void fadd(double a, double b, double *result);
-
-</pre></blockquote>
-Now in a Perl script, the function works like this :<p>
-<p>
-<blockquote><pre>$c = 0.0; # Variable for holding the result
-fadd(3,4,\$c); # fadd() places the result in $c
-
-</pre></blockquote>
-In addition to handling pointers as output values or references, two other methods are available. The <tt>INPUT</tt> method indicates that a pointer is an input value and the <tt>BOTH</tt> method indicates that a pointer is both an input and output value. These would be specified as follows :<p>
-<p>
-<blockquote><pre>%apply double *INPUT {double *in}; // double *in is an input value
-%apply double *BOTH {double *r}; // double *r is both an input/output value
-
-</pre></blockquote>
-This processing of datatypes is built using SWIG's typemap mechanism. The details of typemaps is described shortly although the <tt>typemaps.i</tt> library already includes a variety of useful typemaps ready for use.<p>
-<a name="n13"></a><h2> Exception handling </h2>
-The SWIG <tt>%except</tt> directive can be used to create a user-definable exception handler for converting exceptions in your C/C++ program into Perl exceptions. The chapter on exception handling contains more details, but suppose you have a C++ class like the following :<p>
-<blockquote><pre>
-class RangeError {}; // Used for an exception
-
-class DoubleArray {
- private:
- int n;
- double *ptr;
- public:
- // Create a new array of fixed size
- DoubleArray(int size) {
- ptr = new double[size];
- n = size;
- }
- // Destroy an array
- ~DoubleArray() {
- delete ptr;
- }
- // Return the length of the array
- int length() {
- return n;
- }
-
- // Get an item from the array and perform bounds checking.
- double getitem(int i) {
- if ((i >= 0) && (i < n))
- return ptr[i];
- else
- throw RangeError();
- }
-
- // Set an item in the array and perform bounds checking.
- void setitem(int i, double val) {
- if ((i >= 0) && (i < n))
- ptr[i] = val;
- else {
- throw RangeError();
- }
- }
- };
-</pre></blockquote>
-<p>
-The functions associated with this class can throw a range exception for an out-of-bounds array access. We can catch this in our Perl extension by specifying the following in an interface file :<p>
-<p>
-<blockquote><pre>%except(perl5) {
- try {
- $function // Gets substituted by actual function call
- }
- catch (RangeError) {
- croak("Array index out-of-bounds");
- }
-}
-
-</pre></blockquote>
-Now, when the C++ class throws a RangeError exception, our wrapper functions will catch it, turn it into a Perl exception, and allow a graceful death as opposed to just having some sort of mysterious program crash. Since SWIG's exception handling is user-definable, we are not limited to C++ exception handling. It is also possible to write a language-independent exception handler that works with other scripting languages. Please see the chapter on exception handling for more details.<p>
-<a name="n14"></a><h2> Remapping datatypes with typemaps</h2>
-While SWIG does a reasonable job with most C/C++ datatypes, it doesn't always do what you want. However, you can remap SWIG's treatment of just about any datatype using a typemap. A typemap simply specifies a conversion between Perl and C datatypes and can be used to process function arguments, function return values, and more. A similiar mechanism is used by the xsubpp compiler provided with Perl although the SWIG version provides many more options.<p>
-<a name="n37"></a><h3> A simple typemap example</h3>
-The following example shows how a simple typemap can be written :<p>
-<p>
-<blockquote><pre>%module example
-
-%typemap(perl5,in) int {
- $target = (int) SvIV($source);
- printf("Received an integer : %d\n", $target);
-}
-...
-extern int fact(int n);
-
-</pre></blockquote>
-Typemap specifications require a language name, method name, datatype, and conversion code. For Perl5, "perl5" should be used as the language name. The "in" method refers to the input arguments of a function. The `int' datatype tells SWIG that we are remapping integers. The conversion code is used to convert from a Perl scalar value to the corresponding datatype. Within the support code, the variable<tt> $source</tt> contains the source data (a Perl object) and <tt>$target</tt> contains the destination of the conversion (a C local variable). <p>
-<p>
-When this example is used in Perl5, it will operate as follows :<p>
-<p>
-<blockquote><pre>use example;
-$n = example::fact(6);
-print "$n\n";
-...
-
-Output :
-Received an integer : 6
-720
-</pre></blockquote>
-<p>
-General discussion of typemaps can be found in the main SWIG users reference. <p>
-<a name="n38"></a><h3> Perl5 typemaps</h3>
-The following typemap methods are available to Perl5 modules<p>
-<p>
-<tt>%typemap(perl5,in)</tt> Converts Perl5 object to input function arguments.<p>
-<tt>%typemap(perl5,out)</tt> Converts function return value to a Perl5 value.<p>
-<tt>%typemap(perl5,varin)</tt> Converts a Perl5 object to a global variable.<p>
-<tt>%typemap(perl5,varout)</tt> Converts a global variable to a Perl5 object.<p>
-<tt>%typemap(perl5,freearg)</tt> Cleans up a function argument after a function call<p>
-<tt>%typemap(perl5,argout)</tt> Output argument handling<p>
-<tt>%typemap(perl5,ret) </tt>Clean up return value from a function.<p>
-<tt>%typemap(memberin)</tt> Setting of C++ member data (all languages).<p>
-<tt>%typemap(memberout)</tt> Return of C++ member data (all languages).<p>
-<tt>%typemap(perl5,check)</tt> Check value of input parameter.<p>
-<a name="n39"></a><h3> Typemap variables</h3>
-The following variables may be used within the C code used in a typemap :<p>
-<p>
-<tt>$source</tt> Source value of a conversion<p>
-<tt>$target</tt> Target of conversion (where result should be stored)<p>
-<tt>$type</tt> C datatype being remapped<p>
-<tt>$mangle</tt> Mangled version of datatype (for blessing objects)<p>
-<tt>$arg</tt> Function argument (when applicable).<p>
-<a name="n40"></a><h3> Name based type conversion</h3>
-Typemaps are based both on the datatype and an optional name attached to a datatype. For example :<p>
-<p>
-<blockquote><pre>%module foo
-
-// This typemap will be applied to all char ** function arguments
-%typemap(perl5,in) char ** { ... }
-
-// This typemap is applied only to char ** arguments named `argv'
-%typemap(perl5,in) char **argv { ... }
-
-</pre></blockquote>
-In this example, two typemaps are applied to the char ** datatype. However, the second typemap will only be applied to arguments named `argv'. A named typemap will always override an unnamed typemap.<p>
-<p>
-Due to the name matching scheme, typemaps do not follow typedef declarations. For example :<p>
-<p>
-<blockquote><pre>%typemap(perl5,in) double {
- ... get a double ...
-}
-
-double foo(double); // Uses the double typemap above
-typedef double Real;
-Real bar(Real); // Does not use the typemap above (double != Real)
-
-</pre></blockquote>
-Is is odd behavior to be sure, but you can work around the problem using the <tt>%apply</tt> directive as follows :<p>
-<p>
-<blockquote><pre>%typemap(perl5,in) double {
- ... get a double ...
-}
-double foo(double); // Uses the double typemap above
-
-typedef double Real;
-%apply double { Real }; // Apply the double typemap to Reals.
-Real bar(Real); // Uses the double typemap already defined.
-</pre></blockquote>
-<p>
-Named typemaps are extremely useful for managing special cases. It is also possible to use named typemaps to process output arguments (ie. function arguments that have values returned in them).<p>
-<a name="n41"></a><h3> Converting a Perl5 array to a char ** </h3>
-A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Perl5 array reference to be used as a char ** datatype.<p>
-<p>
-<blockquote><pre>%module argv
-
-// This tells SWIG to treat char ** as a special case
-%typemap(perl5,in) char ** {
- AV *tempav;
- I32 len;
- int i;
- SV **tv;
- if (!SvROK($source))
- croak("$source is not a reference.");
- if (SvTYPE(SvRV($source)) != SVt_PVAV)
- croak("$source is not an array.");
- tempav = (AV*)SvRV($source);
- len = av_len(tempav);
- $target = (char **) malloc((len+2)*sizeof(char *));
- for (i = 0; i <= len; i++) {
- tv = av_fetch(tempav, i, 0);
- $target[i] = (char *) SvPV(*tv,na);
- }
- $target[i] = 0;
-};
-
-// This cleans up our char ** array after the function call
-%typemap(perl5,freearg) char ** {
- free($source);
-}
-
-// Creates a new Perl array and places a char ** into it
-%typemap(perl5,out) char ** {
- AV *myav;
- SV **svs;
- int i = 0,len = 0;
- /* Figure out how many elements we have */
- while ($source[len])
- len++;
- svs = (SV **) malloc(len*sizeof(SV *));
- for (i = 0; i < len ; i++) {
- svs[i] = sv_newmortal();
- sv_setpv((SV*)svs[i],$source[i]);
- };
- myav = av_make(len,svs);
- free(svs);
- $target = newRV((SV*)myav);
- sv_2mortal($target);
-}
-
-// Now a few test functions
-%inline %{
-int print_args(char **argv) {
- int i = 0;
- while (argv[i]) {
- printf("argv[%d] = %s\n", i,argv[i]);
- i++;
- }
- return i;
-}
-
-// Returns a char ** list
-char **get_args() {
- static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
- return &values[0];
-}
-%}
-
-</pre></blockquote>
-When this module is compiled, our wrapped C functions can be used in a Perl script as follows :<p>
-<blockquote><pre>
-use argv;
-@a = ("Dave", "Mike", "John", "Mary"); # Create an array of strings
-argv::print_args(\@a); # Pass it to our C function
-$b = argv::get_args(); # Get array of strings from C
-print @$b,"\n"; # Print it out
-</pre></blockquote>
-<p>
-Of course, there are many other possibilities. As an alternative to array references, we could pass in strings separated by some delimeter and perform a splitting operation in C. <p>
-<a name="n42"></a><h3> Using typemaps to return values</h3>
-Sometimes it is desirable for a function to return a value in one of its arguments. A named typemap can be used to handle this case. For example :<p>
-<p>
-<blockquote><pre>%module return
-
-// This tells SWIG to treat an double * argument with name 'OutDouble' as
-// an output value.
-
-%typemap(perl5,argout) double *OutDouble {
- $target = sv_newmortal();
- sv_setnv($target, *$source);
- argvi++; /* Increment return count -- important! */
-}
-
-// If we don't care what the input value is, we can make the typemap ignore it.
-
-%typemap(perl5,ignore) double *OutDouble(double junk) {
- $target = &junk; /* junk is a local variable that has been declared */
-}
-
-// Now a function to test it
-%{
-/* Returns the first two input arguments */
-int multout(double a, double b, double *out1, double *out2) {
- *out1 = a;
- *out2 = b;
- return 0;
-};
-%}
-
-// If we name both parameters OutDouble both will be output
-
-int multout(double a, double b, double *OutDouble, double *OutDouble);
-...
-</pre></blockquote>
-<p>
-When output arguments are encountered, they are simply appended to the stack used to return results. This will show up as an array when used in Perl. For example :<p>
-<p>
-<blockquote><pre>@r = multout(7,13);
-print "multout(7,13) = @r\n";
-
-</pre></blockquote>
-<a name="n43"></a><h3> Accessing array structure members</h3>
-Consider the following data structure :<p>
-<p>
-<blockquote><pre>#define NAMELEN 32
-typedef struct {
- char name[NAMELEN];
- ...
-} Person;
-
-</pre></blockquote>
-By default, SWIG doesn't know how to the handle the name structure since it's an array, not a pointer. In this case, SWIG will make the array member readonly. However, member typemaps can be used to make this member writable from Perl as follows :<p>
-<p>
-<blockquote><pre>%typemap(memberin) char[NAMELEN] {
- /* Copy at most NAMELEN characters into $target */
- strncpy($target,$source,NAMELEN);
-}
-
-</pre></blockquote>
-Whenever a <tt>char[NAMELEN]</tt> type is encountered in a structure or class, this typemap provides a safe mechanism for setting its value. An alternative implementation might choose to print an error message if the name was too long to fit into the field.<p>
-<p>
-It should be noted that the <tt>[NAMELEN]</tt> array size is attached to the typemap. A datatype involving some other kind of array would be affected. However, we can write a typemap that will work for any array dimension as follows :<p>
-<blockquote><pre>
-%typemap(memberin) char [ANY] {
- strncpy($target,$source,$dim0);
-}
-
-</pre></blockquote>
-When code is generated, <tt>$dim0</tt> gets filled in with the real array dimension.<p>
-<a name="n44"></a><h3> Turning Perl references into C pointers</h3>
-A frequent confusion on the SWIG mailing list is errors caused by the mixing of Perl references and C pointers. For example, suppose you have a C function that modifies its arguments like this :<p>
-<p>
-<blockquote><pre>void add(double a, double b, double *c) {
- *c = a + b;
-}
-
-</pre></blockquote>
-A common misinterpretation of this function is the following Perl script :<p>
-<p>
-<blockquote><pre># Perl script
-$a = 3.5;
-$b = 7.5;
-$c = 0.0; # Output value
-add($a,$b,\$c); # Place result in c (Except that it doesn't work)
-</pre></blockquote>
-<p>
-Unfortunately, this does NOT work. There are many reasons for this, but the main one is that SWIG has no idea what a <tt>double *</tt> really is. It could be an input value, an output value, or an array of 2 million elements. As a result, SWIG leaves it alone and looks exclusively for a C pointer value (which is not the same as a Perl reference--well, at least note of the type used in the above script).<p>
-<p>
-However, you can use a typemap to get the desired effect. For example :<p>
-<p>
-<blockquote><pre>%typemap(perl5,in) double * (double dvalue) {
- SV* tempsv;
- if (!SvROK($source)) {
- croak("expected a reference\n");
- }
- tempsv = SvRV($source);
- if ((!SvNOK(tempsv)) && (!SvIOK(tempsv))) {
- croak("expected a double reference\n");
- }
- dvalue = SvNV(tempsv);
- $target = &dvalue;
-}
-
-%typemap(perl5,argout) double * {
- SV *tempsv;
- tempsv = SvRV($arg);
- sv_setnv(tempsv, *$source);
-}
-</pre></blockquote>
-<p>
-Now, if you place this before our add function, we can do this :<p>
-<p>
-<blockquote><pre>$a = 3.5;
-$b = 7.5;
-$c = 0.0;
-add($a,$b,\$c); # Now it works!
-print "$c\n";
-
-</pre></blockquote>
-You'll get the output value of "11.0" which is exactly what we wanted. While this is pretty cool, it should be stressed that you can easily shoot yourself in the foot with typemaps--of course SWIG is has never been too concerned about legislating morality....<p>
-<a name="n45"></a><h3> Useful functions</h3>
-When writing typemaps, it is necessary to work directly with Perl5 objects. This, unfortunately, can be a daunting task. Consult the "perlguts" man-page for all of the really ugly details. A short summary of commonly used functions is provided here for reference. It should be stressed that SWIG can be usef quite effectively without knowing any of these details--especially now that there are typemap libraries that can already been written.<p>
-<center>
-<img src="ch8.table.1.png"><br>
-<img src="ch8.table.2.png"><br>
-<img src="ch8.table.3.png"><br>
-<img src="ch8.table.4.png"><br>
-</center><p>
-<p>
-<a name="n46"></a><h3> Standard typemaps</h3>
-The following typemaps show how to convert a few common types of objects between Perl and C (and to give a better idea of how everything works). <p>
-<center>
-<img src="ch8.table.5.png"><br>
-<img src="ch8.table.6.png"><br>
-</center><p>
-<p>
-<a name="n47"></a><h3> Pointer handling</h3>
-SWIG pointers are represented as blessed references. The following functions can be used to create and read pointer values.<p>
-<center>
-<img src="ch8.table.7.png">
-</center><p>
-<a name="n48"></a><h3> Return values </h3>
-Return values are placed on the argument stack of each wrapper function. The current value of the argument stack pointer is contained in a variable <tt>argvi</tt>. Whenever a new output value is added, it is critical that this value be incremented. For multiple output values, the final value of <tt>argvi</tt> should be the total number of output values. <p>
-<p>
-The total number of return values should not exceed the number of input values unless you explicitly extend the argument stack. This can be done using the <tt>EXTEND()</tt> macro as in :<p>
-<p>
-<blockquote><pre>%typemap(perl5,argout) int *OUTPUT {
- if (argvi >= items) {
- EXTEND(sp,1); /* Extend the stack by 1 object */
- }
- $target = sv_newmortal();
- sv_setiv($target,(IV) *($source));
- argvi++;
-}
-</pre></blockquote>
-<a name="n15"></a><h2> The gory details on shadow classes</h2>
-Perl5 shadow classes are constructed on top of the low-level C interface provided by SWIG. By implementing the classes in Perl instead of C, we get a number of advantages :<p>
-<p>
-<ul>
-<li>The classes are easier to implement (after all Perl makes lots of things easier).
-<li>By writing in Perl, the classes tend to interact better with other Perl objects and programs.
-<li>You can modify the resulting Perl code without recompiling the C module.
-</ul>
-<p>
-Shadow classes are new in SWIG 1.1 and still somewhat experimental. The current implementation is a combination of contributions provided by Gary Holt and David Fletcher--many thanks!<p>
-<a name="n49"></a><h3> Module and package names</h3>
-When shadow classing is enabled, SWIG generates a low-level package named `modulec' where `module' is the name of the module you provided with the <tt>%module</tt> directive (SWIG appends a `c' to the name to indicate that it is the low-level C bindings). This low-level package is exactly the same module that SWIG would have created without the <tt>`-shadow</tt>' option, only renamed.<p>
-<p>
-Using the low-level interface, SWIG creates Perl wrappers around classes, structs, and functions. This collection of wrappers becomes the Perl module that you will use in your Perl code, not the low-level package (the original package is hidden, but working behind the scenes).<p>
-<a name="n50"></a><h3> What gets created?</h3>
-Suppose you have the following SWIG interface file :<p>
-<p>
-<blockquote><pre>%module vector
-struct Vector {
- Vector(double x, double y, double z);
- ~Vector();
- double x,y,z;
-};
-
-</pre></blockquote>
-When wrapped, SWIG creates the following set of low-level accessor functions.<p>
-<p>
-<blockquote><pre>Vector *new_Vector(double x, double y, double z);
-void delete_Vector(Vector *v);
-double Vector_x_get(Vector *v);
-double Vector_x_set(Vector *v, double value);
-double Vector_y_get(Vector *v);
-double Vector_y_set(Vector *v, double value);
-double Vector_z_get(Vector *v);
-double Vector_z_set(Vector *v, double value);
-
-</pre></blockquote>
-These functions can now be used to create a Perl shadow class that looks like this :<p>
-<p>
-<blockquote><pre>package Vector;
-@ISA = qw( vector );
-%OWNER = ();
-%BLESSEDMEMBERS = ();
-
-sub new () {
- my $self = shift;
- my @args = @_;
- $self = vectorc::new_Vector(@args);
- return undef if (!defined($self));
- bless $self, "Vector";
- $OWNER{$self} = 1;
- my %retval;
- tie %retval, "Vector", $self;
- return bless \%retval,"Vector";
-}
-
-sub DESTROY {
- my $self = shift;
- if (exists $OWNER{$self}) {
- delete_Vector($self));
- delete $OWNER{$self};
-}
-
-sub FETCH {
- my ($self,$field) = @_;
- my $member_func = "vectorc::Vector_${field}_get";
- my $val = &$member_func($self);
- if (exists $BLESSEDMEMBERS{$field}) {
- return undef if (!defined($val));
- my %retval;
- tie %retval,$BLESSEDMEMBERS{$field},$val;
- return bless \%retval, $BLESSEDMEMBERS{$field};
- }
- return $val;
-}
-
-sub STORE {
- my ($self,$field,$newval) = @_;
- my $member_func = "vectorc::Vector_${field}_set";
- if (exists $BLESSEDMEMBERS{$field}) {
- &$member_func($self,tied(%{$newval}));
- } else {
- &$member_func($self,$newval);
- }
-}
-</pre></blockquote>
-<p>
-Each structure or class is mapped into a Perl package of the same name. The C++ constructors and destructors are mapped into constructors and destructors for the package and are always named "new" and "DESTROY". The constructor always returns a tied hash table. This hash table is used to access the member variables of a structure in addition to being able to invoke member functions. The <tt>%OWNER</tt> and <tt>%BLESSEDMEMBERS</tt> hash tables are used internally and described shortly. <p>
-<p>
-To use our new shadow class we can simply do the following:<p>
-<p>
-<blockquote><pre># Perl code using Vector class
-$v = new Vector(2,3,4);
-$w = Vector->new(-1,-2,-3);
-
-# Assignment of a single member
-$v->{x} = 7.5;
-
-# Assignment of all members
-%$v = ( x=>3,
- y=>9,
- z=>-2);
-
-# Reading members
-$x = $v->{x};
-
-# Destruction
-$v->DESTROY();
-
-</pre></blockquote>
-<a name="n51"></a><h3> Object Ownership</h3>
-In order for shadow classes to work properly, it is necessary for Perl to manage some mechanism of object ownership. Here's the crux of the problem---suppose you had a function like this :<p>
-<p>
-<blockquote><pre>Vector *Vector_get(Vector *v, int index) {
- return &v[i];
-}
-
-</pre></blockquote>
-This function takes a Vector pointer and returns a pointer to another Vector. Such a function might be used to manage arrays or lists of vectors (in C). Now contrast this function with the constructor for a Vector object :<p>
-<p>
-<blockquote><pre>Vector *new_Vector(double x, double y, double z) {
- Vector *v;
- v = new Vector(x,y,z); // Call C++ constructor
- return v;
-}
-
-</pre></blockquote>
-Both functions return a Vector, but the constructor is returning a brand-new Vector while the other function is returning a Vector that was already created (hopefully). In Perl, both vectors will be indistinguishable---clearly a problem considering that we would probably like the newly created Vector to be destroyed when we are done with it.<p>
-<p>
-To manage these problems, each class contains two methods that access an internal hash table called <tt>%OWNER</tt>. This hash keeps a list of all of the objects that Perl knows that it has created. This happens in two cases: (1) when the constructor has been called, and (2) when a function implicitly creates a new object (as is done when SWIG needs to return a complex datatype by value). When the destructor is invoked, the Perl shadow class module checks the <tt>%OWNER</tt> hash to see if Perl created the object. If so, the C/C++ destructor is invoked. If not, we simply destroy the Perl object and leave the underlying C object alone (under the assumption that someone else must have created it).<p>
-<p>
-This scheme works remarkably well in practice but it isn't foolproof. In fact, it will fail if you create a new C object in Perl, pass it on to a C function that remembers the object, and then destroy the corresponding Perl object (this situation turns out to come up frequently when constructing objects like linked lists and trees). When C takes possession of an object, you can change Perl's owership by simply deleting the object from the <tt>%OWNER</tt> hash. This is done using the <tt>DISOWN </tt>method.<p>
-<p>
-<blockquote><pre># Perl code to change ownership of an object
-$v = new Vector(x,y,z);
-$v->DISOWN();
-</pre></blockquote>
-<p>
-To acquire ownership of an object, the <tt>ACQUIRE</tt> method can be used.<p>
-<p>
-<blockquote><pre># Given Perl ownership of a file
-$u = Vector_get($v);
-$u->ACQUIRE();
-
-</pre></blockquote>
-As always, a little care is in order. SWIG does not provide reference counting, garbage collection, or advanced features one might find in sophisticated languages.<p>
-<a name="n52"></a><h3> Nested Objects</h3>
-Suppose that we have a new object that looks like this :<p>
-<p>
-<blockquote><pre>struct Particle {
- Vector r;
- Vector v;
- Vector f;
- int type;
-}
-
-</pre></blockquote>
-In this case, the members of the structure are complex objects that have already been encapsulated in a Perl shadow class. To handle these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would look like this (along with some supporting code) :<p>
-<p>
-<blockquote><pre>package Particle;
-...
-%BLESSEDMEMBERS = (
- r => `Vector',
- v => `Vector',
- f => `Vector',
-);
-
-</pre></blockquote>
-When fetching members from the structure, <tt>%BLESSEDMEMBERS</tt> is checked. If the requested field is present, we create a tied-hash table and return it. If not, we just return the corresponding member unmodified.<p>
-<p>
-This implementation allows us to operate on nested structures as follows :<p>
-<blockquote><pre>
-# Perl access of nested structure
-$p = new Particle();
-$p->{f}->{x} = 0.0;
-%${$p->{v}} = ( x=>0, y=>0, z=>0);
-</pre></blockquote>
-<p>
-<a name="n53"></a><h3> Shadow Functions</h3>
-When functions take arguments involving a complex object, it is sometimes necessary to write a shadow function. For example :<p>
-<p>
-<blockquote><pre>double dot_product(Vector *v1, Vector *v2);
-
-</pre></blockquote>
-Since Vector is an object already wrapped into a shadow class, we need to modify this function to accept arguments that are given in the form of tied hash tables. This is done by creating a Perl function like this :<p>
-<p>
-<blockquote><pre>sub dot_product {
- my @args = @_;
- $args[0] = tied(%{$args[0]}); # Get the real pointer values
- $args[1] = tied(%{$args[1]});
- my $result = vectorc::dot_product(@args);
- return $result;
-}
-</pre></blockquote>
-<p>
-This function replaces the original function, but operates in an identical manner.<p>
-<a name="n54"></a><h3> Inheritance</h3>
-Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array in each class package. For example, if you have the following interface file :<p>
-<p>
-<blockquote><pre>// shapes.i
-// SWIG interface file for shapes class
-%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>
-The resulting, Perl wrapper class will create the following code :<p>
-<blockquote><pre>Package Shape;
-@ISA = (shapes);
-...
-Package Circle;
-@ISA = (shapes Shape);
-...
-Package Square;
-@ISA = (shapes Shape);
-
-</pre></blockquote>
-The <tt>@ISA</tt> array determines where to look for methods of a particular class. In this case, both the <tt>Circle</tt> and <tt>Square</tt> classes inherit functions from <tt>Shape</tt> so we'll want to look in the <tt>Shape</tt> base class for them. All classes also inherit from the top-level module <tt>shapes</tt>. This is because certain common operations needed to implement shadow classes are implemented only once and reused in the wrapper code for various classes and structures.<p>
-<p>
-Since SWIG shadow classes are implemented in Perl, it is easy to subclass from any SWIG generated class. To do this, simply put the name of a SWIG class in the <tt>@ISA</tt> array for your new class. However, be forewarned that this is not a trivial problem. In particular, inheritance of data members is extremely tricky (and I'm not even sure if it really works). <p>
-<a name="n55"></a><h3> Iterators</h3>
-With each class or structure, SWIG also generates a pair of functions to support Perl iterators. This makes it possible to use the <tt>keys</tt> and <tt>each</tt> functions on a C/C++ object. Iterators are implemented using code like this :<p>
-<p>
-<blockquote><pre>sub FIRSTKEY {
- my $self = shift;
- @ITERATORS{$self} = [`x','y','z', ];
- my $first = shift @{$ITERATORS{$self}};
- return $first;
-}
-
-sub NEXTKEY {
- my $self = shift;
- $nelem = scalar @{$ITERATORS{$self}};
- if ($nelem > 0) {
- my $member = shift @{$ITERATORS{$self}};
- return $member;
- } else {
- @ITERATORS{$self} = [`x','y','z', ];
- return ();
- }
-}
-</pre></blockquote>
-The <tt>%ITERATORS</tt> hash table maintains the state of each object for which the <tt>keys</tt> or <tt>each</tt> function has been applied to. The state is maintained by keeping a list of the member names.<p>
-<p>
-While iterators may be of limited use when working with C/C++ code, it turns out they can be used to perform an element by element copy of an object.<p>
-<p>
-<blockquote><pre>$v = new Vector(1,2,3);
-$w = new Vector(0,0,0);
-%$w = %$v; # Copy contents of v into w
-
-</pre></blockquote>
-However, this is not a deep copy so they probably works better with C than with C++.<p>
-<a name="n16"></a><h2> Where to go from here?</h2>
-The SWIG Perl5 module is constantly improving to provide better integration with Perl and to be easier to use. The introduction of shadow classes and typemaps in this release are one more step in that direction. The SWIG <tt>Examples</tt> directory contains more simple examples of building Perl5 modules. As always, suggestions for improving the Perl5 implementation are welcome.<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:01 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Preface.html b/swigweb/Doc1.1/HTML/Preface.html
deleted file mode 100644
index 47207f9..0000000
--- a/swigweb/Doc1.1/HTML/Preface.html
+++ /dev/null
@@ -1,83 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Preface</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1> Preface</h1><p><ul>
-<li> <a href="#n1">Introduction</a>
-<li> <a href="#n2">SWIG resources</a>
-<li> <a href="#n3">About this manual</a>
-<li> <a href="#n4">Credits</a>
-<li> <a href="#n5">What's new?</a>
-<li> <a href="#n6">Bug reports</a>
-<li> <a href="#n7">SWIG is free</a>
-</ul>
-
-<a name="n1"></a><h2> Introduction</h2>
-SWIG is a tool for solving problems.<p>
-<p>
-More specifically, SWIG is a simple tool for building interactive C, C++, or Objective-C programs with common scripting languages such as Tcl, Perl, and Python. Of course, more importantly, SWIG is a tool for making C programming more enjoyable and promoting laziness (an essential feature). SWIG is not part of an overgrown software engineering project, an attempt to build some sort of monolithic programming environment, or an attempt to force everyone to rewrite all of their code (ie. code reuse). In fact, none of these things have ever been a priority.<p>
-<p>
-SWIG was originally developed in the Theoretical Physics Division at Los Alamos National Laboratory for building interfaces to large materials science research simulations being run on the Connection Machine 5 supercomputer. In this environment, we were faced with the problems of working with huge amounts of data, complicated machines, and constantly changing code. As scientists, we needed a mechanism for building interactive programs that was extremely easy to use, could keep pace with code that was constantly changing, and didn't get in the way of the real problems that were being solved. Mainly, we just wanted to "cut the crap" and work on the real problems at hand.<p>
-<p>
-While SWIG was originally developed for scientific applications, it has become a general purpose tool that is being used in an increasing variety of other computing applications--in fact almost anything where C programming is involved. Some of the application areas that I am aware of include scientific applications, visualization, databases, semiconductor CAD, remote sensing and distributed objects. Development has been pragmatic in nature--features have been added to address interesting problems as they arise. Most of the really cool stuff has been contributed or suggested by SWIG's users. There has never really been a "grand" design to SWIG other than the goal of creating a practical programming tool that could be used in other applications.<p>
-<a name="n2"></a><h2> SWIG resources</h2>
-The official location of SWIG related material is<p>
-<blockquote><pre>
-http://www.cs.utah.edu/~beazley/SWIG
-</pre></blockquote>
-<p>
-This site contains the latest version of the software, users guide, and information regarding bugs, installation problems, and implementation tricks. The latest version of the software and related files are also available via anonymous ftp at <p>
-<p>
-<blockquote><pre>ftp://ftp.cs.utah.edu/pub/beazley/SWIG
-</pre></blockquote>
-<p>
-You can also subscribe to the SWIG mailing list by sending a message with the text "subscribe swig" to <p>
-<p>
-<blockquote><pre>majordomo@cs.utah.edu
-</pre></blockquote>
-<p>
-The mailing list often discusses some of the more technical aspects of SWIG along with information about beta releases and future work.<p>
-<a name="n3"></a><h2> About this manual</h2>
-This manual has been written in parallel with the development of SWIG because I hate black boxes and I don't like using software that is poorly documented. This manual attempts to describe all aspects of SWIG and how it can be used to solve interesting problems. Don't let the size scare you, SWIG can be quite easy to use. However, covering automatic code generation for four different scripting languages takes abit of explanation. SWIG can do quite a few interesting things that might not be so obvious so I hope that the manual can shed some light on many of these issues. The manual also serves as a general reference describing many of SWIG's implementation issues (I use the manual quite regularly myself).<p>
-<a name="n8"></a><h3> Prerequisites</h3>
-This manual assumes that you are interested in writing interactive C programs and that you have at least heard of scripting languages such as Tcl, Python, and Perl. A detailed knowledge of these scripting languages is not required although some familiarity certainly won't hurt. No prior experience with building C extensions to these languages is required---after all, this is what SWIG allows you to do automatically. However, I do assume that you are reasonably familiar with the use of compilers, linkers, and makefiles since making scripting language extensions is somewhat more complicated than writing a normal C program (although not significantly more complex).<p>
-<a name="n9"></a><h3> Organization of this manual</h3>
-The first few chapters of this manual describe SWIG in general and provide an overview of its capabilities. The remaining chapters are devoted to specific SWIG language modules and are self contained. Thus, if you are using SWIG to build Python interfaces, you can skip right to that chapter and find just about everything you need to know. So, in a sense, you are really getting 3 or 4 manuals in one.<p>
-<a name="n10"></a><h3> How to avoid reading the manual</h3>
-If you hate reading manuals, glance at the "Introduction" which contains a few simple examples and the overall philosophy. These examples contain about 95% of everything you need to know to use SWIG. After that, simply use the language-specific chapters for reference. The SWIG distribution also comes with a large directory of examples that illustrate how to do most kinds of things. <p>
-<a name="n4"></a><h2> Credits</h2>
-This work would certainly not be possible without the support of many people. I would like to acknowledge Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann at Los Alamos National Laboratory for allowing me to pursue this project and for being the first users. Patrick Tullmann at the University of Utah suggested the idea of automatic documentation generation. John Schmidt and Kurtis Bleeker at the University of Utah tested out the early versions. I'd also like to acknowledge Chris Johnson and the Scientific Computing and Imaging Group at the University of Utah for their continued support. John Buckman, Larry Virden, and Tom Schwaller provided valuable input on the first releases and improving the portability of SWIG. David Fletcher and Gary Holt have provided a great deal of input on improving SWIG's Perl5 implementation. I'd also like to thank Kevin Butler for his valuable input and contribution of a Windows NT port. Finally, I'd like to acknowledge all of the users who have braved the first few releases and have been instrumental in suggesting way to make SWIG more fun to use than I ever imagined possible.<p>
-<a name="n5"></a><h2> What's new?</h2>
-The following significant features are new in version 1.1<p>
-<p>
-<ul>
-<li>Support for typemaps (a mechanism for customizing SWIG).
-<li>Multiple inheritance.
-<li>Default/optional arguments.
-<li>Perl5 shadow classes.
-<li>Tcl8.0 module (uses the native Tcl8 object interface).
-<li>An entirely new documentation system.
-<li>Limited support for nested structures.
-<li>New object oriented Tcl interface.
-<li>User defined exception handling.
-<li>New directives for better library support (%inline, %extern %import)
-<li>Objective-C support.
-<li>Support for Windows-NT and Macintosh.
-<li>Lots of minor bug fixes to almost everything.
-</ul>
-<p>
-This release should be backwards compatible with interface files generated for SWIG 1.0. However, many things have changed in the SWIG C++ API so special purpose SWIG C++ extensions written for 1.0 will need to be modified.<p>
-<a name="n6"></a><h2> Bug reports</h2>
-While every attempt has been made to make SWIG bug-free, occasionally bugs will arrise. To report a bug, send mail to the SWIG mailing list at <tt>swig@cs.utah.edu</tt>. In your message, be as specific as possible, including (if applicable), error messages, tracebacks (if a core dump occurred), corresponding portions of the SWIG interface file used, and any important pieces of the SWIG generated wrapper code. I attempt to respond to all bug reports, but I can only fix bugs if I know about them.<p>
-<a name="n7"></a><h2> SWIG is free</h2>
-SWIG is a completely free package that you can use in any manner that you wish, including modification, redistribution, and use in commercial products. The only restriction on its use is that redistributions of the SWIG compiler should reproduce the SWIG copyright notice in the supporting documentation. The code generated by SWIG can be redistributed in any manner. On a more personal note, if you've used SWIG to make something cool, I'd like to find out more about it so that I can make SWIG better (and to satisfy my curiosity).<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:49 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Python.html b/swigweb/Doc1.1/HTML/Python.html
deleted file mode 100644
index 357ab53..0000000
--- a/swigweb/Doc1.1/HTML/Python.html
+++ /dev/null
@@ -1,2334 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>SWIG and Python</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>9 SWIG and Python</h1><p><ul>
-<li> <a href="#n1">Preliminaries</a>
-<li> <a href="#n2">Building Python Extensions under Windows 95/NT</a>
-<li> <a href="#n3">The low-level Python/C interface</a>
-<li> <a href="#n4">Python shadow classes</a>
-<li> <a href="#n5">About the Examples</a>
-<li> <a href="#n6">Solving a simple heat-equation</a>
-<li> <a href="#n7">Wrapping a C library</a>
-<li> <a href="#n8">Putting it all together</a>
-<li> <a href="#n9">Exception handling</a>
-<li> <a href="#n10">Remapping C datatypes with typemaps</a>
-<li> <a href="#n11">Implementing C callback functions in Python</a>
-<li> <a href="#n12">Other odds and ends</a>
-<li> <a href="#n13">The gory details of shadow classes</a>
-</ul>
-
-This chapter describes SWIG's support of Python. Many of the example presented here will have a scientific bias given Python's increasing use in scientific applications (this is how I primarily use Python), but the techniques are widely applicable to other areas.<p>
-<a name="n1"></a><h2> Preliminaries</h2>
-SWIG 1.1 works with Python 1.3 and Python 1.4. Given the choice, you should use the latest version of Python. You should also determine if your system supports shared libraries and dynamic loading. SWIG will work with or without dynamic loading, but the compilation process will vary.<p>
-<a name="n14"></a><h3> Running SWIG</h3>
-To build a Python module, run SWIG using the <tt>-python</tt> option :<p>
-<p>
-<blockquote><pre>%swig -python example.i
-</pre></blockquote>
-<p>
-This will produce 2 files. The file <tt>example_wrap.c</tt> contains all of the C code needed to build a Python module and a documentation file describes the resulting interface. To build a Python module, you will need to compile the file <tt>example_wrap.c</tt> and link it with the rest of your program (and possibly Python itself). When working with shadow classes, SWIG will also produce a <tt>.py</tt> file, but this is described later.<p>
-<a name="n15"></a><h3> Getting the right header files</h3>
-In order to compile, you need to locate the following directories that are part of the Python distribution :<p>
-<p>
-For Python 1.3 :<p>
-<p>
-<blockquote><pre>/usr/local/include/Py
-/usr/local/lib/python/lib
-</pre></blockquote>
-<p>
-For Python 1.4 :<p>
-<p>
-<blockquote><pre>/usr/local/include/python1.4
-/usr/local/lib/python1.4/config
-
-</pre></blockquote>
-The exact location may vary on your machine, but the above locations are typical. <p>
-<a name="n16"></a><h3> Compiling a dynamic module</h3>
-To build a shared object file, you need to compile your module in a manner similar to the following (shown for Irix):<p>
-<p>
-<blockquote><pre>% swig -python example.i
-% gcc -c example.c
-% gcc -c example_wrap.c -DHAVE_CONFIG_H -I/usr/local/include/python1.4 \
- -I/usr/local/lib/python1.4/config
-% ld -shared example.o example_wrap.o -o examplemodule.so
-
-</pre></blockquote>
-Unfortunately, the process of building a shared object file varies on every single machine so you may need to read up on the man pages for your C compiler and linker.<p>
-<p>
-When building a dynamic module, the name of the output file is important. If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding object file should be "<tt>examplemodule.so</tt>" (or equivalent depending on your machine). The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.<p>
-<p>
-While dynamic loading is the preferred method for making SWIG modules, it is not foolproof and not supported on all machines. In these cases, you can rebuild the Python interpreter with your extensions added.<p>
-<a name="n17"></a><h3> Rebuilding the Python interpreter (aka. static linking)</h3>
-The normal procedure for adding a new module to Python involves finding the Python source, adding an entry to the <tt>Modules/Setup</tt> file, and rebuilding the interpreter using the Python Makefile. While it's possible to simplify the process by using the VPATH feature of `make', I've always found the process to be a little too complicated. <p>
-<p>
-SWIG provides an extremely easy, although somewhat unconventional, mechanism for rebuilding Python using SWIG's library feature. When you want to build a static version of Python, simply make an interface file like this :<p>
-<p>
-<blockquote><pre>%module example
-
-extern int fact(int);
-extern int mod(int, int);
-extern double My_variable;
-
-%include embed.i // Include code for a static version of Python
-
-</pre></blockquote>
-The <tt>embed.i</tt> library file includes supporting code that contains everything needed to rebuild Python. To build your module, simply do the following :<p>
-<p>
-<blockquote><pre>% swig -python example.i
-% gcc example.c example_wrap.c -DHAVE_CONFIG_H -I/usr/local/include/python1.4 \
- -I/usr/local/lib/python1.4/config \
- -L/usr/local/lib/python1.4/config -lModules -lPython -lObjects -lParser -lm \
- -o mypython
-
-</pre></blockquote>
-On some machines, you may need need to supply additional libraries on the link line. In particular, you may need to supply <tt>-lsocket</tt>,<tt> -lnsl</tt>, and <tt>-ldl</tt>. <p>
-<p>
-It is also possible to add the embed.i library to an existing interface by running SWIG as follows :<p>
-<p>
-<blockquote><pre>% swig -python -lembed.i example.i
-
-</pre></blockquote>
-The <tt>embed.i</tt> file uses all of the modules that are currently being used in your installed version of Python. Thus, your new version of Python will be identical to the old one except with your new module added. If you have configured Python to use modules such as <tt>tkinter,</tt> you may need to supply linkage to the Tcl/Tk libraries and X11 libraries.<p>
-<p>
-Python's <tt>main()</tt> program is rather unfriendly towards C++ code, but SWIG's <tt>embed.i</tt> module provides a replacement that can be compiled with the C++ compiler--making it easy to build C++ Python extensions.<p>
-<p>
-The <tt>embed.i</tt> library should only be used with Python 1.4. If you are using Python 1.3, you should use the file <tt>embed13.i</tt> instead (this can be done by making a symbolic link in the SWIG library) or simply using the <tt>-l</tt> option.<p>
-<a name="n18"></a><h3> Using your module</h3>
-To use your module in Python, simply use Python's import command. The process is identical regardless of whether or not you used dynamic loading or rebuilt the Python interpreter :<p>
-<p>
-<blockquote><pre>% python
->>> import example
->>> example.fact(4)
-24
->>>
-
-</pre></blockquote>
-<a name="n19"></a><h3> Compilation problems and compiling with C++</h3>
-For the most part, compiling a Python module is straightforward, but there are a number of potential problems :<p>
-<p>
-<ul>
-<li>Dynamic loading is not supported on all machines. If you can't get a module to build, you might try building a new version of Python using static linking instead.
-<li>In order to build C++ modules, you may need to link with the C++ compile using a command like `<tt>c++ -shared example_wrap.o example.o -o examplemodule.so</tt>'
-<li>If building a dynamic C++ module using g++, you may also need to link against <tt>libgcc.a</tt>, <tt>libg++.a</tt>, and <tt>libstc++.a</tt> libraries.
-<li>Make sure you are using the correct header files and libraries. A module compiled with Python 1.3 headers probably won't work with Python 1.4.
-</ul>
-<a name="n2"></a><h2> Building Python Extensions under Windows 95/NT</h2>
-Building a SWIG extension to Python under Windows 95/NT is roughly similar to the process used with Unix. Normally, you will want to produce a DLL that can be loaded into the Python interpreter. This section covers the process of using SWIG with Microsoft Visual C++ 4.x although the procedure may be similar with other compilers. SWIG currently supports both the basic Python release and Pythonwin. In order to build extensions, you will need to download the source distribution to these packages as you will need the Python header files.<p>
-<a name="n20"></a><h3> Running SWIG from Developer Studio</h3>
-If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process roughly follows these steps :<p>
-<p>
-<ul>
-<li>Open up a new workspace and use the AppWizard to select a DLL project.
-<li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't exist yet--Developer Studio will keep a reference to it around.
-<li>Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
-<li>Enter "SWIG" in the description field.
-<li>Enter "<tt>swig -python -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build command(s) field"
-<li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" in the "Output files(s) field".
-<li>Next, select the settings for the entire project and go to "C++:Preprocessor". Add the include directories for your Python installation under "Additional include directories".
-<li>Define the symbol __WIN32__ under preprocessor options.
-<li>Finally, select the settings for the entire project and go to "Link Options". Add the Python library file to your link libraries. For example "python14.lib". Also, set the name of the output file to match the name of your Python module (ie. example.dll).
-<li>Build your project.
-</ul>
-<p>
-Now, assuming all went well, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Python extension, simply run Python and use the <tt>import</tt> command as normal. For example :<p>
-<p>
-<blockquote><pre>
-MSDOS > python
->>> import example
->>> print example.fact(4)
-24
->>>
-</pre></blockquote>
-<a name="n21"></a><h3> Using NMAKE</h3>
-Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE. Make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. Now, just write a short Makefile like this :<p>
-<p>
-<blockquote><pre># Makefile for building a Python extension
-
-SRCS = example.c
-IFILE = example
-INTERFACE = $(IFILE).i
-WRAPFILE = $(IFILE)_wrap.c
-
-# Location of the Visual C++ tools (32 bit assumed)
-
-TOOLS = c:\msdev
-TARGET = example.dll
-CC = $(TOOLS)\bin\cl.exe
-LINK = $(TOOLS)\bin\link.exe
-INCLUDE32 = -I$(TOOLS)\include
-MACHINE = IX86
-
-# C Library needed to build a DLL
-
-DLLIBC = msvcrt.lib oldnames.lib
-
-# Windows libraries that are apparently needed
-WINLIB = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib
-winspool.lib
-
-# Libraries common to all DLLs
-LIBS = $(DLLIBC) $(WINLIB)
-
-# Linker options
-LOPT = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO \
- /MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
-
-# C compiler flags
-
-CFLAGS = /Z7 /Od /c /nologo
-PY_INCLUDE = -Id:\python-1.4\Include -Id:\python-1.4 -Id:\python-1.4\Pc
-PY_LIB = d:\python-1.4\vc40\python14.lib
-PY_FLAGS = /D__WIN32__
-
-python::
- swig -python -o $(WRAPFILE) $(INTERFACE)
- $(CC) $(CFLAGS) $(PY_FLAGS) $(PY_INCLUDE) $(SRCS) $(WRAPFILE)
- set LIB=$(TOOLS)\lib
- $(LINK) $(LOPT) -out:example.dll $(LIBS) $(PY_LIB) example.obj example_wrap.obj
-
-
-</pre></blockquote>
-<p>
-To build the extension, run NMAKE (you may need to run <tt>vcvars32</tt> first). This is a pretty simplistic Makefile, but hopefully its enough to get you started. <p>
-<a name="n3"></a><h2> The low-level Python/C interface</h2>
-The SWIG Python module is based upon a basic low-level interface that provides access to C functions, variables, constants, and C++ classes. This low-level interface is often used to create more sophisticated interfaces (such as shadow classes) so it may be hidden in practice.<p>
-<a name="n22"></a><h3> Modules</h3>
-The SWIG <tt>%module</tt> directive specifies the name of the Python module. If you specified `<tt>%module example</tt>', then everything found in a SWIG interface file will be contained within the Python `<tt>example</tt>' module. Make sure you don't use the same name as a built-in Python command or standard module or your results may be unpredictable. <p>
-<a name="n23"></a><h3> Functions</h3>
-C/C++ functions are mapped directly into a matching Python function. For example :<p>
-<p>
-<blockquote><pre>%module example
-extern int fact(int n);
-
-</pre></blockquote>
-gets turned into the Python function <tt>example.fact(n)</tt> :<p>
-<p>
-<blockquote><pre>>>> import example
->>> print example.fact(4)
-24
->>>
-</pre></blockquote>
-<a name="n24"></a><h3> Variable Linking</h3>
-SWIG provides access to C/C++ global variables, but the mechanism is slightly different than one might expect due to the object model used in Python. When you type the following in Python :<p>
-<p>
-<blockquote><pre>a = 3.4
-
-</pre></blockquote>
-"a" becomes a name for an object containing the value 3.4. If you later type<p>
-<p>
-<blockquote><pre>b = a
-
-</pre></blockquote>
-Then "a" and "b" are both names for the object containing the value 3.4. In other words, there is only one object containing 3.4 and "a" and "b" are both names that refer to it. This is a very different model than that used in C. For this reason, there is no mechanism for mapping "assignment" in Python onto C global variables (because assignment is Python is really a naming operation).<p>
-<p>
-To provide access to C global variables, SWIG creates a special Python object called `<tt>cvar</tt>' that is added to each SWIG generated module. This object is used to access global variables as follows :<p>
-<blockquote><pre>
-// SWIG interface file with global variables
-%module example
-...
-extern int My_variable;
-extern double density;
-...
-</pre></blockquote>
-<p>
-Now in Python :<p>
-<p>
-<blockquote><pre>>>> import example
->>> # Print out value of a C global variable
->>> print example.cvar.My_variable
-4
->>> # Set the value of a C global variable
->>> example.cvar.density = 0.8442
->>> # Use in a math operation
->>> example.cvar.density = example.cvar.density*1.10
-</pre></blockquote>
-<p>
-Just remember, all C globals need to be prefixed with a "<tt>cvar.</tt>" and you will be set. If you would like to use a name other than "<tt>cvar</tt>", it can be changed using the <tt>-globals</tt> option :<p>
-<p>
-<blockquote><pre>% swig -python -globals myvar example.i
-
-</pre></blockquote>
-Some care is in order when importing multiple SWIG modules. If you use the "<tt>from <file> import *</tt>" style of importing, you will get a name clash on the variable `<tt>cvar</tt>' and will only be able to access global variables from the last module loaded. SWIG does not create <tt>cvar</tt> if there are no global variables in a module.<p>
-<a name="n25"></a><h3> Constants</h3>
-C/C++ constants are installed as new Python objects containing the appropriate value. These constants are given the same name as the corresponding C constant. "Constants" are not guaranteed to be constants in Python---in other words, you are free to change them and suffer the consequences!<p>
-<a name="n26"></a><h3> Pointers</h3>
-Pointers to C/C++ objects are represented as character strings such as the following :<p>
-<p>
-<blockquote><pre>_100f8e2_Vector_p
-
-</pre></blockquote>
-A NULL pointer is represented by the string "NULL". You can also explicitly create a NULL pointer consisting of the value 0 and a type such as :<p>
-<p>
-<blockquote><pre>_0_Vector_p
-
-</pre></blockquote>
-To some Python users, the idea of representing pointers as strings may seem strange, but keep in mind that pointers are meant to be opaque objects. In practice, you may never notice that pointers are character strings. There is also a certain efficiency in using this representation as it is easy to pass pointers around between modules and it is unnecessary to rely on a new Python datatype. Eventually, pointers may be represented as special Python objects, but the string representation works remarkably well so there has been little need to replace it.<p>
-<a name="n27"></a><h3> Structures </h3>
-The low-level SWIG interface only provides a simple interface to C structures. For example :<p>
-<p>
-<blockquote><pre>struct Vector {
- double x,y,z;
-};
-
-</pre></blockquote>
-gets mapped into the following collection of C functions :<p>
-<p>
-<blockquote><pre>double Vector_x_get(Vector *obj)
-double Vector_x_set(Vector *obj, double x)
-double Vector_y_get(Vector *obj)
-double Vector_y_set(Vector *obj, double y)
-double Vector_z_get(Vector *obj)
-double Vector_z_set(Vector *obj, double z)
-
-</pre></blockquote>
-These functions are then used in the resulting Python interface. For example :<p>
-<p>
-<blockquote><pre># v is a Vector that got created somehow
->>> Vector_x_get(v)
-3.5
->>> Vector_x_set(v,7.8) # Change x component
->>> print Vector_x_get(v), Vector_y_get(v), Vector_z_get(v)
-7.8 -4.5 0.0
->>>
-</pre></blockquote>
-<p>
-Similar access is provided for unions and the data members of C++ classes.<p>
-<a name="n28"></a><h3> C++ Classes</h3>
-C++ classes are handled by building a set of low level accessor functions. Consider the following class :<p>
-<p>
-<blockquote><pre>class List {
-public:
- List();
- ~List();
- int search(char *item);
- void insert(char *item);
- void remove(char *item);
- char *get(int n);
- int length;
-static void print(List *l);
-};
-</pre></blockquote>
-<p>
-When wrapped by SWIG, the following functions will be created :<p>
-<p>
-<blockquote><pre>List *new_List();
-void delete_List(List *l);
-int List_search(List *l, char *item);
-void List_insert(List *l, char *item);
-void List_remove(List *l, char *item);
-char *List_get(List *l, int n);
-int List_length_get(List *l);
-int List_length_set(List *l, int n);
-void List_print(List *l);
-
-</pre></blockquote>
-Within Python, these functions used to access the C++ class :<p>
-<blockquote><pre>
->>> l = new_List()
->>> List_insert(l,"Ale")
->>> List_insert(l,"Stout")
->>> List_insert(l,"Lager")
->>> List_print(l)
-Lager
-Stout
-Ale
->>> print List_length_get(l)
-3
->>> print l
-_1008560_List_p
->>>
-
-</pre></blockquote>
-C++ objects are really just pointers. Member functions and data are accessed by simply passing a pointer into a collection of accessor functions that take the pointer as the first argument.<p>
-<p>
-While somewhat primitive, the low-level SWIG interface provides direct and flexible access to C++ objects. As it turns out, a more elegant method of accessing structures and classes is available using shadow classes.<p>
-<a name="n4"></a><h2> Python shadow classes</h2>
-The low-level interface generated by SWIG provides access to C structures and C++ classes, but it doesn't look much like a class that might be created in Python. However, it is possible to use the low-level C interface to write a Python class that looks like the original C++ class. In this case, the Python class is said to "shadow" the C++ class. That is, it behaves like the original class, but is really just a wrapper around a C++ class.<p>
-<a name="n29"></a><h3> A simple example</h3>
-For our earlier List class, a Python shadow class could be written by hand like this :<p>
-<p>
-<blockquote><pre>class List:
- def __init__(self):
- self.this = new_List()
- def __del__(self):
- delete_List(self.this)
- def search(self,item):
- return List_search(self.this,item)
- def insert(self,item):
- List_insert(self.this,item)
- def remove(self,item):
- List_remove(self.this,item)
- def get(self,n):
- return List_get(self.this,n)
- def __getattr__(self,name):
- if name == "length" : return List_length_get(self.this))
- else : return self.__dict__[name]
- def __setattr__(self,name,value):
- if name == "length": List_length_set(self.this,value)
- else : self.__dict__[name] = value
-</pre></blockquote>
-<p>
-When used in a Python script, we can use the class as follows :<p>
-<blockquote><pre>
-
->>> l = List()
->>> l.insert("Ale")
->>> l.insert("Stout")
->>> l.insert("Lager")
->>> List_print(l.this)
-Lager
-Stout
-Ale
->>> l.length
-3
-</pre></blockquote>
-<p>
-Obviously, this is a much nicer interface than before--and it only required a small amount of Python coding.<p>
-<a name="n30"></a><h3> Why write shadow classes in Python?</h3>
-While one could wrap C/C++ objects directly into Python as new Python types, this approach has a number of problems. First, as the C/C++ code gets complicated, the resulting wrapper code starts to become extremely ugly. It also becomes hard to handle inheritance and more advanced language features. A second, and more serious problem, is that Python "types" created in C can not be subclassed or used in the same way as one might use a real Python class. As a result, it is not possible to do interesting things like create Python classes that inherit from C++ classes. <p>
-<p>
-By writing shadow classes in Python instead of C, the classes become real Python classes that can be used as base-classes in an inheritance hierarchy or for other applications. Writing the shadow classes in Python also greatly simplies coding complexity as writing in Python is much easier than trying to accomplish the same thing in C. Finally, by writing shadow classes in Python, they are easy to modify and can be changed without ever recompiling any of the C code. The downside to this approach is worse performance--a concern for some users.<p>
-<p>
-The problems of combining C++ and Python have been of great interest to the Python community. SWIG is primarily concerned with accessing C++ from Python. Readers who are interested in more than this (and the idea of accessing Python classes from C++) are encouraged to look into the MESS extension which aims to provide a tighter integration between C++ and Python. The recently announced GRAD package also shows much promise and provides very comprehensive C++/Python interface.<p>
-<a name="n31"></a><h3> Automated shadow class generation</h3>
-SWIG can automatically generate shadow classes if you use the <tt>-shadow</tt> option :<p>
-<p>
-<blockquote><pre>swig -python -shadow interface.i
-
-</pre></blockquote>
-This will create the following two files :<p>
-<p>
-<blockquote><pre>interface_wrap.c
-module.py
-</pre></blockquote>
-<p>
-The file <tt>interface_wrap.c</tt> contains the normal SWIG C/C++ wrappers. The file <tt>module.py</tt> contains the Python code corresponding to shadow classes. The name of this file will be the same as specified by the <tt>%module</tt> directive in the SWIG interface file.<p>
-<p>
-Associated with the two files are TWO Python modules. The C module `<tt>modulec</tt>' contains the low-level C interface that would have been created without the <tt>-shadow</tt> option. The Python module `<tt>module</tt>' contains the Python shadow classes that have been built around the low-level interface. To use the module, simply use `<tt>import module</tt>'. For all practical purposes, the `<tt>modulec</tt>' module is completely hidden although you can certainly use it if you want to.<p>
-<a name="n32"></a><h3> Compiling modules with shadow classes</h3>
-To compile a module involving shadow classes, you can use the same procedure as before except that the module name now has an extra `<tt>c</tt>' appended to the name. Thus, an interface file like this <p>
-<p>
-<blockquote><pre>%module example
-... a bunch of declarations ...
-
-</pre></blockquote>
-might be compiled as follows :<p>
-<p>
-<blockquote><pre>% swig -python -shadow example.i
-% gcc -c example.c example_wrap.c -I/usr/local/include/python1.4 \
- -I/usr/local/lib/python1.4/config -DHAVE_CONFIG_H
-% ld -shared example.o example_wrap.o -o examplecmodule.so
-
-</pre></blockquote>
-Notice the naming of `<tt>examplecmodule.so</tt>' as opposed to `<tt>examplemodule.so</tt>' that would have been created without shadow classes.<p>
-<p>
-When using static linking, no changes need to be made to the compilation process.<p>
-<a name="n33"></a><h3> Where to go for more information</h3>
-Shadow classes turn out to be so useful that they are used almost all of the time with SWIG. All of the examples presented here will assume that shadow classes have been enabled. The precise implementation of shadow classes is described at the end of this chapter and is not necessary to effectively use SWIG.<p>
-<a name="n5"></a><h2> About the Examples</h2>
-The next few sections will go through a series of Python examples of varying complexity. These examples are designed to illustrate how SWIG can be used to integrate C/C++ and Python in a variety of ways. Some of the things that will be covered include :<p>
-<p>
-<ul>
-<li>Controlling a simple C++ program with Python
-<li>Wrapping a C library.
-<li>Adding Python methods to existing C++ classes
-<li>Accessing arrays and other common data structures.
-<li>Building reusable components.
-<li>Writing C/C++ callback functions in Python.
-</ul>
-<a name="n6"></a><h2> Solving a simple heat-equation</h2>
-In this example, we will show how Python can be used to control a simple physics application--in this case, some C++ code for solving a 2D heat equation. This example is probably overly simplistic, but hopefully it's enough to give you some ideas.<p>
-<a name="n34"></a><h3> The C++ code </h3>
-Our simple application consists of the following two files :<p>
-<blockquote><pre>
-// File : pde.h
-// Header file for Heat equation solver
-
-#include <math.h>
-#include <stdio.h>
-
-// A simple 2D Grid structure
-
-// A simple structure for holding a 2D grid of values
-struct Grid2d {
- Grid2d(int ni, int nj);
- ~Grid2d();
- double **data;
- int xpoints;
- int ypoints;
-};
-
-// Simple class for solving a heat equation */
-class Heat2d {
-private:
- Grid2d *work; // Temporary grid, needed for solver
- double h,k; // Grid spacing
-public:
- Heat2d(int ni, int nj);
- ~Heat2d();
- Grid2d *grid; // Data
- double dt; // Timestep
- double time; // Elapsed time
- void solve(int nsteps); // Run for nsteps
- void set_temp(double temp); // Set temperature
-};
-</pre></blockquote>
-<p>
-The supporting C++ code implements a simple partial differential equation solver and some operations on the grid data structure. The precise implementation isn't important here, but all of the code can be found in the "<tt>Examples/python/manual" </tt>directory of the SWIG distribution. <p>
-<a name="n35"></a><h3> Making a quick and dirty Python module</h3>
-Given our simple application, making a Python module is easy. Simply use the following SWIG interface file :<p>
-<p>
-<blockquote><pre>// File : pde.i
-%module pde
-%{
-#include "pde.h"
-%}
-
-%include pde.h
-
-</pre></blockquote>
-Since <tt>pde.h</tt> is fairly simple, we can simply include it directly into our interface file using <tt>%include</tt>. However, we also need to make sure we also include it in the <tt>%{,%}</tt> block--otherwise we'll get a huge number of compiler errors when we compile the resulting wrapper file. <p>
-<p>
-To build the module simply run SWIG with the following options<p>
-<p>
-<blockquote><pre>swig -python -shadow pde.i
-</pre></blockquote>
-<p>
-and compile using the techniques described in the beginning of this chapter.<p>
-<a name="n36"></a><h3> Using our new module</h3>
-We are now ready to use our new module. To do this, we can simply write a Python script like this :<p>
-<p>
-<blockquote><pre># A fairly uninteresting example
-
-from pde import *
-
-h = Heat2d(50,50) # Creates a new "problem"
-
-h.set_temp(1.0)
-print "Dt = ", h.dt
-
-# Solve something
-
-for i in range(0,25):
- h.solve(100)
- print "time = ", h.time
-
-</pre></blockquote>
-<p>
-When run, we get rather exciting output such as the following :<p>
-<blockquote><pre>
-Dt = 2.5e-05
-time = 0.0025
-time = 0.005
-time = 0.0075
-...
-time = 0.06
-time = 0.0625
-
-</pre></blockquote>
-(okay, it's not that exciting--well, maybe it is if you don't get out much).<p>
-<p>
-While this has only been a simple example it is important to note that we could have just as easily written the same thing in C++. For example :<p>
-<p>
-<blockquote><pre>// Python example written in C++
-
-#include "pde.h"
-#include <stdio.h>
-
-int main(int argc, char **argv) {
-
- Heat2d *h;
-
- h = new Heat2d(50,50);
- printf("Dt = %g\n", h->dt);
-
- h->set_temp(1.0);
-
- for (int i = 0; i < 25; i++) {
- h->solve(100);
- printf("time = %g\n", h->time);
- }
-}
-
-</pre></blockquote>
-For the most part, the code looks identical (although the Python version is simpler). As for performance, the Python version runs less than 1% slower than the C++ version on my machine. Given that most of the computational work is written in C++, there is very little performance penalty for writing the outer loop of our calculation in Python in this case.<p>
-<p>
-Unfortunately, our Python version suffers a number of drawbacks. Most notably, there is no way for us to access any of the grid data (which is easily accomplished in C++). However, there are ways to fix this :<p>
-<a name="n37"></a><h3> Accessing array data</h3>
-Let's modify our heat equation problem so that we can access grid data directly from Python. This can be done by modifying our interface file as follows :<p>
-<blockquote><pre>
-%module pde
-%{
-#include "pde.h"
-%}
-
-%include pde.h
-
-// Add a few "helper" functions to extract grid data
-%inline %{
-double Grid2d_get(Grid2d *g, int i, int j) {
- return g->data[i][j];
-}
-void Grid2d_set(Grid2d *g, int i, int j, double val) {
- g->data[i][j] = val;
-}
-%}
-
-</pre></blockquote>
-Rather than modifying our C++ code, it is easy enough to supply a few accessor functions directly in our interface file. These function may only be used from Python so this approach makes sense and it helps us keep our C++ code free from unnecessary clutter. The <tt>%inline</tt> directive is a convenient method for adding helper functions since the functions you declare show up in the interface automatically.<p>
-<p>
-We can now use our accessor functions to write a more sophisticated Python script :<p>
-<p>
-<blockquote><pre># An example using our set/get functions
-
-from pde import *
-
-# Set up an initial condition
-def initcond(h):
- h.set_temp(0.0)
- nx = h.grid.xpoints
- for i in range(0,nx):
- Grid2d_set(h.grid,i,0,1.0) # Set grid values
-
-# Dump out to a file
-def dump(h,filename):
- f = open(filename,"w")
- nx = h.grid.xpoints
- ny = h.grid.ypoints
- for i in range(0,nx):
- for j in range(0,ny):
- f.write(str(Grid2d_get(h.grid,i,j))+"\n") # Get grid value
- f.close()
-
-# Set up a problem and run it
-
-h = Heat2d(50,50)
-initcond(h)
-fileno = 1
-for i in range(0,25):
- h.solve(100)
- dump(h,"Dat"+str(fileno))
- print "time = ", h.time
- fileno = fileno+1
-
-</pre></blockquote>
-<p>
-We now have a Python script that can create a grid, set up an initial condition, run a simulation, and dump a collection of datafiles. So, with just a little supporting code in our interface file, we can start to do useful work from Python. <p>
-<a name="n38"></a><h3> Use Python for control, C for performance</h3>
-Now that it is possible to access grid data from Python, it is possible to quickly write code for all sorts of operations. However, Python may not provide enough performance for certain operations. For example, the <tt>dump()</tt> function in the previous example may become quite slow as problem sizes increase. Thus, we might consider writing it in C++ such as the follows:<p>
-<p>
-<blockquote><pre>void dump(Heat2d *h, char *filename) {
- FILE *f;
- int i,j;
-
- f = fopen(filename,"w");
- for (i = 0; i < h->grid->xpoints; i++)
- for (j = 0; j < h->grid->ypoints; j++)
- fprintf(f,"%0.17f\n",h->grid->data[i][j]);
- fclose(f);
-}
-</pre></blockquote>
-<p>
-To use this new function, simple put its declaration in the SWIG interface file and get rid of the old Python version. The Python script won't know that you changed the implementation.<p>
-<a name="n39"></a><h3> Getting even more serious about array access</h3>
-We have provided access to grid data using a pair of get/set functions. However, using these functions is a little clumsy because they always have to be called as a separate function like this :<p>
-<p>
-<blockquote><pre>Grid2d_set(grid,i,j,1.0)
-</pre></blockquote>
-<p>
-It might make more sense to make the get/set functions appear like member functions of the <tt>Grid2D</tt> class. That way we could use them like this :<p>
-<p>
-<blockquote><pre>grid.set(i,j,1.0)
-grid.get(i,j)
-
-</pre></blockquote>
-SWIG provides a simple technique for doing this as illustrated in the following interface file :<p>
-<p>
-<blockquote><pre>%module pde
-%{
-#include "pde.h"
-%}
-%include pde.h
-
-// Add a few "helper" functions to extract grid data
-%{
- double Grid2d_get(Grid2d *g, int i, int j) {
- return g->data[i][j];
- }
- void Grid2d_set(Grid2d *g, int i, int j, double val) {
- g->data[i][j] = val;
- }
-%}
-
-// Now add these helper functions as methods of Grid2d
-
-%addmethods Grid2d {
- double get(int i, int j); // Gets expanded to Grid2d_get()
- void set(int i, int j, double val); // Gets expanded to Grid2d_set()
-}
-</pre></blockquote>
-<p>
-The <tt>%addmethods</tt> directive tells SWIG that you want to add new functions to an existing C++ class or C structure for the purposes of building an interface. In reality, SWIG leaves the original C++ class unchanged, but the resulting Python interface will have some new functions that appear to be class members.<p>
-<p>
-SWIG uses a naming convention for adding methods to a class. If you have a class <tt>Foo</tt> and you add a member function <tt>bar(args),</tt> SWIG will look for a function called <tt>Foo_bar(this,args)</tt> that implements the desired functionality. You can write this function yourself, as in the previous interface file, but you can also just supply the code immediately after a declaration like this :<p>
-<blockquote><pre>
-%module pde
-%{
-#include "pde.h"
-%}
-%include pde.h
-
-// Add some new accessor methods to the Grid2D class
-%addmethods Grid2d {
- double get(int i, int j) {
- return self->data[i][j];
- };
- void set(int i, int j, double val) {
- self->data[i][j] = val;
- };
-};
-
-</pre></blockquote>
-<p>
-In this case, SWIG will take the supplied code, and automatically generate a function for the method. The special variable "<tt>self</tt>" is used to hold a pointer to the corresponding object. The <tt>self </tt>pointer is exactly like the C++ "<tt>this</tt>" pointer, except that the name has been changed in order to remind you that you aren't really writing a real class member function. (Actually, the real reason we can't use "this" is because the C++ compiler will start complaining!)<p>
-<p>
- Finally, it is worth noting that the <tt>%addmethods</tt> directive may also be used inside a class definition like this :<p>
-<p>
-<blockquote><pre>struct Grid2d {
- Grid2d(int ni, int nj);
- ~Grid2d();
- double **data;
- int xpoints;
- int ypoints;
- %addmethods {
- double get(int i, int j);
- void set(int i, int j, double value);
- }
-};
-
-</pre></blockquote>
-This latter case is really only useful if the C++ class definition is included in the SWIG interface file itself. If you are pulling the class definition out of a separate file or a C++ header file, using a separate <tt>%addmethods</tt> directive is preferable. It doesn't matter if the <tt>%addmethods</tt> directive appears before or after the real class definition--SWIG will correctly associate the two definitions.<p>
-<p>
-Okay, enough talk. By adding the set/get functions as methods, we can now change our Python script to look like this (changes are underlined) :<p>
-<p>
-<blockquote><pre># An example using our new set/get functions
-
-from pde import *
-
-# Set up an initial condition
-
-def initcond(h):
- h.set_temp(0.0)
- nx = h.grid.xpoints
- for i in range(0,nx):
- h.grid.set(i,0,1.0) # Note changed interface
-
-# Dump out to a file
-def dump(h,filename):
- f = open(filename,"w")
- nx = h.grid.xpoints
- ny = h.grid.ypoints
- for i in range(0,nx):
- for j in range(0,ny):
- f.write(str(h.grid.get(i,j))+"\n")
- f.close()
-
-# Set up a problem and run it
-
-h = Heat2d(50,50)
-initcond(h)
-fileno = 1
-
-for i in range(0,25):
- h.solve(100)
- h.dump("Dat"+str(fileno))
- print "time = ", h.time
- fileno = fileno+1
-
-</pre></blockquote>
-<p>
-Now it's starting to look a little better, but we can do even better...<p>
-<a name="n40"></a><h3> Implementing special Python methods in C</h3>
-Now that you're getting into the spirit of things, let's make it so that we can access our <tt>Grid2D</tt> data like a Python array. As it turns out, we can do this with a little trickery in the SWIG interface file. Don't forget to put on your Python wizard cap...<p>
-<p>
-<blockquote><pre>// SWIG interface file with Python array methods added
-%module pde
-%{
-#include "pde.h"
-%}
-
-%include pde.h
-
-%inline %{
- // Define a new Grid2d row class
- struct Grid2dRow {
- Grid2d *g; // Grid
- int row; // Row number
- // These functions are used by Python to access sequence types (lists, tuples, ...)
- double __getitem__(int i) {
- return g->data[row][i];
- };
- void __setitem__(int i, double val) {
- g->data[row][i] = val;
- };
- };
-%}
-
-// Now add a __getitem__ method to Grid2D to return a row
-%addmethods Grid2d {
- Grid2dRow __getitem__(int i) {
- Grid2dRow r;
- r.g = self;
- r.row = i;
- return r;
- };
-};
-</pre></blockquote>
-<p>
-We have now replaced our get/set functions with<tt> the __getitem__</tt> and <tt>__setitem__</tt> functions that Python needs to access arrays. We have also added a special <tt>Grid2dRow</tt> class. This is needed to allow us to make a funny kind of "multidimensional" array in Python (this may take a few minutes of thought to figure out). Using this new interface file, we can now write a Python script like this :<p>
-<p>
-<blockquote><pre># An example script using our array access functions
-
-from pde import *
-
-# Set up an initial condition
-
-def initcond(h):
- h.set_temp(0.0)
- nx = h.grid.xpoints
- for i in range(0,nx):
- h.grid[i][0] = 1.0 # Note nice array access
-
-# Set up a problem and run it
-
-h = Heat2d(50,50)
-initcond(h)
-fileno = 1
-
-for i in range(0,25):
- h.solve(100)
- h.dump("Dat"+str(fileno))
- print "time = ", h.time
- fileno = fileno+1
-
-# Calculate average temperature over the region
-
-sum = 0.0
-for i in range(0,h.grid.xpoints):
- for j in range(0,h.grid.ypoints):
- sum = sum + h.grid[i][j] # Note nice array access
-
-avg = sum/(h.grid.xpoints*h.grid.ypoints)
-
-print "Avg temperature = ",avg
-</pre></blockquote>
-<a name="n41"></a><h3> Summary (so far)</h3>
-In our first example, we have taken a very simple C++ problem and wrapped it into a Python module. With a little extra work, we have been able to provide array type access to our C++ data from Python and to write some computationally intensive operations in C++. At this point, it would easy to write all sorts of Python scripts to set up problems, run simulations, look at the data, and to debug new operations implemented in C++. <p>
-<a name="n7"></a><h2> Wrapping a C library</h2>
-In this next example, we focus on wrapping the gd-1.2 library. gd is public domain library for fast GIF image creation written by Thomas Boutell and available on the internet. gd-1.2 is copyright 1994,1995, Quest Protein Database Center, Cold Spring Harbor Labs. This example assumes that you have gd-1.2 available, but you can use the ideas here to wrap other kinds of C libraries.<p>
-<a name="n42"></a><h3> Preparing a module</h3>
-Wrapping a C library into a Python module usually involves working with the C header files associated with a particular library. In some cases, a header file can be used directly (without modification) with SWIG. Other times, it may be necessary to copy the header file into a SWIG interface file and make a few touch-ups and modifications. In either case, it's usually not too difficult.<p>
-<p>
-To make a module, you can use the following checklist :<p>
-<p>
-<ul>
-<li>Locate the header files associated with a package
-<li>Look at the contents of the header files to see if SWIG can handle them. In particular, SWIG can not handle excessive use of C preprocessor macros, or non-ANSI C syntax. The best way to identify problems is to simply run SWIG on the file and see what errors (if any) get reported.
-<li>Make a SWIG interface file for your module specifying the name of the module, the appropriate header files, and any supporting documentation that you would like to provide.
-<li>If the header file is clean, simply use SWIG's <tt>%include</tt> directive. If not, paste the header file into your interface file and edit it until SWIG can handle it.
-<li>Clean up the interface by possibly adding supporting code, deleting unnecessary functions, and eliminating clutter.
-<li>Run SWIG and compile.
-</ul>
-<p>
-In the case of the gd library, we can simply use the following SWIG interface file :<p>
-<p>
-<blockquote><pre>%module gd
-%{
-#include "gd.h"
-%}
-
-%section "gd-1.2",ignore
-%include "gd.h"
-
-// These will come in handy later
-FILE *fopen(char *, char *);
-void fclose(FILE *f);
-
-</pre></blockquote>
-<p>
-In this file, we first tell SWIG to put all of the gd functions in a separate documentation section and to ignore all comments. This usually helps clean up the documentation when working with raw header files. Next, we simply include the contents of "gd.h" directly. Finally, we provide wrappers to <tt>fopen()</tt> and <tt>fclose()</tt> since these will come in handy in our Python interface.<p>
-<p>
-If we give this interface file to SWIG, we will get the following output :<p>
-<p>
-<blockquote><pre>% swig -python -shadow -I/usr/local/include gd.i
-Generating wrappers for Python
-/usr/local/include/gd.h : Line 32. Arrays not currently supported (ignored).
-/usr/local/include/gd.h : Line 33. Arrays not currently supported (ignored).
-/usr/local/include/gd.h : Line 34. Arrays not currently supported (ignored).
-/usr/local/include/gd.h : Line 35. Arrays not currently supported (ignored).
-/usr/local/include/gd.h : Line 41. Arrays not currently supported (ignored).
-/usr/local/include/gd.h : Line 42. Arrays not currently supported (ignored).
-%
-
-</pre></blockquote>
-While SWIG was able to handle most of the header file, it also ran into a few unsupported declarations---in this case, a few data structures with array members. However, the warning messages also tell us that these declarations have simply been ignored. Thus, we can choose to continue and build our interface anyways. As it turns out in this case, the ignored declarations are of little or no consequence so we can ignore the warnings.<p>
-<p>
-If SWIG is unable to process a raw header file or if you would like to eliminate the warning messages, you can structure your interface file as follows :<p>
-<p>
-<blockquote><pre>%module gd
-%{
-#include "gd.h"
-%}
-
-%section "gd-1.2",ignore
-
-... paste the contents of gd.h here and remove problems ...
-
-// A few extra support functions
-
-FILE *fopen(char *, char *);
-void fclose(FILE *f);
-
-</pre></blockquote>
-This latter option requires a little more work (since you need to paste the contents of gd.h into the file and edit it), but is otherwise not much more difficult to do. For highly complex C libraries or header files that go overboard with the C preprocessor, you may need to do this more often. <p>
-<a name="n43"></a><h3> Using the gd module</h3>
-Now, that we have created a module from the gd library, we can use it in Python scripts. The following script makes a simple image of a black background with a white line drawn on it. Notice how we have used our wrapped versions of <tt>fopen()</tt> and <tt>fclose()</tt> to create a FILE handle for use in the gd library (there are also ways to use Python file objects, but this is described later).<p>
-<p>
-<blockquote><pre># Simple gd program
-
-from gd import *
-
-im = gdImageCreate(64,64)
-black = gdImageColorAllocate(im,0,0,0)
-white = gdImageColorAllocate(im,255,255,255)
-gdImageLine(im,0,0,63,63,white)
-out = fopen("test.gif","w")
-gdImageGif(im,out)
-fclose(out)
-gdImageDestroy(im)
-
-</pre></blockquote>
-<p>
-That was simple enough--and it only required about 5 minutes of work. Unfortunately, our gd module still has a few problems...<p>
-<a name="n44"></a><h3> Extending and fixing the gd module</h3>
-While our first attempt at wrapping gd works for simple functions, there are a number of problems. For example, the gd-1.2 library contains the following function for drawing polygons :<p>
-<p>
-<blockquote><pre>void gdImagePolygon(gdImagePtr im, gdPointPtr points, int pointsTotal, int color);
-
-</pre></blockquote>
-The <tt>gdImagePtr</tt> type is created by another function in our module and the parameters <tt>pointsTotal</tt> and <tt>color</tt> are simple integers. However, the 2nd argument is a pointer to an array of points as defined by the following data structure in the gd-1.2 header file :<p>
-<p>
-<blockquote><pre>typedef struct {
- int x, y;
-} gdPoint, *gdPointPtr;
-
-</pre></blockquote>
-Unfortunately, there is no way to create a gdPoint in Python and consequently no way to call the gdImagePolygon function. A temporary setback, but one that is not difficult to solve using the <tt>%addmethods</tt> directive as follows :<p>
-<blockquote><pre>
-%module gd
-%{
-#include "gd.h"
-%}
-
-%include "gd.h"
-
-// Fix up the gdPoint structure a little bit
-%addmethods gdPoint {
- // Constructor to make an array of "Points"
- gdPoint(int npoints) {
- return (gdPoint *) malloc(npoints*sizeof(gdPoint));
- };
- // Destructor to destroy this array
- ~gdPoint() {
- free(self);
- };
- // Python method for array access
- gdPoint *__getitem__(int i) {
- return self+i;
- };
-};
-
-FILE *fopen(char *, char *);
-void fclose(FILE *f);
-
-</pre></blockquote>
-With these simple additions, we can now create arrays of points and use the polygon function as follows :<p>
-<p>
-<blockquote><pre># Simple gd program
-
-from gd import *
-
-im = gdImageCreate(64,64)
-black = gdImageColorAllocate(im,0,0,0)
-white = gdImageColorAllocate(im,255,255,255)
-
-pts = gdPoint(3); # Create an array of Points
-pts[0].x,pts[0].y = (5,5) # Assign a set of points
-pts[1].x,pts[1].y = (60,25)
-pts[2].x,pts[2].y = (16,60)
-
-gdImagePolygon(im,pts,3,white) # Draw a polygon from our array of points
-out = fopen("test.gif","w")
-gdImageGif(im,out)
-fclose(out)
-gdImageDestroy(im)
-
-</pre></blockquote>
-<a name="n45"></a><h3> Building a simple 2D imaging class</h3>
-Now it's time to get down to business. Using our gd-1.2 module, we can write a simple 2D imaging class that hides alot of the underlying details and provides scaling, translations, and a host of other operations. (It's a fair amount code, but an interesting example of how one can take a simple C library and turn it into something that looks completely different).<p>
-<p>
-<p>
-<blockquote><pre># image.py
-# Generic 2D Image Class
-#
-# Built using the 'gd-1.2' library by Thomas Boutell
-#
-
-import gd
-
-class Image:
- def __init__(self,width,height,xmin=0.0,ymin=0.0,xmax=1.0,ymax=1.0):
- self.im = gd.gdImageCreate(width,height)
- self.xmin = xmin
- self.ymin = ymin
- self.xmax = xmax
- self.ymax = ymax
- self.width = width
- self.height = height
- self.dx = 1.0*(xmax-xmin)
- self.dy = 1.0*(ymax-ymin)
- self.xtick = self.dx/10.0
- self.ytick = self.dy/10.0
- self.ticklen= 3
- self.name = "image.gif"
- gd.gdImageColorAllocate(self.im,0,0,0) # Black
- gd.gdImageColorAllocate(self.im,255,255,255) # White
- gd.gdImageColorAllocate(self.im,255,0,0) # Red
- gd.gdImageColorAllocate(self.im,0,255,0) # Green
- gd.gdImageColorAllocate(self.im,0,0,255) # Blue
-
- def __del__(self):
- print "Deleting"
- gd.gdImageDestroy(self.im)
-
- # Dump out this image to a file
- def write(self,name="NONE"):
- if name == "NONE":
- name = self.name
- f = gd.fopen(name,"w")
- gd.gdImageGif(self.im,f)
- gd.fclose(f)
- self.name = name
-
- # Virtual method that derived classes define
- def draw(self):
- print "No drawing method specified."
-
- # A combination of write and draw
- def show(self,filename="NONE"):
- self.draw()
- self.write(filename)
-
- # Load up a colormap from a Python array of (R,G,B) tuples
- def colormap(self, cmap):
- for i in range(0,255):
- gd.gdImageColorDeallocate(self.im,i)
- for c in cmap:
- gd.gdImageColorAllocate(self.im,c[0],c[1],c[2])
-
- # Change viewing region
- def region(self,xmin,ymin,xmax,ymax):
- self.xmin = xmin
- self.ymin = ymin
- self.xmax = xmax
- self.ymax = ymax
- self.dx = 1.0*(xmax-xmin)
- self.dy = 1.0*(ymax-ymin)
-
- # Transforms a 2D point into screen coordinates
- def transform(self,x,y):
- npt = []
- ix = (x-self.xmin)/self.dx*self.width + 0.5
- iy = (self.ymax-y)/self.dy*self.height + 0.5
- return (ix,iy)
-
- # A few graphics primitives
- def clear(self,color):
- gd.gdImageFilledRectangle(self.im,0,0,self.width,self.height,color)
-
- def plot(self,x,y,color):
- ix,iy = self.transform(x,y)
- gd.gdImageSetPixel(self.im,ix,iy,color)
-
- def line(self,x1,y1,x2,y2,color):
- ix1,iy1 = self.transform(x1,y1)
- ix2,iy2 = self.transform(x2,y2)
- gd.gdImageLine(self.im,ix1,iy1,ix2,iy2,color)
-
- def box(self,x1,y1,x2,y2,color):
- ix1,iy1 = self.transform(x1,y1)
- ix2,iy2 = self.transform(x2,y2)
- gd.gdImageRectangle(self.im,ix1,iy1,ix2,iy2,color)
-
- def solidbox(self,x1,y1,x2,y2,color):
- ix1,iy1 = self.transform(x1,y1)
- ix2,iy2 = self.transform(x2,y2)
- gd.gdImageFilledRectangle(self.im,ix1,iy1,ix2,iy2,color)
-
- def arc(self,cx,cy,w,h,s,e,color):
- ix,iy = self.transform(cx,cy)
- iw = (x - self.xmin)/self.dx * self.width
- ih = (y - self.ymin)/self.dy * self.height
- gd.gdImageArc(self.im,ix,iy,iw,ih,s,e,color)
-
- def fill(self,x,y,color):
- ix,iy = self.transform(x,y)
- gd.gdImageFill(self,ix,iy,color)
-
- def axis(self,color):
- self.line(self.xmin,0,self.xmax,0,color)
- self.line(0,self.ymin,0,self.ymax,color)
- x = -self.xtick*(int(-self.xmin/self.xtick)+1)
- while x <= self.xmax:
- ix,iy = self.transform(x,0)
- gd.gdImageLine(self.im,ix,iy-self.ticklen,ix,iy+self.ticklen,color)
- x = x + self.xtick
- y = -self.ytick*(int(-self.ymin/self.ytick)+1)
- while y <= self.ymax:
- ix,iy = self.transform(0,y)
- gd.gdImageLine(self.im,ix-self.ticklen,iy,ix+self.ticklen,iy,color)
- y = y + self.ytick
-
- # scalex(s). Scales the x-axis. s is given as a scaling factor
- def scalex(self,s):
- xc = self.xmin + self.dx/2.0
- dx = self.dx*s
- xmin = xc - dx/2.0
- xmax = xc + dx/2.0
- self.region(xmin,self.ymin,xmax,self.ymax)
-
- # scaley(s). Scales the y-axis.
- def scaley(self,s):
- yc = self.ymin + self.dy/2.0
- dy = self.dy*s
- ymin = yc - dy/2.0
- ymax = yc + dy/2.0
- self.region(self.xmin,ymin,self.xmax,ymax)
-
- # Zooms a current image. s is given as a percent
- def zoom(self,s):
- s = 100.0/s
- self.scalex(s)
- self.scaley(s)
-
- # Move image left. s is given in range 0,100. 100 moves a full screen left
- def left(self,s):
- dx = self.dx*s/100.0
- xmin = self.xmin + dx
- xmax = self.xmax + dx
- self.region(xmin,self.ymin,xmax,self.ymax)
-
- # Move image right. s is given in range 0,100. 100 moves a full screen right
- def right(self,s):
- self.left(-s)
-
- # Move image down. s is given in range 0,100. 100 moves a full screen down
- def down(self,s):
- dy = self.dy*s/100.0
- ymin = self.ymin + dy
- ymax = self.ymax + dy
- self.region(self.xmin,ymin,self.xmax,ymax)
-
- # Move image up. s is given in range 0,100. 100 moves a full screen up
- def up(self,s):
- self.down(-s)
-
- # Center image
- def center(self,x,y):
- self.right(50-x)
- self.up(50-y)
-
-
-</pre></blockquote>
-Our image class provides a number of methods for creating images, plotting points, making lines, and other graphical objects. We have also provided some methods for moving and scaling the image. Now, let's use this image class to do some interesting things :<p>
-<p>
-<a name="n46"></a><h3> A mathematical function plotter </h3>
-Here's a simple class that can be used to plot mathematical functions :<p>
-<p>
-<blockquote><pre># funcplot.py
-
-from image import *
-
-class PlotFunc(Image):
- def __init__(self,func,xmin,ymin,xmax,ymax,width=500,height=500):
- Image.__init__(self,width,height,xmin,ymin,xmax,ymax)
- self.func = func # The function being plotted
- self.npoints = 100 # Number of samples
- self.color = 1
- def draw(self):
- self.clear(0)
- lastx = self.xmin
- lasty = self.func(lastx)
- dx = 1.0*(self.xmax-self.xmin)/self.npoints
- x = lastx+dx
- for i in range(0,self.npoints):
- y = self.func(x)
- self.line(lastx,lasty,x,y,self.color)
- lastx = x
- lasty = y
- x = x + dx
- self.axis(1)
-
-</pre></blockquote>
-Most of the functionality is implemented in our base image class so this is pretty simple. However, if we wanted to make a GIF image of a mathematical function, we could just do this :<p>
-<p>
-<blockquote><pre>>>> from funcplot import *
->>> import math
->>> p = PlotFunc(lambda x: 0.5*math.sin(x)+0.75*math.sin(2*x)-0.6*math.sin(3*x),
- -10,-2,10,2)
->>> p.show("plot.gif")
-
-</pre></blockquote>
-Which would produce the following GIF image :<p>
-<p><center><img src="ch9.1.png"></center><p>
-<p>
-<p>
-<a name="n47"></a><h3> Plotting an unstructured mesh</h3>
-Of course, perhaps we want to plot something a little more complicated like a mesh. Recently, a colleague came to me with some unstructured mesh data contained in a pair of ASCII formatted files. These files contained a collection of points, and a list of connectivities defining a mesh on these points. Reading and plotting this data in Python turned out to be relatively easy using the following script and our image base class :<p>
-<p>
-<blockquote><pre># plotmesh.py
-# Plots an unstructured mesh stored as an ASCII file
-from image import *
-import string
-
-class PlotMesh(Image):
- def __init__(self,filename,xmin,ymin,xmax,ymax,width=500,height=500):
- Image.__init__(self,width,height,xmin,ymin,xmax,ymax)
- # read in a mesh file in pieces
- pts = []
- # Read in data points
- atoi = string.atoi
- atof = string.atof
- f = open(filename+".pts","r")
- npoints = atoi(f.readline())
- for i in range(0,npoints):
- l = string.split(f.readline())
- pts.append((atof(l[0]),atof(l[1])))
- f.close()
-
- # Read in mesh data
- f = open(filename+".tris","r")
- ntris = string.atoi(f.readline())
- tris = [ ]
- for i in range(0,ntris):
- l = string.split(f.readline())
- tris.append((atoi(l[0])-1,atoi(l[1])-1,atoi(l[2])-1,atoi(l[3])))
- f.close()
-
- # Set up local attributes
- self.pts = pts
- self.npoints = npoints
- self.tris = tris
- self.ntris = ntris
-
- # Draw mesh
- def draw(self):
- self.clear(0);
- i = 0
- while i < self.ntris:
- tri = self.tris[i]
- pt1 = self.pts[tri[0]]
- pt2 = self.pts[tri[1]]
- pt3 = self.pts[tri[2]]
- # Now draw the mesh
- self.triangle(pt1[0],pt1[1],pt2[0],pt2[1],pt3[0],pt3[1],tri[3]);
- i = i + 1
-
- # Draw a triangle
- def triangle(self,x1,y1,x2,y2,x3,y3,color):
- self.line(x1,y1,x2,y2,color)
- self.line(x2,y2,x3,y3,color)
- self.line(x3,y3,x1,y1,color)
-
-</pre></blockquote>
-This class simply reads the data into a few Python lists, has a drawing function for making a plot, and adds a special method for making triangles. Making a plot is now easy, just do this :<p>
-<p>
-<blockquote><pre>>>> from plotmesh.py import *
->>> mesh = PlotMesh("mesh",5,0,35,25)
->>> mesh.show("mesh.gif")
-
-</pre></blockquote>
-This produces the following GIF image :<p>
-<p><center><img src="ch9.2.png"></center><p>
-<p>
-<p>
-When run interactively, we can also use simple commands to zoom in and move the image around. For example :<p>
-<p>
-<blockquote><pre>>>> mesh = PlotMesh("mesh",5,0,35,25)
->>> mesh.zoom(200) # Enlarge by 200%
->>> mesh.left(50) # Move image half a screen to left
->>> mesh.show()
->>>
-</pre></blockquote>
-<p>
-While a Python-only implementation would be unsuitable for huge datasets, performance critical operations could be moved to C and used in conjunction with our Image base class. <p>
-<a name="n48"></a><h3> From C to SWIG to Python</h3>
-This example illustrates a number of things that are possible with SWIG and Python. First, it is usually relatively easy to build a Python interface to an existing C library. With a little extra work, it is possible to improve the interface by adding a few support functions such as our Point extensions. Finally, once in Python, it is possible to encapsulate C libraries in new kinds of Python objects and classes. We built a simple Image base class and used it to plot mathematical functions and unstructured 2D mesh data---two entirely different tasks, yet easily accomplished with a small amount of Python code. If we later decided to use a different C library such as OpenGL, we could wrap it in SWIG, change the Image base class appropriately , and use the function and mesh plotting examples without modification. I think this is pretty cool.<p>
-<a name="n8"></a><h2> Putting it all together</h2>
-Finally, let's combine our heat equation solver and graphics module into a single application. To do this, we first need to know how to combine two different SWIG generated modules. When different SWIG modules need to be combined, there are a number of things you can do.<p>
-<a name="n49"></a><h3> Merging modules</h3>
-Two SWIG modules can be combined into a single module if you make an interface file like this :<p>
-<p>
-<blockquote><pre>%module package
-%include pde.i
-%include gd.i
-</pre></blockquote>
-<p>
-This will combine everything in both interface files into a single super-module called "package". The advantage to this approach is that it is extremely quick and easy. The disadvantage is that the module names of "pde" and "gd" will be lost. If you had a bunch of scripts that relied on those names, they would no longer work. Thus, combining modules in this way is probably only a good idea if the modules are closely related.<p>
-<a name="n50"></a><h3> Using dynamic loading</h3>
-If your system supports dynamic loading, you can build each SWIG module into a separate dynamically loadable module and load each one individually into Python. This is the preferred approach if it is supported on your system. SWIG wrapper files declare virtually everything as "static" so using dynamic loading with multiple SWIG generated modules will not usually cause any namespace clashes. <p>
-<a name="n51"></a><h3> Use static linking</h3>
-As an alternative to dynamic loading, you can use a special form of the <tt>%module</tt> directive as follows :<p>
-<p>
-<blockquote><pre>%module package, pdec, gdc
-%include embed.i
-
-</pre></blockquote>
-This will build a static version of Python with 3 C extension modules added (<tt>package</tt>, <tt>pdec</tt>, and <tt>gdc</tt>). When using this technique, the names of the modules refer to the low-level SWIG generated C/C++ modules. Since shadow classes are being used, these modules must have an extra `c' appended to the name (thus, "pdec" and "gdc" instead of "pde" and "gd"). The extra modules specified with the <tt>%modules</tt> directive do not necessarily have to be SWIG-generated modules. In practice, almost any kind of Python module can be listed here. It should also be noted that extra modules names are completely ignored if the <tt>embed.i </tt>library file is not used.<p>
-<a name="n52"></a><h3> Building large multi-module systems</h3>
-By default, SWIG includes the C code for the SWIG type-checker and variable linking into every module. However, when, building systems involving large numbers of SWIG modules, common code such as the SWIG pointer type-checker and variable linking extensions can be shared if you run SWIG with the <tt>-c</tt> option. For example :<p>
-<p>
-<blockquote><pre>% swig -c -python graphics.i
-% swig -c -python network.i
-% swig -c -python analysis.i
-% swig -c -python math.i
-% gcc -c graphics_wrap.c network_wrap.c analysis_wrap.c math_wrap.c
-% ld -shared graphics_wrap.o -lswigpy -o graphicsmodule.so
-% ld -shared network_wrap.o -lswigpy -o networkmodule.so
-% ld -shared analysis_wrap.o -lswigpy -o analysismodule.so
-% ld -shared math_wrap.o -o -lswigpy mymathmodule.so
-
-</pre></blockquote>
-<tt>swigpy</tt> is a special purpose library that contains the SWIG pointer type checker and other support code (see the <tt>Misc</tt> subdirectory of the SWIG distribution). When used in this manner, the same support code will be used for all of the modules. The <tt>swigpy</tt> library can also be applied when static linking is being used. See the Advanced Topics chapter for more information about using SWIG with multiple modules.<p>
-<a name="n53"></a><h3> A complete application</h3>
-The following Python script shows an application that combines our C++ heat equation solver, our gd library, and our Image base class that we developed. <p>
-<p>
-<blockquote><pre># Solve the heat equation.
-# Make a series of data files
-# Make a movie of GIF images
-
-from pde import *
-from image import *
-import string
-
-# Image class
-class HeatImg(Image):
- def __init__(self,h,width=300,height=300):
- Image.__init__(self,width,height,0.0,0.0,1.0,1.0)
- self.h = h
- # Create a greyscale colormap
- cmap = []
- for i in range(0,255):
- cmap.append((i,i,i))
- self.colormap(cmap)
- self.cmin = 0.0
- self.cmax = 1.0
- self.imgno = 1
- def draw(self):
- self.clear(0)
- dx = 1.0/(self.h.grid.xpoints-2)
- dy = 1.0/(self.h.grid.ypoints-2)
- i = 1
- x = 0.0
- while i < self.h.grid.xpoints:
- j = 1;
- y = 0.0
- while j < self.h.grid.ypoints:
- c = int((self.h.grid[i][j]-self.cmin)/(self.cmax-
- self.cmin)*255)
- self.solidbox(x,y+dy,x+dx,y,c)
- j = j + 1
- y = y + dy
- i = i + 1
- x = x + dx
- self.name = "image"+string.zfill(self.imgno,4)+".gif"
- self.imgno = self.imgno+1
-
-# Set up an initial condition
-def initcond(h):
- h.set_temp(0.0)
- nx = h.grid.xpoints
- for i in range(0,nx):
- h.grid[i][0] = 1.0
-
-# Set up a problem and run it
-h = Heat2d(50,50)
-
-# Make an image object
-img = HeatImg(h)
-
-initcond(h)
-fileno = 1
-
-# Run it
-for i in range(0,25):
- h.solve(100)
- h.dump("Dat"+str(fileno))
- img.show()
- print "time = ", h.time
- fileno = fileno+1
-
-# Calculate average temperature and exit
-sum = 0.0
-for i in range(0,h.grid.xpoints):
- for j in range(0,h.grid.ypoints):
- sum = sum + h.grid[i][j]
-avg = sum/(h.grid.xpoints*h.grid.ypoints)
-print "Avg temperature = ",avg
-</pre></blockquote>
-<p>
-When run, we now get a collection of datafiles and series of images like this :<p>
-<p><center><img src="ch9.3.png"></center><p>
-<p>
-<p>
-Thus, we have a simple physics application that only takes about 1 page of Python code, runs a simulation, creates data files, and a movie of images. We can easily change any aspect of the simulation, interactively query variables and examine data. New procedures can be written and tested in Python and later implemented in C++ if needed. More importantly, we have an application that is actually fun to use and modify (well, at least I think so).<p>
-<a name="n9"></a><h2> Exception handling </h2>
-The SWIG <tt>%except</tt> directive can be used to create a user-definable exception handler in charge of converting exceptions in your C/C++ program into Python exceptions. The chapter on exception handling contains more details, but suppose you have a C++ class like the following :<p>
-<blockquote><pre>
-class RangeError {}; // Used for an exception
-
-class DoubleArray {
- private:
- int n;
- double *ptr;
- public:
- // Create a new array of fixed size
- DoubleArray(int size) {
- ptr = new double[size];
- n = size;
- }
- // Destroy an array
- ~DoubleArray() {
- delete ptr;
- }
- // Return the length of the array
- int length() {
- return n;
- }
-
- // Get an item from the array and perform bounds checking.
- double getitem(int i) {
- if ((i >= 0) && (i < n))
- return ptr[i];
- else
- throw RangeError();
- }
-
- // Set an item in the array and perform bounds checking.
- void setitem(int i, double val) {
- if ((i >= 0) && (i < n))
- ptr[i] = val;
- else {
- throw RangeError();
- }
- }
- };
-</pre></blockquote>
-<p>
-The functions associated with this class can throw a range exception for an out-of-bounds array access. We can catch this in our Python extension by specifying the following in an interface file :<p>
-<p>
-<blockquote><pre>%except(python) {
- try {
- $function
- }
- catch (RangeError) {
- PyErr_SetString(PyExc_IndexError,"index out-of-bounds");
- return NULL;
- }
-}
-
-</pre></blockquote>
-When the C++ class throws a RangeError exception, our wrapper functions will catch it, turn it into a Python exception, and allow a graceful death as opposed to just having some sort of mysterious program crash. Since SWIG's exception handling is user-definable, we are not limited to C++ exception handling. Please see the chapter on exception handling for more details and using the <tt>exception.i</tt> library for writing language-independent exception handlers.<p>
-<p>
-Python exceptions can be raised using the <tt>PyErr_SetString()</tt> function as shown above. The following table provides a list of the different Python exceptions available.<p>
-<center><img src="ch9.table.1.png"></center><p>
-<p>
-<a name="n10"></a><h2> Remapping C datatypes with typemaps</h2>
-This section describes how SWIG's treatment of various C/C++ datatypes can be remapped using the SWIG <tt>%typemap</tt> directive. While not required, this section assumes some familiarity with Python's C API. The reader is advised to consult the Python reference manual or one of the books on Python. A glance at the chapter on SWIG typemaps will also be useful. <p>
-<a name="n54"></a><h3> What is a typemap?</h3>
-A typemap is mechanism by which SWIG's processing of a particular C datatype can be overridden. A simple typemap might look like this :<p>
-<p>
-<blockquote><pre>%module example
-
-%typemap(python,in) int {
- $target = (int) PyLong_AsLong($source);
- printf("Received an integer : %d\n",$target);
-}
-extern int fact(int n);
-</pre></blockquote>
-<p>
-Typemaps require a language name, method name, datatype, and conversion code. For Python, "python" should be used as the language name. The "in" method in this example refers to an input argument of a function. The datatype `int' tells SWIG that we are remapping integers. The supplied code is used to convert from a <tt>PyObject *</tt> to the corresponding C datatype. Within the supporting C code, the variable <tt>$source</tt> contains the source data (the <tt>PyObject</tt> in this case) and <tt>$target</tt> contains the destination of a conversion. <p>
-<p>
-When this example is compiled into a Python module, it will operate as follows :<p>
-<p>
-<blockquote><pre>>>> from example import *
->>> fact(6)
-Received an integer : 6
-720
-</pre></blockquote>
-<p>
-A full discussion of typemaps can be found in the main SWIG users reference. We will primarily be concerned with Python typemaps here.<p>
-<a name="n55"></a><h3> Python typemaps</h3>
-The following typemap methods are available to Python modules :<p>
-<p>
-<tt>%typemap(python,in) </tt>Converts Python objects to input function arguments<p>
-<tt>%typemap(python,out)</tt> Converts return value of a C function to a Python object<p>
-<tt>%typemap(python,varin) </tt>Assigns a global variable from a Python object<p>
-<tt>%typemap(python,varout)</tt> Returns a global variable as a Python object<p>
-<tt>%typemap(python,freearg)</tt> Cleans up a function argument (if necessary)<p>
-<tt>%typemap(python,argout)</tt> Output argument processing<p>
-<tt>%typemap(python,ret)</tt> Cleanup of function return values<p>
-<tt>%typemap(python,const)</tt> Creation of Python constants<p>
-<tt>%typemap(memberin)</tt> Setting of C++ member data<p>
-<tt>%typemap(memberout)</tt> Return of C++ member data<p>
-<tt>%typemap(python,check)</tt> Checks function input values.<p>
-<a name="n56"></a><h3> Typemap variables</h3>
-The following variables may be used within the C code used in a typemap:<p>
-<p>
-<tt>$source</tt> Source value of a conversion<p>
-<tt>$target</tt> Target of conversion (where the result should be stored)<p>
-<tt>$type</tt> C datatype being remapped<p>
-<tt>$mangle</tt> Mangled version of data (used for pointer type-checking)<p>
-<tt>$value</tt> Value of a constant (const typemap only)<p>
-<a name="n57"></a><h3> Name based type conversion</h3>
-Typemaps are based both on the datatype and an optional name attached to a datatype. For example :<p>
-<p>
-<blockquote><pre>%module foo
-
-// This typemap will be applied to all char ** function arguments
-%typemap(python,in) char ** { ... }
-
-// This typemap is applied only to char ** arguments named `argv'
-%typemap(python,in) char **argv { ... }
-
-</pre></blockquote>
-In this example, two typemaps are applied to the <tt>char **</tt> datatype. However, the second typemap will only be applied to arguments named `<tt>argv</tt>'. A named typemap will always override an unnamed typemap.<p>
-<p>
-Due to the name-based nature of typemaps, it is important to note that typemaps are independent of typedef declarations. For example :<p>
-<p>
-<blockquote><pre>%typemap(python, in) double {
- ... get a double ...
-}
-void foo(double); // Uses the above typemap
-typedef double Real;
-void bar(Real); // Does not use the above typemap (double != Real)
-
-</pre></blockquote>
-To get around this problem, the <tt>%apply</tt> directive can be used as follows :<p>
-<blockquote><pre>
-%typemap(python,in) double {
- ... get a double ...
-}
-void foo(double);
-
-typedef double Real; // Uses typemap
-%apply double { Real }; // Applies all "double" typemaps to Real.
-void bar(Real); // Now uses the same typemap.
-</pre></blockquote>
-<a name="n58"></a><h3> Converting Python list to a char ** </h3>
-A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Python list object to be used as a <tt>char **</tt> object.<p>
-<p>
-<blockquote><pre>%module argv
-
-// This tells SWIG to treat char ** as a special case
-%typemap(python,in) char ** {
- /* Check if is a list */
- if (PyList_Check($source)) {
- int size = PyList_Size($source);
- int i = 0;
- $target = (char **) malloc((size+1)*sizeof(char *));
- for (i = 0; i < size; i++) {
- PyObject *o = PyList_GetItem($source,i);
- if (PyString_Check(o))
- $target[i] = PyString_AsString(PyList_GetItem($source,i));
- else {
- PyErr_SetString(PyExc_TypeError,"list must contain strings");
- free($target);
- return NULL;
- }
- }
- $target[i] = 0;
- } else {
- PyErr_SetString(PyExc_TypeError,"not a list");
- return NULL;
- }
-}
-
-// This cleans up the char ** array we malloc'd before the function call
-%typemap(python,freearg) char ** {
- free((char *) $source);
-}
-
-// This allows a C function to return a char ** as a Python list
-%typemap(python,out) char ** {
- int len,i;
- len = 0;
- while ($source[len]) len++;
- $target = PyList_New(len);
- for (i = 0; i < len; i++) {
- PyList_SetItem($target,i,PyString_FromString($source[i]));
- }
-}
-
-// Now a few test functions
-%inline %{
-int print_args(char **argv) {
- int i = 0;
- while (argv[i]) {
- printf("argv[%d] = %s\n", i,argv[i]);
- i++;
- }
- return i;
-}
-
-// Returns a char ** list
-
-char **get_args() {
- static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
- return &values[0];
-}
-%}
-
-</pre></blockquote>
-When this module is compiled, our wrapped C functions now operate as follows :<p>
-<p>
-<blockquote><pre>>>> from argv import *
->>> print_args(["Dave","Mike","Mary","Jane","John"])
-argv[0] = Dave
-argv[1] = Mike
-argv[2] = Mary
-argv[3] = Jane
-argv[4] = John
-5
->>> get_args()
-[`Dave', `Mike', `Susan', `John', `Michelle']
->>>
-
-</pre></blockquote>
-Our type-mapping makes the Python interface to these functions more natural and easy to use. <p>
-<a name="n59"></a><h3> Converting a Python file object to a FILE *</h3>
-In our previous example involving gd-1.2, we had to write wrappers around <tt>fopen()</tt> and <tt>fclose()</tt> so that we could provide gd with a <tt>FILE *</tt> pointer. However, we could have used a typemap like this instead :<p>
-<p>
-<blockquote><pre>// Type mapping for grabbing a FILE * from Python
-
-%typemap(python,in) FILE * {
- if (!PyFile_Check($source)) {
- PyErr_SetString(PyExc_TypeError, "Need a file!");
- return NULL;
- }
- $target = PyFile_AsFile($source);
-}
-</pre></blockquote>
-<p>
-Now, we can rewrite one of our earlier examples like this :<p>
-<p>
-<blockquote><pre># Simple gd program
-
-from gd import *
-
-im = gdImageCreate(64,64)
-black = gdImageColorAllocate(im,0,0,0)
-white = gdImageColorAllocate(im,255,255,255)
-gdImageLine(im,0,0,63,63,white)
-f = open("test.gif","w") # Create a Python file object
-gdImageGif(im,f) # Pass to a C function as FILE *
-f.close()
-gdImageDestroy(im)
-</pre></blockquote>
-<a name="n60"></a><h3> Using typemaps to return arguments</h3>
-A common problem in some C programs is that values may be returned in arguments rather than in the return value of a function. For example :<p>
-<p>
-<blockquote><pre>/* Returns a status value and two values in out1 and out2 */
-int spam(double a, double b, double *out1, double *out2) {
- ... Do a bunch of stuff ...
- *out1 = result1;
- *out2 = result2;
- return status;
-};
-
-</pre></blockquote>
-A named typemap can be used to handle this case as follows :<p>
-<p>
-<blockquote><pre>%module outarg
-
-// This tells SWIG to treat an double * argument with name 'OutValue' as
-// an output value. We'll append the value to the current result which
-// is guaranteed to be a List object by SWIG.
-
-%typemap(python,argout) double *OutValue {
- PyObject *o;
- o = PyFloat_FromDouble(*$source);
- if ((!$target) || ($target == Py_None)) {
- $target = o;
- } else {
- if (!PyList_Check($target)) {
- PyObject *o2 = $target;
- $target = PyList_New(0);
- PyList_Append($target,o2);
- Py_XDECREF(o2);
- }
- PyList_Append($target,o);
- Py_XDECREF(o);
- }
-}
-int spam(double a, double b, double *OutValue, double *OutValue);
-
-</pre></blockquote>
-With this typemap, we first check to see if any result exists. If so, we turn it into a list and append our new output value to it. If this is the only result, we simply return it normally. For our sample function, there are three output values so the function will return a list of 3 elements. As written, our function needs to take 4 arguments, the last two being pointers to doubles. We may not want to pass anything into these arguments if they are only used to hold output values so we could change this as follows :<p>
-<blockquote><pre>
-%typemap(python,ignore) double *OutValue(double temp) {
- $target = &temp; /* Assign the pointer to a local variable */
-}
-
-</pre></blockquote>
-Now, in a Python script, we could do this :<p>
-<p>
-<blockquote><pre>>>> a = spam(4,5)
->>> print a
-[0, 2.45, 5.0]
->>>
-</pre></blockquote>
-<a name="n61"></a><h3> Mapping Python tuples into small arrays</h3>
-In some applications, it is sometimes desirable to pass small arrays of numbers as arguments. For example :<p>
-<p>
-<blockquote><pre>extern void set_direction(double a[4]); // Set direction vector
-</pre></blockquote>
-<p>
-This too, can be handled used typemaps as follows :<p>
-<p>
-<blockquote><pre>// Grab a 4 element array as a Python 4-tuple
-%typemap(python,in) double[4](double temp[4]) { // temp[4] becomes a local variable
- int i;
- if (PyTuple_Check($source)) {
- if (!PyArg_ParseTuple($source,"dddd",temp,temp+1,temp+2,temp+3)) {
- PyErr_SetString(PyExc_TypeError,"tuple must have 4 elements");
- return NULL;
- }
- $target = &temp[0];
- } else {
- PyErr_SetString(PyExc_TypeError,"expected a tuple.");
- return NULL;
- }
-}
-
-</pre></blockquote>
-This allows our <tt>set_direction</tt> function to be called from Python as follows :<p>
-<p>
-<blockquote><pre>>>> set_direction((0.5,0.0,1.0,-0.25))
-
-</pre></blockquote>
-Since our mapping copies the contents of a Python tuple into a C array, such an approach would not be recommended for huge arrays, but for small structures, this kind of scheme works fine.<p>
-<a name="n62"></a><h3> Accessing array structure members</h3>
-Consider the following data structure :<p>
-<p>
-<blockquote><pre>#define NAMELEN 32
-typedef struct {
- char name[NAMELEN];
- ...
-} Person;
-
-</pre></blockquote>
-By default, SWIG doesn't know how to the handle the name structure since it's an array, not a pointer. In this case, SWIG will make the array member readonly. However, member typemaps can be used to make this member writable from Python as follows :<p>
-<p>
-<blockquote><pre>%typemap(memberin) char[NAMELEN] {
- /* Copy at most NAMELEN characters into $target */
- strncpy($target,$source,NAMELEN);
-}
-
-</pre></blockquote>
-Whenever a <tt>char[NAMELEN]</tt> type is encountered in a structure or class, this typemap provides a safe mechanism for setting its value. An alternative implementation might choose to print an error message if the name was too long to fit into the field.<p>
-<p>
-It should be noted that the <tt>[NAMELEN]</tt> array size is attached to the typemap. A datatype involving some other kind of array would not be affected. However, you can write a typemap to match any sized array using the <tt>ANY</tt> keyword as follows :<p>
-<p>
-<blockquote><pre>%typemap(memberin) char [ANY] {
- strncpy($target,$source,$dim0);
-}
-</pre></blockquote>
-<p>
-During code generation, <tt>$dim0</tt> will be filled in with the real array dimension. <p>
-<a name="n63"></a><h3> Useful Functions</h3>
-When writing typemaps, it is often necessary to work directly with Python objects instead of using the conventional <tt>PyArg_ParseTuple()</tt> function that is usually used when writing Python extensions. However, there are a number of useful Python functions available for you to use.<p>
-<center>
-<img src="ch9.table.2.png"><br>
-<img src="ch9.table.3.png"><br>
-<img src="ch9.table.4.png"><br>
-<img src="ch9.table.5.png"><br>
-<img src="ch9.table.6.png"><br>
-<img src="ch9.table.7.png"><br>
-</center><p>
-<p>
-<a name="n64"></a><h3> Standard typemaps</h3>
-The following typemaps show how to convert a few common kinds of objects between Python and C (and to give a better idea of how typemaps work)<p>
-<center>
-<img src="ch9.table.8.png"><br>
-<img src="ch9.table.9.png"><br>
-</center><p>
-<p>
-<a name="n65"></a><h3> Pointer handling</h3>
-SWIG pointers are mapped into Python strings containing the hexadecimal value and type. The following functions can be used to create and read pointer values.<p>
-<center>
-<img src="ch9.table.10.png">
-</center><p>
-<p>
-These functions can be used in typemaps. For example, the following typemap makes an argument of "<tt>char *buffer</tt>" accept a pointer instead of a NULL-terminated ASCII string.<p>
-<p>
-<blockquote><pre>%typemap(python,in) char *buffer {
- PyObject *o;
- char *str;
- if (!PyString_Check(o)) {
- PyErr_SetString(PyExc_TypeError,"not a string");
- return NULL;
- }
- str = PyString_AsString(o);
- if (SWIG_GetPtr(str, (void **) &$target, "$mangle")) {
- PyErr_SetString(PyExc_TypeError,"not a pointer");
- return NULL;
- }
-}
-
-</pre></blockquote>
-Note that the <tt>$mangle</tt> variable generates the type string associated with the datatype used in the typemap.<p>
-<p>
-By now you hopefully have the idea that typemaps are a powerful mechanism for building more specialized applications. While writing typemaps can be technical, many have already been written for you. See the Typemaps chapter for more information about using library files.<p>
-<a name="n11"></a><h2> Implementing C callback functions in Python</h2>
-Now that you're an expert, we will implement simple C callback functions in Python and use them in a C++ code.<p>
-<p>
-Let's say that we wanted to write a simple C++ 2D plotting widget layered on top of the gd-1.2 library. A class definition might look like this :<p>
-<p>
-<blockquote><pre>// --------------------------------------------------------------------
-// Create a C++ plotting "widget" using the gd-1.2 library by Thomas Boutell
-//
-// This example primarily illustrates how callback functions can be
-// implemented in Python.
-// --------------------------------------------------------------------
-
-#include <stdio.h>
-extern "C" {
-#include "gd.h"
-}
-
-typedef double (*PLOTFUNC)(double, void *);
-
-class PlotWidget {
-private:
- double xmin,ymin,xmax,ymax; // Plotting range
- PLOTFUNC callback; // Callback function
- void *clientdata; // Client data for callback
- int npoints; // Number of points to plot
- int width; // Image width
- int height; // Image height
- int black,white; // Some colors
- gdImagePtr im; // Image pointer
- void transform(double,double,int&,int&);
-public:
- PlotWidget(int w, int h,double,double,double,double);
- ~PlotWidget();
- void set_method(PLOTFUNC func, void *clientdata); // Set callback method
- void set_range(double,double,double,double); // Set plot range
- void set_points(int np) {npoints = np;} // Set number of points
- void plot(); // Make a plot
- void save(FILE *f); // Save a plot to disk
-};
-
-</pre></blockquote>
-The widget class hides all of the underlying implementation details so this could have just as easily been implemented on top of OpenGL, X11 or some other kind of library. When used in C++, the widget works like this :<p>
-<p>
-<blockquote><pre>// Simple main program to test out our widget
-#include <stdio.h>
-#include "widget.h"
-#include <math.h>
-
-// Callback function
-double my_func(double a, void *clientdata) {
- return sin(a);
-}
-
-int main(int argc, char **argv) {
- PlotWidget *w;
- FILE *f;
-
- w = new PlotWidget(500,500,-6.3,-1.5,6.3,1.5);
- w->set_method(my_func,0); // Set callback function
- w->plot(); // Make plot
- f = fopen("plot.gif","w");
- w->save(f);
- fclose(f);
- printf("wrote plot.gif\n");
-}
-
-</pre></blockquote>
-Now suppose that we wanted to use our widget interactively from Python. While possible, it is going to be difficult because we would really like to implement the callback function in Python, not C++. We also don't want to go in and hack or C++ code to support this. Fortunately, you can do it with SWIG using the following interface file :<p>
-<p>
-<blockquote><pre>// SWIG interface to our PlotWidget
-%module plotwidget
-%{
-#include "widget.h"
-%}
-
-// Grab a Python function object as a Python object.
-%typemap(python,in) PyObject *pyfunc {
- if (!PyCallable_Check($source)) {
- PyErr_SetString(PyExc_TypeError, "Need a callable object!");
- return NULL;
- }
- $target = $source;
-}
-
-// Type mapping for grabbing a FILE * from Python
-%typemap(python,in) FILE * {
- if (!PyFile_Check($source)) {
- PyErr_SetString(PyExc_TypeError, "Need a file!");
- return NULL;
- }
- $target = PyFile_AsFile($source);
-}
-
-// Grab the class definition
-%include widget.h
-
-%{
-/* This function matches the prototype of the normal C callback
- function for our widget. However, we use the clientdata pointer
- for holding a reference to a Python callable object. */
-
-static double PythonCallBack(double a, void *clientdata)
-{
- PyObject *func, *arglist;
- PyObject *result;
- double dres = 0;
-
- func = (PyObject *) clientdata; // Get Python function
- arglist = Py_BuildValue("(d)",a); // Build argument list
- result = PyEval_CallObject(func,arglist); // Call Python
- Py_DECREF(arglist); // Trash arglist
- if (result) { // If no errors, return double
- dres = PyFloat_AsDouble(result);
- }
- Py_XDECREF(result);
- return dres;
-}
-%}
-
-// Attach a new method to our plot widget for adding Python functions
-%addmethods PlotWidget {
- // Set a Python function object as a callback function
- // Note : PyObject *pyfunc is remapped with a typempap
- void set_pymethod(PyObject *pyfunc) {
- self->set_method(PythonCallBack, (void *) pyfunc);
- Py_INCREF(pyfunc);
- }
-}
-
-</pre></blockquote>
-While this is certainly not a trivial SWIG interface file, the results are quite cool. Let's try out our new Python module :<p>
-<p>
-<blockquote><pre># Now use our plotting widget in variety of ways
-
-from plotwidget import *
-from math import *
-
-# Make a plot using a normal Python function as a callback
-def func1(x):
- return 0.5*sin(x)+0.25*sin(2*x)+0.125*cos(4*x)
-
-print "Making plot1.gif..."
-# Make a widget and set callback
-w = PlotWidget(500,500,-10,-2,10,2)
-w.set_pymethod(func1) # Register our Python function
-w.plot()
-f = open("plot1.gif","w")
-w.save(f)
-f.close()
-
-# Make a plot using an anonymous function
-
-print "Making plot2.gif..."
-w1 = PlotWidget(500,500,-4,-1,4,16)
-w1.set_pymethod(lambda x: x*x) # Register x^2 as a callback
-w1.plot()
-f = open("plot2.gif","w")
-w1.save(f)
-f.close()
-
-# Make another plot using a built-in function
-
-print "Making plot3.gif..."
-w2 = PlotWidget(500,500,-7,-1.5,7,1.5)
-w2.set_pymethod(sin) # Register sin(x) as a callback
-w2.plot()
-f = open("plot3.gif","w")
-w2.save(f)
-f.close()
-</pre></blockquote>
-<p>
-<p>
-The "plot" method for each widget is written entirely in C++ and assumes that it is calling a callback function written in C/C++. Little does it know that we have actually implemented this function in Python. With a little more work, we can even write a simple function plotting tool :<p>
-<p>
-<blockquote><pre># Plot a function and spawn xv
-
-import posix
-import sys
-import string
-from plotwidget import *
-from math import *
-
-line = raw_input("Enter a function of x : ")
-ranges = string.split(raw_input("Enter xmin,ymin,xmax,ymax :"),",")
-
-print "Making a plot..."
-w = PlotWidget(500,500,string.atof(ranges[0]),string.atof(ranges[1]),
- string.atof(ranges[2]),string.atof(ranges[3]))
-
-# Turn user input into a Python function
-code = "def func(x): return " + line
-exec(code)
-
-w.set_pymethod(func)
-w.plot()
-f = open("plot.gif","w")
-w.save(f)
-f.close()
-posix.system("xv plot.gif &")
-
-</pre></blockquote>
-<a name="n12"></a><h2> Other odds and ends</h2>
-<a name="n66"></a><h3> Adding native Python functions to a SWIG module</h3>
-Sometimes it is desirable to add a native Python method to a SWIG wrapper file. Suppose you have the following Python/C function :<p>
-<p>
-<blockquote><pre>PyObject *spam_system(PyObject *self, PyObject *args) {
- char *command;
- int sts;
- if (!PyArg_ParseTuple(args,"s",&command))
- return NULL;
- sts = system(command);
- return Py_BuildValue("i",sts);
-}
-
-</pre></blockquote>
-This function can be added to a SWIG module using the following declaration :<p>
-<p>
-<blockquote><pre>%native(system) spam_system; // Create a command called `system'
-
-</pre></blockquote>
-Alternatively, you can use the full function declaration like this <p>
-<p>
-<blockquote><pre>%native(system) PyObject *spam_system(PyObject *self, PyObject *args);
-</pre></blockquote>
-<p>
-or<p>
-<p>
-<blockquote><pre>%native(system) extern PyObject *spam_system(PyObject *self, PyObject *args);
-</pre></blockquote>
-<a name="n13"></a><h2> The gory details of shadow classes</h2>
-This section describes the process by which SWIG creates shadow classes and some of the more subtle aspects of using them.<p>
-<a name="n67"></a><h3> A simple shadow class</h3>
-Consider the following declaration from our previous example :<p>
-<p>
-<blockquote><pre>%module pde
-struct Grid2d {
- Grid2d(int ni, int nj);
- ~Grid2d();
- double **data;
- int xpoints;
- int ypoints;
-};
-</pre></blockquote>
-<p>
-The SWIG generated class for this structure looks like the following :<p>
-<p>
-<blockquote><pre># This file was created automatically by SWIG.
-import pdec
-class Grid2dPtr :
- def __init__(self,this):
- self.this = this
- self.thisown = 0
- def __del__(self):
- if self.thisown == 1 :
- pdec.delete_Grid2d(self.this)
- def __setattr__(self,name,value):
- if name == "data" :
- pdec.Grid2d_data_set(self.this,value)
- return
- if name == "xpoints" :
- pdec.Grid2d_xpoints_set(self.this,value)
- return
- if name == "ypoints" :
- pdec.Grid2d_ypoints_set(self.this,value)
- return
- self.__dict__[name] = value
- def __getattr__(self,name):
- if name == "data" :
- return pdec.Grid2d_data_get(self.this)
- if name == "xpoints" :
- return pdec.Grid2d_xpoints_get(self.this)
- if name == "ypoints" :
- return pdec.Grid2d_ypoints_get(self.this)
- return self.__dict__[name]
- def __repr__(self):
- return "<C Grid2d instance>"
-class Grid2d(Grid2dPtr):
- def __init__(self,arg0,arg1) :
- self.this = pdec.new_Grid2d(arg0,arg1)
- self.thisown = 1
-
-</pre></blockquote>
-<a name="n68"></a><h3> Module names</h3>
-Shadow classes are built using the low-level SWIG generated C interface. This interface is named "modulec" where "module" is the name of the module specified in a SWIG interface file. The Python code for the shadow classes is created in a file "module.py". This is the file that should be loaded when a user wants to use the module.<p>
-<a name="n69"></a><h3> Two classes</h3>
-For each structure or class found in an interface file, SWIG creates two Python classes. If a class is named "<tt>Grid2d</tt>", one of these classes will be named "<tt>Grid2dPtr</tt>" and the other named "<tt>Grid2d</tt>". The <tt>Grid2dPtr</tt> class is used to turn wrap a Python class around an already preexisting <tt>Grid2d</tt> pointer. For example :<p>
-<p>
-<blockquote><pre>>>> gptr = create_grid2d() # Returns a Grid2d from somewhere
->>> g = Grid2dPtr(gptr) # Turn it into a Python class
->>> g.xpoints
-50
->>>
-
-</pre></blockquote>
-The <tt>Grid2d</tt> class, on the other hand, is used when you want to create a new <tt>Grid2d</tt> object from Python. In reality, it inherits all of the attributes of a <tt>Grid2dPtr</tt>, except that its constructor calls the corresponding C++ constructor to create a new object. Thus, in Python, this would look something like the following :<p>
-<p>
-<blockquote><pre>>>> g = Grid2d(50,50) # Create a new Grid2d
->>> g.xpoints
-50
->>>
-
-</pre></blockquote>
-This two class model is a tradeoff. In order to support C/C++ properly, it is necessary to be able to create Python objects from both pre-existing C++ objects and to create entirely new C++ objects in Python. While this might be accomplished using a single class, it would complicate the handling of constructors considerably. The two class model, on the other hand, works, is consistent, and is relatively easy to use. In practice, you probably won't even be aware that there are two classes working behind the scenes.<p>
-<a name="n70"></a><h3> The this pointer</h3>
-Within each shadow class, the member "<tt>this</tt>" contains the actual C/C++ pointer to the object. You can check this out yourself by typing something like this :<p>
-<p>
-<blockquote><pre>>>> g = Grid2d(50,50)
->>> print g.this
-_1008fe8_Grid2d_p
->>>
-</pre></blockquote>
-<p>
-Direct manipulation of the "<tt>this</tt>" pointer is generally discouraged. In fact forget that you read this.<p>
-<a name="n71"></a><h3> Object ownership</h3>
-Ownership is a critical issue when mixing C++ and Python. For example, suppose I create a new object in C++, but later use it to create a Python object. If that object is being used elsewhere in the C++ code, we clearly don't want Python to delete the C++ object when the Python object is deleted. Similarly, what if I create a new object in Python, but C++ saves a pointer to it and starts using it repeatedly. Clearly, we need some notion of who owns what. Since sorting out all of the possibilities is probably impossible, SWIG shadow classes always have an attribute "<tt>thisown</tt>" that indicates whether or not Python owns an object. Whenever an object is created in Python, Python will be given ownership by setting <tt>thisown </tt> to <tt> 1</tt>. When a Python class is created from a pre-existing C/C++ pointer, ownership is assumed to belong to the C/C++ code and <tt>thisown</tt> will be set to 0.<p>
-<p>
-Ownership of an object can be changed as necessary by changing the value of <tt>thisown</tt>. When set, Python will call the C/C++ destructor when the object is deleted. If it is zero, Python will never call the C/C++ destructor.<p>
-<a name="n72"></a><h3> Constructors and Destructors</h3>
-C++ constructors and destructors will be mapped into Python's <tt>__init__</tt> and <tt>__del__</tt> methods respectively. Shadow classes always contain these methods even if no constructors or destructors were available in the SWIG interface file. The Python destructor will only call a C/C++ destructor if <tt>self.thisown</tt> is set.<p>
-<a name="n73"></a><h3> Member data</h3>
-Member data of an object is accessed through Python's <tt>__getattr__</tt> and <tt>__setattr__</tt> methods.<p>
-<a name="n74"></a><h3> Printing</h3>
-SWIG automatically creates a Python<tt> __repr__</tt> method for each class. This forces the class to be relatively well-behaved when printing or being used interactively in the Python interpreter.<p>
-<a name="n75"></a><h3> Shadow Functions</h3>
-Suppose you have the following declarations in an interface file :<p>
-<p>
-<blockquote><pre>%module vector
-struct Vector {
- Vector();
- ~Vector();
- double x,y,z;
-};
-
-Vector addv(Vector a, Vector b);
-
-</pre></blockquote>
-By default, the function <tt>addv</tt> will operate on <tt>Vector</tt> pointers, not Python classes. However, the SWIG Python module is smart enough to know that <tt>Vector</tt> has been wrapped into a Python class so it will create the following replacement for the <tt>addv()</tt> function.<p>
-<p>
-<blockquote><pre>def addv(a,b):
- result = VectorPtr(vectorc.addv(a.this,b.this))
- result.thisown = 1
- return result
-
-</pre></blockquote>
-Function arguments are modified to use the "this" pointer of a Python Vector object. The result is a pointer to the result which has been allocated by malloc or new (this behavior is described in the chapter on SWIG basics), so we simply create a new VectorPtr with the return value. Since the result involved an implicit malloc, we set the ownership to 1 indicating that the result is to be owned by Python and that it should be deleted when the Python object is deleted. As a result, operations like this are perfectly legal and result in no memory leaks :<p>
-<p>
-<blockquote><pre>>>> v = add(add(add(add(a,b),c),d),e)
-
-</pre></blockquote>
-Substitution of complex datatypes occurs for all functions and member functions involving structure or class definitions. It is rarely necessary to use the low-level C interface when working with shadow classes.<p>
-<a name="n76"></a><h3> Nested objects</h3>
-SWIG shadow classes support nesting of complex objects. For example, suppose you had the following interface file :<p>
-<p>
-<blockquote><pre>%module particle
-
-typedef struct {
- Vector();
- double x,y,z;
-} Vector;
-
-typedef struct {
- Particle();
- ~Particle();
- Vector r;
- Vector v;
- Vector f;
- int type;
-} Particle;
-
-</pre></blockquote>
-<p>
-In this case you will be able to access members as follows :<p>
-<p>
-<blockquote><pre>>>> p = Particle()
->>> p.r.x = 0.0
->>> p.r.y = -1.5
->>> p.r.z = 2.0
->>> p.v = addv(v1,v2)
->>> ...
-
-</pre></blockquote>
-Nesting of objects is implemented using Python's<tt> __setattr__</tt> and <tt>__getattr__</tt> functions. In this case, they would look like this :<p>
-<p>
-<blockquote><pre>class ParticlePtr:
- ...
- def __getattr__(self,name):
- if name == "r":
- return particlec.VectorPtr(Particle_r_get(self.this))
- elif name == "v":
- return particlec.VectorPtr(Particle_v_get(self.this))
- ...
-
- def __setattr__(self,name,value):
- if name == "r":
- particlec.Particle_r_set(self.this,value.this)
- elif name == "v":
- particlec.Particle_v_set(self.this,value.this)
- ...
-
-</pre></blockquote>
-The attributes of any given object are only converted into a Python object when referenced. This approach is more memory efficient, faster if you have a large collection of objects that aren't examined very often, and works with recursive structure definitions such as :<p>
-<p>
-<blockquote><pre>struct Node {
- char *name;
- struct Node *next;
-};
-</pre></blockquote>
-<p>
-Nested structures such as the following are also supported by SWIG. These types of structures tend to arise frequently in database and information processing applications.<p>
-<p>
-<blockquote><pre>typedef struct {
- unsigned int dataType;
- union {
- int intval;
- double doubleval;
- char *charval;
- void *ptrvalue;
- long longval;
- struct {
- int i;
- double f;
- void *v;
- char name[32];
- } v;
- } u;
-} ValueStruct;
-
-</pre></blockquote>
-Access is provided in an entirely natural manner,<p>
-<p>
-<blockquote><pre>>>> v = new_ValueStruct() # Create a ValueStruct somehow
->>> v.dataType
-1
->>> v.u.intval
-45
->>> v.u.longval
-45
->>> v.u.v.v = _0_void_p
->>>
-
-</pre></blockquote>
-To support the embedded structure definitions, SWIG has to extract the internal structure definitions and use them to create new Python classes. In this example, the following shadow classes are created :<p>
-<p>
-<blockquote><pre># Class corresponding to union u member
-class ValueStruct_u :
- ...
-# Class corresponding to struct v member of union u
-class ValueStruct_u_v :
- ...
-</pre></blockquote>
-<p>
-The names of the new classes are formed by appending the member names of each embedded structure.<p>
-<a name="n77"></a><h3> Inheritance and shadow classes</h3>
-Since shadow classes are implemented in Python, you can use any of the automatically generated classes as a base class for more Python classes. However, you need to be extremely careful when using multiple inheritance. When multiple inheritance is used, at most ONE SWIG generated shadow class can be involved. If multiple SWIG generated classes are used in a multiple inheritance hierarchy, you will get name clashes on the <tt>this</tt> pointer, the <tt>__getattr__</tt> and <tt>__setattr__</tt> functions won't work properly and the whole thing will probably crash and burn. Perhaps it's best to think of multiple inheritance as a big hammer that can be used to solve alot of problems, but it hurts quite alot if you accidently drop it on your foot.... <p>
-<a name="n78"></a><h3> Methods that return new objects</h3>
-By default SWIG assumes that constructors are the only functions returning new objects to Python. However, you may have other functions that return new objects as well. For example :<p>
-<blockquote><pre>
-Vector *cross_product(Vector *v1, Vector *v2) {
- Vector *result = new Vector();
- result = ... compute cross product ...
- return result;
-}
-
-</pre></blockquote>
-When the value is returned to Python, we want Python to assume ownership. The brute force way to do this is to simply change the value of thisown. For example :<p>
-<p>
-<blockquote><pre>>>> v = cross_product(a,b)
->>> v.thisown = 1 # Now Python owns it
-
-</pre></blockquote>
-Unfortunately, this is ugly and it doesn't work if we use the result as a temporary value :<p>
-<p>
-<blockquote><pre>w = vector_add(cross_product(a,b),c) # Results in a memory leak
-</pre></blockquote>
-<p>
-However, you can provide a hint to SWIG when working with such a function as shown :<p>
-<p>
-<blockquote><pre>// C Function returning a new object
-%new Vector *cross_product(Vector *v1, Vector *v2);
-
-</pre></blockquote>
-The <tt>%new</tt> directive only provides a hint that the function is returning a new object. The Python module will assign proper ownership of the object when this is used.<p>
-<a name="n79"></a><h3> Performance concerns and hints</h3>
-Shadow classing is primarily intended to be a convenient way of accessing C/C++ objects from Python. However, if you're directly manipulating huge arrays of complex objects from Python, performance may suffer greatly. In these cases, you should consider implementing the functions in C or thinking of ways to optimize the problem.<p>
-<p>
-There are a number of ways to optimize programs that use shadow classes. Consider the following two code fragments involving the <tt>Particle</tt> data structure in a previous example :<p>
-<p>
-<blockquote><pre>def force1(p1,p2):
- dx = p2.r.x - p1.r.x
- dy = p2.r.y - p1.r.y
- dz = p2.r.z - p1.r.z
- r2 = dx*dx + dy*dy + dz*dz
- f = 1.0/(r2*math.sqrt(r2))
- p1.f.x = p1.f.x + f*dx
- p2.f.x = p2.f.x - f*dx
- p1.f.y = p1.f.y + f*dy
- p2.f.y = p2.f.y - f*dy
- p1.f.z = p1.f.z + f*dz
- p2.f.z = p2.f.z - f*dz
-
-def force2(p1,p2):
- r1 = p1.r
- r2 = p2.r
- dx = r2.x - r1.x
- dy = r2.y - r1.y
- dz = r2.z - r1.z
- r2 = dx*dx + dy*dy + dz*dz
- f = 1.0/(r2*math.sqrt(r2))
- f1 = p1.f
- f2 = p2.f
- f1.x = f1.x + f*dx
- f2.x = f2.x - f*dx
- f1.y = f1.y + f*dy
- f2.y = f2.y - f*dy
- f1.z = f1.z + f*dz
- f2.z = f2.z - f*dz
-
-</pre></blockquote>
-The first calculation simply works with each Particle structure directly. Unfortunately, it performs alot of dereferencing of objects. If the calculation is restructured to use temporary variables as shown in force2, it will run significantly faster--in fact, on my machine, the second code fragment runs more than twice as fast as the first one.<p>
-<p>
-If performance is even more critical you can use the low-level C interface which eliminates all of the overhead of going through Python's class mechanism (at the expense of coding simplicity). When Python shadow classes are used, the low level C interface can still be used by importing the `modulec' module where `module' is the name of the module you used in the SWIG interface file.<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:07 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/SWIG.html b/swigweb/Doc1.1/HTML/SWIG.html
deleted file mode 100644
index 64eb6da..0000000
--- a/swigweb/Doc1.1/HTML/SWIG.html
+++ /dev/null
@@ -1,1586 +0,0 @@
-<!-- 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 <options> 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 <stdio.h>
-#include <ctype.h>
-#include <string.h>
-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 > strcmp Mike John
-1
-tclsh > toupper g
-G
-tclsh > 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 > 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 &unit_i;
-}
-Vector *unit_i_set(Vector *value) {
- unit_i = *value;
- return &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>&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 <time.h>
-%}
-
-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->x;
-}
-double Vector_y_get(Vector *obj) {
- return obj->y;
-}
-double Vector_z_get(Vector *obj) {
- return obj->z;
-}
-double Vector_x_set(Vector *obj, double value) {
- obj->x = value;
- return value;
-}
-double Vector_y_set(Vector *obj, double value) {
- obj->y = value;
- return value;
-}
-double Vector_z_set(Vector *obj, double value) {
- obj->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->name;
-}
-
-char *Foo_name_set(Foo *obj, char *c) {
- if (obj->name) free(obj->name);
- obj->name = (char *) malloc(strlen(c)+1);
- strcpy(obj->name,c);
- return obj->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->x = x;
- v->y = y;
- v->z = z;
- return v;
- }
- ~Vector() {
- free(self);
- }
- double magnitude() {
- return sqrt(self->x*self->x+self->y*self->y+self->z*self->z);
- }
- void print() {
- printf("Vector [%g, %g, %g]\n", self->x,self->y,self->z);
- }
-};
-
-</pre></blockquote>
-Now, when used with shadow classes in Python, you can do things like this :<p>
-<p>
-<blockquote><pre>>>> v = Vector(3,4,0) # Create a new vector
->>> print v.magnitude() # Print magnitude
-5.0
->>> v.print() # Print it out
-[ 3, 4, 0 ]
->>> 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->x = x;
- v->y = y;
- v->z = z;
- return v;
-}
-void delete_Vector(Vector *v) {
- free(v);
-}
-
-double Vector_magnitude(Vector *v) {
- return sqrt(v->x*v->x+v->y*v->y+v->z*v->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 *) &o->intRep;
-}
-int Object_intRep_ivalue_get(Object_intRep *o) {
- return o->ivalue;
-}
-int Object_intRep_ivalue_set(Object_intRep *o, int value) {
- return (o->ivalue = value);
-}
-double Object_intRep_dvalue_get(Object_intRep *o) {
- return o->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->{intRep}->{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->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->length;
-}
-int List_length_set(List *obj, int value) {
- obj->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 &a);
-}
-</pre></blockquote>
-<p>
-will be accessed using a function like this :<p>
-<p>
-<blockquote><pre>double Foo_bar(Foo *obj, double *a) {
- obj->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";
-<ctrl-d>
-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<class T> 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 < 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<double> &l);
-
-</pre></blockquote>
-The type "<tt>List<double</tt>>" becomes the datatype for the function parameter. In, Python it might appear like this :<p>
-<p>
-<blockquote><pre>>>> print cl
-_80a2df8_List<double>_p
->>>
-
-</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<double>
-List<double> *new_DoubleList() {
- return new List<double>;
-}
-%}
-</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<double> 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->x,v->y,v->z);
- return &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>>>>
->>> v = Vector();
->>> v.x = 3
->>> v.y = 4
->>> v.z = 0
->>> print(v)
-[ 3.0, 4.0, 0.0 ]
->>>
-
-</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 <proto1, proto2> {
-
-}
-// Methods
-- Bar : (id <proto1,proto2>) 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 <stdio.h>
-#include <math.h>
-
-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 <GL/gl.h>
-#include <GL/glu.h>
-%}
-
-// 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>
diff --git a/swigweb/Doc1.1/HTML/Scripting.html b/swigweb/Doc1.1/HTML/Scripting.html
deleted file mode 100644
index db78812..0000000
--- a/swigweb/Doc1.1/HTML/Scripting.html
+++ /dev/null
@@ -1,255 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Scripting Languages</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>2 Scripting Languages</h1><p><ul>
-<li> <a href="#n1">The two language view of the world</a>
-<li> <a href="#n2">How does a scripting language talk to C?</a>
-<li> <a href="#n3">Building scripting language extensions</a>
-<li> <a href="#n4">Shared libraries and dynamic loading</a>
-</ul>
-
-SWIG is all about using scripting languages with C/C++ to make flexible applications. This chapter provides a brief overview of several concepts and important aspects of this interface. Many of SWIG's potential users may not have considered using a scripting language before, so I hope that this chapter can provide a little motivation.<p>
-<a name="n1"></a><h2> The two language view of the world</h2>
-By developing SWIG, I am trying to build systems that are loosely structured as follows :<p>
-<p><center><img src="ch2.1.png"></center><p>
-<p>
-<p>
-A real application might look more like this :<p>
-<p><center><img src="ch2.2.png"></center><p>
-<p>
-In either case, we are interested in controlling a C/C++ program with a scripting language interface. Our interface may be for a small group of functions or a large collection of C libraries for performing a variety of tasks. In this model, C functions are turned into commands. To control the program, the user now types these commands or writes scripts to perform a particular operation. If you have used commercial packages such as MATLAB or IDL, it is a very similar model--you execute commands and write scripts, yet most of the underlying functionality is still written in C or Fortran for performance.<p>
-<p>
-The two-language model of computing is extremely powerful because it exploits the strengths of each language. C/C++ can be used for maximal performance and complicated systems programming tasks. Scripting languages can be used for rapid prototyping, interactive debugging, scripting, and access to high-level data structures such as lists, arrays, and hash tables.<p>
-<a name="n5"></a><h3> Will scripting languages make my C program inefficient?</h3>
-One of the criticisms of scripting languages is that they are interpreted and slow. No doubt about it, a scripting language will always run much slower than C. However, if you are using a scripting language to control a big C program, most of your functionality is still written in C and still fast. Thus, there is really no difference between writing the following in C <p>
-<p>
-<blockquote><pre>for (i = 0; i < 1000; i++) {
- call a bunch of C functions to do something
-}
-</pre></blockquote>
-<p>
-or writing the same thing in Python :<p>
-<p>
-<blockquote><pre>for i in range(0,1000):
- call a bunch of C functions to do something
-
-</pre></blockquote>
-Most of the time is still spent in the underlying C functions. Of course, you wouldn't want to write the inner loop of a matrix multiply in a scripting language, but you already knew this. It is also worth noting that reimplementing certain operations in C might not lead to better performance. For example, Perl is highly optimized for text-processing operations. Most of these operations are already implemented in C (underneath the hood) so in certain cases, using a scripting language may actually be faster than an equivalent implementation in C. <p>
-<a name="n6"></a><h3> Will adding a scripting language to my C program make it unmanagable?</h3>
-A fear among some users is that by adding a second language, you will end up with a package that is hard to maintain and use. I believe that there are two answers to this question. If you find yourself modifying the C code to fit it into a specific scripting language, then it will be difficult to maintain. By doing this, you will lock yourself into a particular language. If that language changes or disappears off the face of the earth, then you will be left with serious maintenance problems. On the flip side of the coin, a non-invasive tool like SWIG can build interfaces without requiring language-specific modifications to the underlying C code. If the scripting language changes, it is easy to update the resulting interface. If you decide that you want to scrap the whole interface scheme and try something else, you still have a clean set of C libraries<p>
-<p>
-My personal experience has been that adding a scripting language to a C program makes the C program more managable! You are encouraged to think about how your C program is structured and how you want things to work. In every program in which I have added a scripting interface, the C code has actually decreased in size, improved in reliability, become easier to maintain, while becoming more functional and flexible than before.<p>
-<a name="n2"></a><h2> How does a scripting language talk to C?</h2>
-Scripting languages are built around a small parser that reads and executes statements on the fly as your program runs. Within the parser, there is a mechanism for executing commands or accessing variables. However, in order to access C functions and variables, it is necessary to tell the parser additional information such as the name of the function, what kind of arguments does it take, and what to do when it is called. Unfortunately, this process can be extremely tedious and technical. SWIG automates the process and allows you to forget about it. In any case, it's probably a good idea to know what's going on under the hood.<p>
-<a name="n7"></a><h3> Wrapper functions</h3>
-Suppose you have an ordinary C function like this :<p>
-<p>
-<blockquote><pre>int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
-}
-</pre></blockquote>
-<p>
-In order to access this function from a scripting language, it is necessary to write a special "wrapper" function that serves as the glue between the scripting language and the underlying C function. A wrapper function must do three things :<p>
-<p>
-<ul>
-<li>Gather function arguments and make sure they are valid.
-<li>Call the C function.
-<li>Convert the return value into a form recognized by the scripting language.
-</ul>
-<p>
-As an example, the Tcl wrapper function for the <tt>fact()</tt> function above example might look like the following : <p>
-<blockquote><pre>
-int wrap_fact(ClientData clientData, Tcl_Interp *interp,
- int argc, char *argv[]) {
- int _result;
- int _arg0;
- if (argc != 2) {
- interp->result = "wrong # args";
- return TCL_ERROR;
- }
- _arg0 = atoi(argv[1]);
- _result = fact(_arg0);
- sprintf(interp->result,"%d", _result);
- return TCL_OK;
-}
-
-</pre></blockquote>
-Once we have created a wrapper function, the final step is to tell the scripting language about our new function. This is usually done in an initialization function called by the language when our module is loaded. For example, adding the above function to the Tcl interpreter would require code like the following :<p>
-<p>
-<blockquote><pre>int Wrap_Init(Tcl_Interp *interp) {
- Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
- (Tcl_CmdDeleteProc *) NULL);
- return TCL_OK;
-}
-</pre></blockquote>
-<p>
-When executed, Tcl will now have a new command called "<tt>fact</tt>" that you can use like any other Tcl command.<p>
-<p>
-While the process of adding a new function to Tcl has been illustrated, the procedure is almost identical for Perl and Python. Both require special wrappers to be written and both need additional initialization code. Only the specific details are different.<p>
-<a name="n8"></a><h3> Variable linking</h3>
-Variable linking is a slightly more difficult problem. The idea here is to map a C/C++ global variable into a variable in the scripting language (we are "linking" a variable in the scripting language to a C variable). For example, if you have the following variable:<p>
-<p>
-<blockquote><pre>double My_variable = 3.5;
-</pre></blockquote>
-<p>
-It would be nice to be able to access it from a script as follows (shown for Perl):<p>
-<p>
-<blockquote><pre>$a = $My_variable * 2.3;
-</pre></blockquote>
-<p>
-Unfortunately, the process of linking variables is somewhat problematic and not supported equally in all scripting languages. There are two primary methods for approaching this problem:<p>
-<p>
-<ul>
-<li>Direct access. Tcl provides a mechanism for directly accessing C <tt>int</tt>, <tt>double</tt>, and <tt>char</tt> * datatypes as Tcl variables. Whenever these variables are used in a Tcl script, the interpreter will directly access the corresponding C variable. In order for this to work, one must first "register" the C variables with the Tcl interpreter. While this approach is easy to support it is also somewhat problematic. Not all C datatypes are supported, and having Tcl directly manipulate your variables in its native representation could be potentially dangerous.
-<li>Access through function calls. Languages such as Perl and Python can access global variables using a function call mechanism. Rather than allowing direct access, the idea is to provide a pair of set/get functions that set or get the value of a particular variable. In many cases, this mechanism may be completely hidden. For example, it is possible to create a magical Perl variable that looks and feels just like a normal Perl variable, but is really mapped into a C variable via a pair of set/get functions. The advantage of this approach is that it is possible to support almost all C datatypes. The disadvantage is that it introduces alot of complexity to the wrapper code as it is now necessary to write a pair of C functions for every single global variable.
-</ul>
-<p>
-SWIG supports both styles of variable linking although the latter is more common. In some cases, a hybrid approach is taken (for example, the Tcl module will create a pair of set/get functions if it encounters a datatype that Tcl can't support). Fortunately, global variables are relatively rare when working with modular code.<p>
-<a name="n9"></a><h3> Constants</h3>
-Constants can easily be created by simply creating a new variable in the target language with the appropriate value. Unfortunately, this can have the undesirable side-effect of making the constant non-constant. As a result, a somewhat better (although perhaps inefficient) method of creating constants is to install them as read-only variables. SWIG tends to prefer this approach.<p>
-<a name="n10"></a><h3> Structures and classes</h3>
-Most scripting languages have trouble directly dealing with C structures and C++ classes. This is because the use of structures is inherently C dependent and it doesn't always map well into a scripting language environment. Many of these problems are simply due to data representation issues and differences in the way C and a scripting language might represent integers, floats, strings, and so on. Other times, the problem is deeper than that--for example, what does it mean (if anything) to try and use C++ inheritance from Perl?<p>
-<p>
-Dealing with objects is a tough problem that many people are looking at. Packages such as CORBA and ILU are primarily concerned with the representation of objects in a portable manner. This allows objects to be used in distributed systems, used with different languages and so on. SWIG is not concerned with the representation problem, but rather the problem of accessing and using C/C++ objects from a scripting language (in fact SWIG has even been used in conjunction with CORBA-based systems).<p>
-<p>
-To provide access, the simplist approach is to transform a structure into a collection of accessor functions. For example :<p>
-<p>
-<blockquote><pre>struct Vector {
- Vector();
- ~Vector();
- double x,y,z;
-};
-
-</pre></blockquote>
-can be transformed into the following set of functions :<p>
-<p>
-<blockquote><pre>Vector *new_Vector();
-void delete_Vector(Vector *v);
-double Vector_x_get(Vector *v);
-double Vector_y_get(Vector *v);
-double Vector_y_get(Vector *v);
-void Vector_x_set(Vector *v, double x);
-void Vector_y_set(Vector *v, double y);
-void Vector_z_set(Vector *v, double z);
-
-</pre></blockquote>
-When accessed in Tcl, the functions could be used as follows :<p>
-<p>
-<blockquote><pre>% set v [new_Vector]
-% Vector_x_set $v 3.5
-% Vector_y_get $v
-% delete_Vector $v
-% ...
-</pre></blockquote>
-<p>
-The accessor functions provide a mechanism for accessing a real C/C++ object. Since all access occurs though these function calls, Tcl does not need to know anything about the actual representation of a <tt>Vector</tt>. This simplifies matters considerably and steps around many of the problems associated with objects--in fact, it lets the C/C++ compiler do most of the work.<p>
-<a name="n11"></a><h3> Shadow classes</h3>
-As it turns out, it is possible to use the low-level accessor functions above to create something known as a "shadow" class. In a nutshell, a "shadow class" is a funny kind of object that gets created in a scripting language to access a C/C++ class (or struct) in a way that looks like the original structure (that is, it "shadows" the real C++ class). Of course, in reality, it's just a slick way of accessing objects that is more natural to most programmers. For example, if you have the following C definition :<p>
-<blockquote><pre>
-class Vector {
-public:
- Vector();
- ~Vector();
- double x,y,z;
-};
-</pre></blockquote>
-<p>
-A shadow classing mechanism would allow you to access the structure in a natural manner. For example, in Python, you might do the following,<p>
-<p>
-<blockquote><pre>>>> v = Vector()
->>> v.x = 3
->>> v.y = 4
->>> v.z = -13
->>> ...
->>> del v
-</pre></blockquote>
-<p>
-while in Perl5, it might look like this :<p>
-<blockquote><pre>
-$v = new Vector;
-$v->{x} = 3;
-$v->{y} = 4;
-$v->{z} = -13;
-
-</pre></blockquote>
-and in Tcl :<p>
-<blockquote><pre>
-Vector v
-v configure -x 3 -y 4 -z 13
-
-</pre></blockquote>
-When shadow classes are used, two objects are at really work--one in the scripting language, and an underlying C/C++ object. Operations affect both objects equally and for all practical purposes, it appears as if you are simply manipulating a C/C++ object. However, the introduction of additional "objects" can also produce excessive overhead if working with huge numbers of objects in this manner. Despite this, shadow classes turn out to be extremely useful. The actual implementation is covered later.<p>
-<a name="n3"></a><h2> Building scripting language extensions</h2>
-The final step in using a scripting language with your C/C++ application is adding your extensions to the scripting language itself. Unfortunately, this almost always seems to be the most difficult part. There are two fundamental approaches for doing this. First, you can build an entirely new version of the scripting language interpreter with your extensions built into it. Alternatively, you can build a shared library and dynamically load it into the scripting language as needed. Both approachs are described below :<p>
-<a name="n12"></a><h3> Static linking</h3>
-With static linking you rebuild the scripting language interpreter with extensions. The process usually involves compiling a short main program that adds your customized commands to the language and starts the interpreter. You then link your program with a library to produce a new executable. When using static linking, SWIG will provide a <tt>main()</tt> program for you so you usually just have to compile as follows (shown for Tcl) :<p>
-<p>
-<blockquote><pre>unix > swig -tcl -ltclsh.i example.i
-Generating wrappers for Tcl.
-unix > gcc example.c example_wrap.c -I/usr/local/include \
- -L/usr/local/lib -ltcl -lm -o my_tclsh
-
-</pre></blockquote>
-<tt>my_tclsh</tt> is a new executable containing the Tcl intepreter. <tt>my_tclsh</tt> will be exactly the same as tclsh except with your new commands added to it. When invoking SWIG, the <tt>-ltclsh.i</tt> option includes support code needed to rebuild the <tt>tclsh</tt> application. <p>
-<p>
-Virtually all machines support static linking and in some cases, it may be the only way to build an extension. The downside to static linking is that you can end up with a large executable. In a very large system, the size of the executable may be prohibitively large.<p>
-<a name="n4"></a><h2> Shared libraries and dynamic loading</h2>
-An alternative to static linking is to build a shared library. With this approach, you build a shared object file containing only the code related to your module (on Windows, this is the same as building a DLL). Unfortunately the process of building these modules varies on every single machine, but the procedure for a few common machines is show below :<p>
-<p>
-<blockquote><pre># Build a shared library for Solaris
-gcc -c example.c example_wrap.c -I/usr/local/include
-ld -G example.o example_wrap.o -o example.so
-
-# Build a shared library for Irix
-gcc -c example.c example_wrap.c -I/usr/local/include
-ld -shared example.o example_wrap.o -o example.so
-
-# Build a shared library for Linux
-gcc -fpic -c example.c example_wrap.c -I/usr/local/include
-gcc -shared example.o example_wrap.o -o example.so
-
-</pre></blockquote>
-To use your shared library, you simply use the corresponding command in the scripting language (load, import, use, etc...). This will import your module and allow you to start using it. <p>
-<p>
-When working with C++ codes, the process of building shared libraries is more difficult--primarily due to the fact that C++ modules may need additional code in order to operate correctly. On most machines, you can build a shared C++ module by following the above procedures, but changing the link line to the following :<p>
-<p>
-<blockquote><pre>c++ -shared example.o example_wrap.o -o example.so
-</pre></blockquote>
-<p>
-The advantages to dynamic loading is that you can use modules as they are needed and they can be loaded on the fly. The disadvantage is that dynamic loading is not supported on all machines (although support is improving). The compilation process also tends to be more complicated than what might be used for a typical C/C++ program.<p>
-<a name="n13"></a><h3> Linking with shared libraries</h3>
-When building extensions as shared libraries, it is not uncommon for your extension to rely upon other shared libraries on your machine. In order for the extension to work, it needs to be able to find all of these libraries at run-time. Otherwise, you may get an error such as the following :<p>
-<p>
-<blockquote><pre>>>> import graph
-Traceback (innermost last):
- File "<stdin>", line 1, in ?
- File "/home/sci/data1/beazley/graph/graph.py", line 2, in ?
- import graphc
-ImportError: 1101:/home/sci/data1/beazley/bin/python: rld: Fatal Error: cannot
-successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
-lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
->>>
-</pre></blockquote>
-<p>
-What this error means is that the extension module created by SWIG depends upon a shared library called "<tt>libgraph.so</tt>" that the system was unable to locate. To fix this problem, there are a few approaches you can take.<p>
-<p>
-<ul>
-<li>Set the UNIX environment variable <tt>LD_LIBRARY_PATH</tt> to the directory where shared libraries are located before running Python.
-<li>Link your extension and explicitly tell the linker where the required libraries are located. Often times, this can be done with a special linker flag such as <tt>-R</tt>, <tt>-rpath</tt>, etc... This is not implemented in a standard manner so read the man pages for your linker to find out more about how to set the search path for shared libraries.
-<li>Put shared libraries in the same directory as the executable. This technique is sometimes required for correct operation on non-Unix platforms.
-</ul>
-<p>
-With a little patience and after some playing around, you can usually get things to work. Afterwards, building extensions becomes alot easier.<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:50 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Tcl.html b/swigweb/Doc1.1/HTML/Tcl.html
deleted file mode 100644
index a9c3173..0000000
--- a/swigweb/Doc1.1/HTML/Tcl.html
+++ /dev/null
@@ -1,2048 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>SWIG and Tcl</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>10 SWIG and Tcl</h1><p><ul>
-<li> <a href="#n1">Preliminaries</a>
-<li> <a href="#n2">Building Tcl/Tk Extensions under Windows 95/NT</a>
-<li> <a href="#n3">Basic Tcl Interface</a>
-<li> <a href="#n4">The object oriented interface</a>
-<li> <a href="#n5">About the examples</a>
-<li> <a href="#n6">Binary trees in Tcl</a>
-<li> <a href="#n7">Building C/C++ data structures with Tk</a>
-<li> <a href="#n8">Accessing arrays</a>
-<li> <a href="#n9">Building a simple OpenGL module</a>
-<li> <a href="#n10">Exception handling</a>
-<li> <a href="#n11">Typemaps</a>
-<li> <a href="#n12">Configuration management with SWIG</a>
-<li> <a href="#n13">Building new kinds of Tcl interfaces (in Tcl)</a>
-<li> <a href="#n14">Extending the Tcl Netscape Plugin</a>
-<li> <a href="#n15">Tcl8.0 features</a>
-</ul>
-
-This chapter discusses SWIG's support of Tcl. SWIG supports Tcl versions 7.3 and newer, including Tcl 8.0. Tk 3.6 and newer can also be used. However, for the best results you should consider using Tcl 7.5/Tk4.1 or later.<p>
-<a name="n1"></a><h2> Preliminaries</h2>
-You will need to install Tcl/Tk on your system if you haven't done so already. If you are using Tcl 7.5 or newer, you should also determine if your system supports dynamic loading and shared libraries. SWIG will work with or without this, but the compilation process varies.<p>
-<a name="n16"></a><h3> Running SWIG</h3>
-To build a Tcl module, run swig using the <tt>-tcl</tt> option as follows :<p>
-<p>
-<blockquote><pre>swig -tcl example.i
-
-</pre></blockquote>
-This will produce 2 files. The first file, <tt>example_wrap.c, </tt>contains all of the C code needed to build your Tcl module. The second file contains supporting documentation and may be named <tt>example_wrap.doc</tt>, <tt>example_wrap.html</tt>, <tt>example_wrap.tex</tt>, etc... To build a Tcl extension you will need to compile the <tt>example_wrap.c</tt> file and link it with the rest of your program (and possibly Tcl itself).<p>
-<a name="n17"></a><h3> Additional SWIG options</h3>
-The following options are also available with the Tcl module :<p>
-<p>
-<blockquote><pre>-tcl8 Produce Tcl8.0 native wrappers (use in place of -tcl).
--module Set the module name.
--namespace Use [incr Tcl] namespaces.
--prefix pkg Set a package prefix of `pkg'. This prefix will be
- attached to each function.
--htcl tcl.h Set name of Tcl header file.
--htk tk.h Set name of Tk header file.
--plugin Generate additional code for the netscape plugin.
--noobject Omit object oriented extensions (compatibility with SWIG 1.0)
-</pre></blockquote>
-<p>
-Many of these options will be described later.<p>
-<a name="n18"></a><h3> Getting the right header files and libraries</h3>
-In order to compile Tcl/Tk extensions, you will need to locate the "<tt>tcl.h</tt>" and "<tt>tk.h</tt>" header files. These are usually located in <tt>/usr/local/include</tt>. You will also need to locate the Tcl/Tk libraries <tt>libtcl.a</tt> and <tt>libtk.a</tt>. These are usually located in <tt>/usr/local/lib</tt>.<p>
-When locating the right header and libraries files, double check to make sure the files are the correct version and form a matching pair. SWIG works with the following Tcl/Tk releases.<p>
-<p>
-<blockquote><pre>Tcl 7.3, Tk 3.6
-Tcl 7.4, Tk 4.0
-Tcl 7.5, Tk 4.1
-Tcl 7.6, Tk 4.2
-Tcl 8.0a2, Tk 8.0a2
-</pre></blockquote>
-<p>
-Do not mix versions. Although the code might compile if you do, it will usually core dump mysteriously. By default, SWIG looks for the header files "<tt>tcl.h</tt>" and "<tt>tk.h</tt>", but your installed version of Tcl/Tk may use slightly different names such as "<tt>tcl7.5.h</tt>" and "<tt>tk4.1.h</tt>". If you need to use different header files, you can use the <tt>-htcl</tt> and <tt>-htk</tt> options as in :<p>
-<p>
-<blockquote><pre>swig -tcl -htcl tcl7.5.h -htk tk4.1.h example.i
-
-</pre></blockquote>
-If you are installing Tcl/Tk yourself, it is often easier to set up a symbolic links between <tt>tcl.h</tt> and the header files for the latest installed version. You might also be able to make symbolic links to the correct files in your working directory.<p>
-<a name="n19"></a><h3> Compiling a dynamic module (Unix)</h3>
-To compile a dynamically loadable module, you will need to compile your SWIG extension into a shared library. This usually looks something like the following (shown for Linux).<p>
-<p>
-<blockquote><pre>unix > swig -tcl example.i
-unix > gcc -fpic example_wrap.c example.c -I/usr/local/include
-unix > gcc -shared example.o example_wrap.o -o example.so # Linux
-
-</pre></blockquote>
-Unfortunately, the process of building of building shared libraries varies on every single machine. SWIG will try to guess when you run configure, but it isn't always successful. It's always a good idea to read the man pages on the compiler/linker to find out more information.<p>
-<a name="n20"></a><h3> Using a dynamic module</h3>
-To use a dynamic module, you will need to load it using the Tcl load command as follows :<p>
-<p>
-<blockquote><pre>load ./example.so example
-
-</pre></blockquote>
-The first argument is the name of the shared library while the second argument is the name of the module (the same as what you specified with the <tt>%module</tt> directive). As alternative, you can turn your module into a Tcl package. See the section on configuration management at the end of this chapter for details.<p>
-<a name="n21"></a><h3> Static linking</h3>
-If your machine does not support dynamic loading or you've tried to use it without success, you can build new versions of <tt>tclsh</tt> (the Tcl shell) or <tt>wish</tt> (Tcl/Tk shell) with your extensions added. To do this, use SWIG's <tt>%include</tt> directive as follows :<p>
-<p>
-<blockquote><pre>%module mymodule
-... declarations ...
-
-%include tclsh.i // Support code for rebuilding tclsh
-</pre></blockquote>
-<p>
-To rebuild tclsh, you will need to compile as follows :<p>
-<p>
-<blockquote><pre>unix > swig -tcl example.i
-unix > gcc example_wrap.c example.c -I/usr/local/include -L/usr/local/lib -ltcl -ldl \
- -lm -o my_tclsh
-
-</pre></blockquote>
-Alternatively, you can use SWIG's <tt>-l</tt> option to add the tclsh.i library file without modifying the interface file. For example :<p>
-<p>
-<blockquote><pre>unix > swig -tcl -ltclsh.i example.i
-unix > gcc example_wrap.c example.c -I/usr/local/include -L/usr/local/lib -ltcl -ldl \
- -lm -o my_tclsh
-
-</pre></blockquote>
-The <tt>-ldl</tt> option will be required if your Tcl/Tk supports dynamic loading. On some machines (most notably Solaris),it will also be necessary to add <tt>-lsocket -lnsl</tt> to the compile line. This will produce a new version of <tt>tclsh</tt> that is identical to the old one, but with your extensions added.<p>
-<p>
-If you are using Tk, you will want to rebuild the <tt>wish</tt> executable instead. This can be done as follows :<p>
-<p>
-<blockquote><pre>%module mymodule
-... declarations ...
-
-%include wish.i // Support code for rebuilding wish
-
-</pre></blockquote>
-The compilation process is similar as before, but now looks like this :<p>
-<p>
-<blockquote><pre>unix > swig -tcl example.i
-unix > gcc example_wrap.c example.c -I/usr/local/include -L/usr/local/lib -ltk -ltcl \
- -lX11 -ldl -lm -o my_wish
-
-</pre></blockquote>
-In this case you will end up with a new version of the <tt>wish</tt> executable with your extensions added. Make sure you include <tt>-ltk</tt>, <tt>-ltcl</tt>, and <tt>-lX11</tt> in the order shown.<p>
-<a name="n22"></a><h3> Compilation problems</h3>
-Tcl is one of the easiest languages to compile extensions for. The Tcl header files should work without problems under C and C++. Perhaps the only tricky task is that of compiling dynamically loadable modules for C++. If your C++ code has static constructors, it is unlikely to work at all. In this case, you will need to build new versions of the <tt>tclsh</tt> or <tt>wish</tt> executables instead. You may also need to link against the <tt>libgcc.a</tt>, <tt>libg++.a</tt>, and l<tt>ibstdc++.a</tt> libraries (assuming g++).<p>
-<a name="n23"></a><h3> Setting a package prefix</h3>
-To avoid namespace problems, you can instruct SWIG to append a package prefix to all of your functions and variables. This is done using the -prefix option as follows :<p>
-<p>
-<blockquote><pre>swig -tcl -prefix Foo example.i
-
-</pre></blockquote>
-If you have a function "<tt>bar</tt>" in the SWIG file, the prefix option will append the prefix to the name when creating a command and call it "<tt>Foo_bar</tt>". <p>
-<a name="n24"></a><h3> Using [incr Tcl] namespaces</h3>
-Alternatively, you can have SWIG install your module into an [incr Tcl] namespace by specifying the <tt>-namespace</tt> option :<p>
-<p>
-<blockquote><pre>swig -tcl -namespace example.i
-
-</pre></blockquote>
-By default, the name of the namespace will be the same as the module name, but you can override it using the <tt>-prefix</tt> option.<p>
-<p>
-When the<tt> -namespace</tt> option is used, the resulting wrapper code can be compiled under both Tcl and [incr Tcl]. When compiling under Tcl, the namespace will turn into a package prefix such as in <tt>Foo_bar</tt>. When running under [incr Tcl], it will be something like <tt>Foo::bar.</tt><p>
-<a name="n2"></a><h2> Building Tcl/Tk Extensions under Windows 95/NT</h2>
-Building a SWIG extension to Tcl/Tk under Windows 95/NT is roughly similar to the process used with Unix. Normally, you will want to produce a DLL that can be loaded into tclsh or wish. This section covers the process of using SWIG with Microsoft Visual C++ 4.x although the procedure may be similar with other compilers.<p>
-<a name="n25"></a><h3> Running SWIG from Developer Studio</h3>
-If you are developing your application within Microsoft developer studio, SWIG can be invoked as a custom build option. The process roughly follows these steps :<p>
-<p>
-<ul>
-<li>Open up a new workspace and use the AppWizard to select a DLL project.
-<li>Add both the SWIG interface file (the .i file), any supporting C files, and the name of the wrapper file that will be created by SWIG (ie. <tt>example_wrap.c</tt>). Note : If using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't exist yet--Developer studio will keep a reference to it around.
-<li>Select the SWIG interface file and go to the settings menu. Under settings, select the "Custom Build" option.
-<li>Enter "SWIG" in the description field.
-<li>Enter "<tt>swig -tcl -o $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build command(s) field"
-<li>Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" in the "Output files(s) field".
-<li>Next, select the settings for the entire project and go to "C++:Preprocessor". Add the include directories for your Tcl installation under "Additional include directories".
-<li>Finally, select the settings for the entire project and go to "Link Options". Add the Tcl library file to your link libraries. For example "<tt>tcl80.lib</tt>". Also, set the name of the output file to match the name of your Tcl module (ie. example.dll).
-<li>Build your project.
-</ul>
-<p>
-Now, assuming all went well, SWIG will be automatically invoked when you build your project. Any changes made to the interface file will result in SWIG being automatically invoked to produce a new version of the wrapper file. To run your new Tcl extension, simply run <tt>tclsh</tt> or <tt>wish</tt> and use the <tt>load</tt> command. For example :<p>
-<p>
-<blockquote><pre>
-
-MSDOS > tclsh80
-% load example.dll
-% fact 4
-24
-%
-</pre></blockquote>
-<a name="n26"></a><h3> Using NMAKE</h3>
-Alternatively, SWIG extensions can be built by writing a Makefile for NMAKE. To do this, make sure the environment variables for MSVC++ are available and the MSVC++ tools are in your path. Now, just write a short Makefile like this :<p>
-<p>
-<blockquote><pre># Makefile for building various SWIG generated extensions
-
-SRCS = example.c
-IFILE = example
-INTERFACE = $(IFILE).i
-WRAPFILE = $(IFILE)_wrap.c
-
-# Location of the Visual C++ tools (32 bit assumed)
-
-TOOLS = c:\msdev
-TARGET = example.dll
-CC = $(TOOLS)\bin\cl.exe
-LINK = $(TOOLS)\bin\link.exe
-INCLUDE32 = -I$(TOOLS)\include
-MACHINE = IX86
-
-# C Library needed to build a DLL
-
-DLLIBC = msvcrt.lib oldnames.lib
-
-# Windows libraries that are apparently needed
-WINLIB = kernel32.lib advapi32.lib user32.lib gdi32.lib comdlg32.lib
-winspool.lib
-
-# Libraries common to all DLLs
-LIBS = $(DLLIBC) $(WINLIB)
-
-# Linker options
-LOPT = -debug:full -debugtype:cv /NODEFAULTLIB /RELEASE /NOLOGO /
-MACHINE:$(MACHINE) -entry:_DllMainCRTStartup@12 -dll
-
-# C compiler flags
-
-CFLAGS = /Z7 /Od /c /nologo
-TCL_INCLUDES = -Id:\tcl8.0a2\generic -Id:\tcl8.0a2\win
-TCLLIB = d:\tcl8.0a2\win\tcl80.lib
-
-tcl::
- ..\..\swig -tcl -o $(WRAPFILE) $(INTERFACE)
- $(CC) $(CFLAGS) $(TCL_INCLUDES) $(SRCS) $(WRAPFILE)
- set LIB=$(TOOLS)\lib
- $(LINK) $(LOPT) -out:example.dll $(LIBS) $(TCLLIB) example.obj example_wrap.obj
-
-</pre></blockquote>
-To build the extension, run NMAKE (you may need to run vcvars32 first). This is a pretty minimal Makefile, but hopefully its enough to get you started. With a little practice, you'll be making lots of Tcl extensions.<p>
-<a name="n3"></a><h2> Basic Tcl Interface</h2>
-<a name="n27"></a><h3> Functions</h3>
-C functions are turned into new Tcl commands with the same usage as the C function. Default/optional arguments are also allowed. An interface file like this :<p>
-<p>
-<blockquote><pre>%module example
-int foo(int a);
-double bar (double, double b = 3.0);
-...
-
-</pre></blockquote>
-Will be used in Tcl like this :<p>
-<p>
-<blockquote><pre>set a [foo 2]
-set b [bar 3.5 -1.5]
-set b [bar 3.5] # Note : default argument is used
-
-</pre></blockquote>
-There isn't much more to say...this is pretty straightforward.<p>
-<a name="n28"></a><h3> Global variables</h3>
-For global variables, things are a little more complicated. For the following C datatypes, SWIG will use Tcl's variable linking mechanism to provide direct access :<p>
-<p>
-<blockquote><pre>int, unsigned int,
-double,
-char *,
-
-</pre></blockquote>
-When used in an interface file and script, it will operate as follows :<p>
-<p>
-<blockquote><pre>// example.i
-%module example
-...
-double My_variable;
-...
-
-# Tcl script
-puts $My_variable # Output value of C global variable
-set My_variable 5.5 # Change the value
-
-</pre></blockquote>
-For all other C datatypes, SWIG will generate a pair of set/get functions. For example :<p>
-<p>
-<blockquote><pre>// example.i
-short My_short;
-</pre></blockquote>
-<p>
-will be accessed in Tcl as follows :<p>
-<p>
-<blockquote><pre>puts [My_short_get] # Get value of global variable
-My_short_set 5.5 # Set value of global variable
-
-</pre></blockquote>
-While not the most elegant solution, this is the only solution for now. Tcl's normal variable linking mechanism operates directly on a variables and would not work correctly on datatypes other than the 3 basic datatypes supported by Tcl (<tt>int</tt>, <tt>double</tt>, and <tt>char *</tt>).<p>
-<a name="n29"></a><h3> Constants</h3>
-Constants are created as read-only variables. For odd datatypes (not supported by the variable linking mechanism), SWIG generates a string representation of the constant and use it instead (you shouldn't notice this however since everything is already a string in Tcl). It is never necessary to use a special "get" function with constants. Unlike Tcl variables, constants can contain pointers, structure addresses, function pointers, etc...<p>
-<a name="n30"></a><h3> Pointers</h3>
-Pointers to C/C++ objects are represented as character strings such as the following :<p>
-<p>
-<blockquote><pre>_100f8e2_Vector_p
-
-</pre></blockquote>
-A NULL pointer is represented by the string "NULL". NULL pointers can also be explicitly created as follows :<p>
-<p>
-<blockquote><pre>_0_Vector_p
-
-</pre></blockquote>
-In Tcl 8.0, pointers are represented using a new type of Tcl object, but the string representation is the same (and is interchangable). As a general, direct manipulation of pointer values is discouraged. <p>
-<a name="n31"></a><h3> Structures </h3>
-SWIG generates a basic low-level interface to C structures. For example :<p>
-<p>
-<blockquote><pre>struct Vector {
- double x,y,z;
-};
-
-</pre></blockquote>
-gets mapped into the following collection of C functions :<p>
-<p>
-<blockquote><pre>double Vector_x_get(Vector *obj)
-double Vector_x_set(Vector *obj, double x)
-double Vector_y_get(Vector *obj)
-double Vector_y_set(Vector *obj, double y)
-double Vector_z_get(Vector *obj)
-double Vector_z_set(Vector *obj, double z)
-
-</pre></blockquote>
-These functions are then used in the resulting Tcl interface. For example :<p>
-<p>
-<blockquote><pre># v is a Vector that got created somehow
-% Vector_x_get $v
-3.5
-% Vector_x_set $v 7.8 # Change x component
-</pre></blockquote>
-<p>
-Similar access is provided for unions and the data members of C++ classes.<p>
-<a name="n32"></a><h3> C++ Classes</h3>
-C++ classes are handled by building a set of low level accessor functions. Consider the following class :<p>
-<p>
-<blockquote><pre>
-class List {
-public:
- List();
- ~List();
- int search(char *item);
- void insert(char *item);
- void remove(char *item);
- char *get(int n);
- int length;
-static void print(List *l);
-};
-</pre></blockquote>
-<p>
-When wrapped by SWIG, the following functions are created :<p>
-<p>
-<blockquote><pre>List *new_List();
-void delete_List(List *l);
-int List_search(List *l, char *item);
-void List_insert(List *l, char *item);
-void List_remove(List *l, char *item);
-char *List_get(List *l, int n);
-int List_length_get(List *l);
-int List_length_set(List *l, int n);
-void List_print(List *l);
-
-</pre></blockquote>
-Within Tcl, we can use the functions as follows :<p>
-<blockquote><pre>
-% set l [new_List]
-% List_insert $l Ale
-% List_insert $l Stout
-% List_insert $l Lager
-% List_print $l
-Lager
-Stout
-Ale
-% puts [List_length_get $l]
-3
-% puts $l
-_1008560_List_p
-%
-
-</pre></blockquote>
-C++ objects are really just pointers (which are represented as strings). Member functions and data are accessed by simply passing a pointer into a collection of accessor functions that take the pointer as the first argument.<p>
-<p>
-While somewhat primitive, the low-level SWIG interface provides direct and flexible access to almost any C++ object. As it turns out, it is possible to do some rather amazing things with this interface as will be shown in some of the later examples. SWIG 1.1 also generates an object oriented interface that can be used in addition to the basic interface just described here.<p>
-<a name="n4"></a><h2> The object oriented interface</h2>
-With SWIG 1.1, a new object oriented interface to C structures and C++ classes is supported. This interface supplements the low-level SWIG interface already defined--in fact, both can be used simultaneously. To illustrate this interface, consider our previous <tt>List</tt> class :<p>
-<p>
-<blockquote><pre>class List {
-public:
- List();
- ~List();
- int search(char *item);
- void insert(char *item);
- void remove(char *item);
- char *get(int n);
- int length;
-static void print(List *l);
-};
-
-</pre></blockquote>
-Using the object oriented interface requires no additional modifications or recompilation of the SWIG module (the functions are just used differently).<p>
-<a name="n33"></a><h3> Creating new objects</h3>
-The name of the class becomes a new command for creating an object. There are 5 methods for creating an object (<tt>MyObject </tt>is the name of the corresponding C++ class) <p>
-<p>
-<blockquote><pre>MyObject o # Creates a new object `o'
-
-MyObject o -this $objptr # Turn a pointer to an existing C++ object into a
- # Tcl object `o'
-
-MyObject -this $objptr # Turn the pointer $objptr into a Tcl "object"
-
-MyObject -args args # Create a new object and pick a name for it. A handle
- # will be returned and is the same as the pointer value.
-
-MyObject # The same as MyObject -args, but for constructors that
- # take no arguments.
-</pre></blockquote>
-<p>
-Thus, for our List class, we can create new List objects as follows :<p>
-<p>
-<blockquote><pre>List l # Create a new list l
-
-set listptr [new_List] # Create a new List using low level interface
-List l2 -this $listptr # Turn it into a List object named `l2'
-
-set l3 [List] # Create a new list. The name of the list is in $l3
-
-List -this $listptr # Turn $listptr into a Tcl object of the same name
-</pre></blockquote>
-<p>
-Now assuming you're not completely confused at this point, the best way to think of this is that there are really two different ways of representing an object. One approach is to simply use the pointer value as the name of an object. For example :<p>
-<p>
-<blockquote><pre>_100e8f8_List_p
-
-</pre></blockquote>
-The second approach is to allow you to pick a name for an object such as "foo". The different types of constructors are really just mechanism for using either approach.<p>
-<a name="n34"></a><h3> Invoking member functions</h3>
-Member functions are invoked using the name of the object followed by the method name and any arguments. For example :<p>
-<p>
-<blockquote><pre>% List l
-% l insert "Bob"
-% l insert "Mary"
-% l search "Dave"
-0
-% ...
-
-</pre></blockquote>
-Or if you let SWIG generate the name of the object... (this is the pointer model)<p>
-<p>
-<blockquote><pre>% set l [List]
-% $l insert "Bob" # Note $l contains the name of the object
-% $l insert "Mary"
-% $l search "Dave"
-0
-%
-</pre></blockquote>
-<a name="n35"></a><h3> Deleting objects</h3>
-Since objects are created by adding new Tcl commands, they can be deleted by simply renaming them. For example :<p>
-<p>
-<blockquote><pre>% rename l "" # Destroy list object `l'
-
-</pre></blockquote>
-SWIG will automatically call the corresponding C/C++ destructor, with one caveat--SWIG will not destroy an object if you created it from an already existing pointer (if you called the constructor using the -this option). Since the pointer already existed when you created the Tcl object, Tcl doesn't own the object so it would probably be a bad idea to destroy it.<p>
-<a name="n36"></a><h3> Accessing member data</h3>
-Member data of an object can be accessed using the <tt>cget</tt> method. The approach is quite similar to that used in [incr Tcl] and other Tcl extensions. For example :<p>
-<p>
-<blockquote><pre>% l cget -length # Get the length of the list
-13
-
-</pre></blockquote>
-The <tt>cget</tt> method currently only allows retrieval of one member at a time. Extracting multiple members will require repeated calls.<p>
-<p>
-The member <tt>-this</tt> contains the pointer to the object that is compatible with other SWIG functions. Thus, the following call would be legal<p>
-<p>
-<blockquote><pre>
-% List l # Create a new list object
-% l insert Mike
-% List_print [l cget -this] # Print it out using low-level function
-</pre></blockquote>
-<a name="n37"></a><h3> Changing member data</h3>
-To change the value of member data, the <tt>configure</tt> method can be used. For example :<p>
-<p>
-<blockquote><pre>% l configure -length 10 # Change length to 10 (probably not a good idea, but
- # possible).
-
-</pre></blockquote>
-In a structure such as the following :<p>
-<blockquote><pre>
-struct Vector {
- double x, y, z;
-};
-
-</pre></blockquote>
-you can change the value of all or some of the members as follows :<p>
-<p>
-<blockquote><pre>% v configure -x 3.5 -y 2 -z -1.0
-</pre></blockquote>
-<p>
-The order of attributes does not matter. <p>
-<a name="n38"></a><h3> Relationship with pointers</h3>
-The object oriented interface is mostly compatible with all of the functions that accept pointer values as arguments. Here are a couple of things to keep in mind :<p>
-<p>
-<ul>
-<li>If you explicitly gave a name to an object, the pointer value can be retrieved using the `<tt>cget -this</tt>' method. The pointer value is what you should give to other SWIG generated functions if necessary.
-<li>If you let SWIG generate the name of an object for you, then the name of the object is the same as the pointer value. This is the preferred approach.
-<li>If you have a pointer value but it's not a Tcl object, you can turn it into one by calling the constructor with the `<tt>-this</tt>' option.
-</ul>
-<p>
-Here is a script that illustrates how these things work :<p>
-<p>
-<blockquote><pre># Example 1 : Using a named object
-
-List l # Create a new list
-l insert Dave # Call some methods
-l insert Jane
-l insert Pat
-List_print [l cget -this] # Call a static method (which requires the pointer value)
-
-# Example 2: Let SWIG pick a name
-
-set l [List] # Create a new list
-$l insert Dave # Call some methods
-$l insert Jane
-$l insert Pat
-List_print $l # Call static method (name of object is same as pointer)
-
-# Example 3: Already existing object
-set l [new_List] # Create a raw object using low-level interface
-List_insert $l Dave # Call some methods (using low-level functions)
-List -this $l # Turn it into a Tcl object instead
-$l insert Jane
-$l insert Part
-List_print $l # Call static method (uses pointer value as before).
-</pre></blockquote>
-<p>
-<a name="n39"></a><h3> Performance concerns and disabling the object oriented interface</h3>
-The object oriented interface is mainly provided for ease of programming at the expense of introducing more overhead and increased code size (C code that is). If you are concerned about these issues use the basic SWIG interface instead. It provides direct access and is much faster. As it turns out, it is possible to build an object oriented interface directly in Tcl as well--an example we'll return to a little later.<p>
-<p>
-To disable the object oriented interface, run SWIG with the <tt>-noobject</tt> option. This will strip out all of the extra code and produce only the low-level interface.<p>
-<a name="n5"></a><h2> About the examples</h2>
-The next few sections cover Tcl examples of varying complexity. These are primarily designed to illustrate how SWIG can be used to integrate C/C++ and Tcl in a variety of ways. Some of the things that will be covered are :<p>
-<p>
-<ul>
-<li>Controlling C programs with Tcl
-<li>Building C data structures in Tcl.
-<li>Use of C objects with Tk
-<li>Wrapping a C library (OpenGL in this case)
-<li>Accessing arrays and other common data structures
-<li>Using Tcl to build new Tcl interfaces to C programs.
-<li>Modifying SWIG's handling of datatypes.
-<li>And a bunch of other cool stuff.
-</ul>
-<a name="n6"></a><h2> Binary trees in Tcl</h2>
-In this example, we show Tcl can be used to manipulate binary trees implemented in C. This will involve accessing C data structures and functions.<p>
-<a name="n40"></a><h3> C files</h3>
-We will build trees using the following C header file :<p>
-<p>
-<blockquote><pre>/* tree.h */
-typedef struct Node Node;
-struct Node {
- char *key;
- char *value;
- Node *left;
- Node *right;
-};
-
-typedef struct Tree {
- Node *head; /* Starting node */
- Node *z; /* Ending node (at leaves) */
-} Tree;
-
-extern Node *new_Node(char *key, char *value);
-extern Tree *new_Tree();
-</pre></blockquote>
-<p>
-The C functions to create new nodes and trees are as follows :<p>
-<p>
-<blockquote><pre>/* File : tree.c */
-#include <string.h>
-#include "tree.h"
-Node *new_Node(char *key, char *value) {
- Node *n;
- n = (Node *) malloc(sizeof(Node));
- n->key = (char *) malloc(strlen(key)+1);
- n->value = (char *) malloc(strlen(value)+1);
- strcpy(n->key,key);
- strcpy(n->value,value);
- n->left = 0;
- n->right = 0;
- return n;
-};
-Tree *new_Tree() {
- Tree *t;
- t = (Tree *) malloc(sizeof(Tree));
- t->head = new_Node("","__head__");
- t->z = new_Node("__end__","__end__");
- t->head->right = t->z;
- t->z->left = t->z;
- t->z->right = t->z;
- return t;
-}
-</pre></blockquote>
-<a name="n41"></a><h3> Making a quick a dirty Tcl module</h3>
-To make a quick Tcl module with these functions, we can do the following :<p>
-<p>
-<blockquote><pre>// file : tree.i
-%module tree
-%{
-#include "tree.h"
-%}
-%include tree.h // Just grab header file since it's fairly simple
-
-</pre></blockquote>
-To build the module, run SWIG as follows and compile the resulting output :<p>
-<p>
-<blockquote><pre>% swig -tcl -ltclsh.i tree.i
-% gcc tree.c tree_wrap.c -I/usr/local/include -L/usr/local/lib -ltcl -lm -o my_tclsh
-</pre></blockquote>
-<p>
-We can now try out the module interactively by just running the new `<tt>my_tclsh</tt>' executable.<p>
-<p>
-<blockquote><pre>unix > my_tclsh
-% set t [new_Tree] # Create a new tree
-_8053198_Tree_p
-% set n [Tree_head_get $t] # Get first node
-_80531a8_Node_p
-% puts [Node_value_get $n] # Get its value
-__head__
-% Node -this $n
-% $n cget -value # Altenative method for getting value
-__head__
-</pre></blockquote>
-<a name="n42"></a><h3> Building a C data structure in Tcl</h3>
-Given our simple Tcl interface, it is easy to write Tcl functions for building up a C binary tree. For example :<p>
-<p>
-<blockquote><pre># Insert an item into a tree
-proc insert_tree {tree key value} {
- set tree_head [Tree_head_get $tree]
- set tree_z [Tree_z_get $tree]
- set p $tree_head
- set x [Node_right_get $tree_head]
- while {[Node_key_get $x] != "__end__"} {
- set p $x
- if {$key < [Node_key_get $x]} {
- set x [Node_left_get $x]
- } {
- set x [Node_right_get $x]
- }
- }
- set x [new_Node $key $value]
- if {$key < [Node_key_get $p]} {
- Node_left_set $p $x
- } {
- Node_right_set $p $x
- }
- Node_left_set $x $tree_z
- Node_right_set $x $tree_z
-}
-
-# Search tree and return all matches
-proc search_tree {tree key} {
- set tree_head [Tree_head_get $tree]
- set tree_z [Tree_z_get $tree]
- set found {}
- set x [Node_right_get $tree_head]
- while {[Node_key_get $x] != "__end__"} {
- if {[Node_key_get $x] == $key} {
- lappend found [Node_value_get $x]
- }
- if {$key < [Node_key_get $x]} {
- set x [Node_left_get $x]
- } {
- set x [Node_right_get $x]
- }
- }
- return $found
-}
-
-</pre></blockquote>
-While written in Tcl, these functions are building up a real C binary tree data structure that could be passed into other C function. For example, we could write a function that globs an entire directory and builds a tree structure as follows :<p>
-<p>
-<blockquote><pre># Insert all of the files in pathname into a binary tree
-
-proc build_dir_tree {tree pathname} {
- set error [catch {set filelist [glob -nocomplain $pathname/*]}]
- if {$error == 0} {
- foreach f $filelist {
- if {[file isdirectory $f] == 1} {
- insert_tree $tree [file tail $f] $f
- if {[file type $f] != "link"} {build_dir_tree $tree $f}
- } {
- insert_tree $tree [file tail $f] $f
- }
- }
- }
-}
-
-</pre></blockquote>
-We can test out our function interactively as follows :<p>
-<p>
-<blockquote><pre>% source tree.tcl
-% set t [new_Tree] # Create a new tree
-_80533c8_Tree_p
-% build_dir_tree $t /home/beazley/SWIG/SWIG1.1
-% search_tree $t tcl
-/home/beazley/SWIG/SWIG1.1/Examples/tcl /home/beazley/SWIG/SWIG1.1/swig_lib/tcl
-%
-</pre></blockquote>
-<a name="n43"></a><h3> Implementing methods in C</h3>
-While our Tcl methods may be fine for small problems, it may be faster to reimplement the insert and search methods in C :<p>
-<p>
-<blockquote><pre>void insert_tree(Tree *t, char *key, char *value) {
- Node *p;
- Node *x;
-
- p = t->head;
- x = t->head->right;
- while (x != t->z) {
- p = x;
- if (strcmp(key,x->key) < 0)
- x = x->left;
- else
- x = x->right;
- }
- x = new_Node(key,value);
- if (strcmp(key,p->key) < 0)
- p->left = x;
- else
- p->right = x;
- x->left = t->z;
- x->right = t->z;
-}
-
-</pre></blockquote>
-To use this function in Tcl, simply put a declaration into the file <tt>tree.h</tt> or <tt>tree.i</tt>.<p>
-<p>
-When reimplemented in C, the underlying Tcl script may not notice the difference. For example, our directory subroutine would not care if <tt>insert_tree</tt> had been written in Tcl or C. Of course, by writing this function C, we will get significantly better performance. <p>
-<a name="n44"></a><h3> Building an object oriented C interface</h3>
-So far our tree example has been using the basic SWIG interface. With a little work in the interface file, we can improve the interface a little bit.<p>
-<p>
-<blockquote><pre>%module tree
-%{
-#include "tree.h"
-%}
-
-%include tree.h
-%{
-
- /* Function to count up Nodes */
- static int count_nodes(Node *n, Node *end) {
- if (n == end) return 0;
- return 1+count_nodes(n->left,end)+count_nodes(n->right,end);
- }
-
-%}
-
-// Attach some new methods to the Tree structure
-
-%addmethods Tree {
- void insert(char *key, char *value) {
- insert_tree(self,key,value);
- }
- char *search(char *key) {
- return search_tree(self,key);
- }
- char *findnext(char *key) {
- return find_next(self,key);
- }
- int count() {
- return count_nodes(self->head->right,self->z);
- }
- Tree(); // This is just another name for new_Tree
-}
-
-</pre></blockquote>
-The <tt>%addmethods</tt> directive can be used to attach methods to existing structures and classes. In this case, we are attaching some methods to the <tt>Tree</tt> structure. Each of the methods are simply various C functions we have written for accessing trees. This type of interface file comes in particularly handy when using the Tcl object oriented interface. For example, we can rewrite our directory globber as follows :<p>
-<p>
-<blockquote><pre>proc build_dir_tree {tree pathname} {
- set error [catch {set filelist [glob -nocomplain $pathname/*]}]
- if {$error == 0} {
- foreach f $filelist {
- if {[file isdirectory $f] == 1} {
- $tree insert [file tail $f] $f # Note new calling method
- if {[file type $f] != "link"} {build_dir_tree $tree $f}
- } {
- $tree insert [file tail $f] $f
- }
- }
- }
-}
-
-</pre></blockquote>
-Now using it :<p>
-<blockquote><pre>% source tree.tcl
-% Tree t # Create a new Tree object
-_8054610_Tree_p
-% build_dir_tree t /home/beazley/SWIG/SWIG1.1
-% t count
-1770
-% t search glaux.i
-/home/beazley/SWIG/SWIG1.1/Examples/OpenGL/glaux.i
-% t search typemaps
-/home/beazley/SWIG/SWIG1.1/Examples/perl5/typemaps
-% t findnext typemaps
-/home/beazley/SWIG/SWIG1.1/Examples/python/typemaps
-% t findnext typemaps
-/home/beazley/SWIG/SWIG1.1/Examples/tcl/typemaps
-% t findnext typemaps
-None
-%
-</pre></blockquote>
-<p>
-With a little extra work, we've managed to turn an ordinary C structure into a class-like object in Tcl. <p>
-<a name="n7"></a><h2> Building C/C++ data structures with Tk</h2>
-Given the direct access to C/C++ objects provided by SWIG, it can be possible to use Tk to interactively build a variety of interesting data structures. To do this, it is usually useful to maintain a mapping between canvas items and an underlying C data structure. This is done using associative arrays to map C pointers to canvas items and canvas items back to pointers.<p>
-<p>
-Suppose that we have a C program for manipulating directed graphs and that we wanted to provide a Tk interface for building graphs using a ball-and-stick model such as the following :<p>
-<p><center><img src="ch10.1.png"></center><p>
-<p>
-<p>
-The SWIG interface file for this might look something like this :<p>
-<p>
-<blockquote><pre>%module graph
-%{
-#include "graph.h"
-%}
-
-/* Get a node's number */
-int GetNum(Node *n); /* Get a node's number */
-AdjList *GetAdj(Node *n); /* Get a node's adjacency list */
-AdjList *GetNext(AdjList *l); /* Get next node in adj. list */
-Node *GetNode(AdjList *l); /* Get node from adj. list */
-Node *new_node(); /* Make a new node */
-void AddLink(Node *v1, Node *v2); /* Add an edge */
-... etc ...
-
-</pre></blockquote>
-The interface file manipulates <tt>Node</tt> and <tt>AdjList</tt> structures. The precise implementation of these doesn't matter here--in fact SWIG doesn't even need it. Within a Tcl/Tk script however, we can keep track of these objects as follows :<p>
-<p>
-<blockquote><pre># Make a new node and put it on the canvas
-proc mkNode {x y} {
- global nodeX nodeY nodeP nodeMap nodeList edgeFirst edgeSecond
- set new [.c create oval [expr $x-15] [expr $y-15] \
- [expr $x+15] [expr $y+15] -outline black \
- -fill white -tags node]
- set newnode [new_node] ;# Make a new C Node
- set nnum [GetNum $newnode] ;# Get our node's number
- set id [.c create text [expr $x-4] [expr $y+10] \
- -text $nnum -anchor sw -tags nodeid]
- set nodeX($new) $x ;# Save coords of canvas item
- set nodeY($new) $y
- set nodeP($new) $newnode ;# Save C pointer
- set nodeMap($newnode) $new ;# Map pointer to Tk widget
- set edgeFirst($new) {}
- set edgeSecond($new) {}
- lappend nodeList $new ;# Keep a list of all C
- ;# Pointers we've made
-}
-
-# Make a new edge between two nodes and put an arrow on the canvas
-proc mkEdge {first second new} {
- global nodeP edgeFirst edgeSecond
- set edge [mkArrow $first $second] ;# Make an arrow
- lappend edgeFirst($first) $edge ;# Save information
- lappend edgeSecond($second) $edge
- if {$new == 1} {
-# Now add an edge within our C data structure
- AddLink $nodeP($first) $nodeP($second) ;# Add link to C structure
- }
-}
-</pre></blockquote>
-<p>
-In these functions, the array <tt>nodeP()</tt> allows us to associate a particular canvas item with a C object. When manipulating the graph, this makes it easy to move from the Tcl world to C. A second array, <tt>nodeMap()</tt> allows us to go the other way--mapping C pointers to canvas items. A list <tt>nodeList</tt> keeps track of all of the nodes we've created just in case we want to examine all of the nodes. For example, suppose a C function added more edges to the graph. To reflect the new state of the graph, we would want to add more edges to the Tk canvas. This might be accomplished as follows :<p>
-<p>
-<blockquote><pre># Look at the C data structure and update the canvas
-proc mkEdges {} {
- global nodeX nodeY nodeP nodeMap nodeList edgeFirst edgeSecond
- unset edgeFirst
- unset edgeSecond
- .c delete arc # Edges have been tagged with arc (not shown)
-
- foreach node $nodeList { ;# clear old lists
- set edgeFirst($node) {}
- set edgeSecond($node) {}
- }
- foreach node $nodeList { ;# Go through all of the nodes
- set v $nodeP($node) ;# Get the node pointer
- set v1 [GetAdj $v] ;# Get its adjacency list
- while {$v1 != "NULL"} {
- set v2 [GetNode $v1] ;# Get node pointer
- set w $nodeMap($v2) ;# Get canvas item
- mkEdge $node $w 0 ;# Make an edge between them
- set v1 [GetNext $v1] ;# Get next node
- }
- }
-}
-
-</pre></blockquote>
-<p>
-This function merely scans through all of the nodes and walks down the adjacency list of each one. The <tt>nodeMap()</tt> array maps C pointers onto the corresponding canvas items. We use this to construct edges on the canvas using the <tt>mkEdge</tt> function.<p>
-<a name="n8"></a><h2> Accessing arrays</h2>
-In some cases, C functions may involve arrays and other objects. In these instances, you may have to write helper functions to provide access. For example, suppose you have a C function like this :<p>
-<p>
-<blockquote><pre>// Add vector a+b -> c
-void vector_add(double *a, double *b, double *c, int size);
-
-</pre></blockquote>
-SWIG is quite literal in its interpretation of <tt>double *</tt>--it is a pointer to a <tt>double</tt>. To provide access, a few helper functions can be written such as the following :<p>
-<p>
-<blockquote><pre>// SWIG helper functions for double arrays
-%inline %{
-double *new_double(int size) {
- return (double *) malloc(size*sizeof(double));
-}
-void delete_double(double *a) {
- free a;
-}
-double get_double(double *a, int index) {
- return a[index];
-}
-void set_double(double *a, int index, double val) {
- a[index] = val;
-}
-%}
-</pre></blockquote>
-<p>
-Using our C functions might work like this :<p>
-<p>
-<blockquote><pre># Tcl code to create some arrays and add them
-
-set a [new_double 200]
-set b [new_double 200]
-set c [new_double 200]
-
-# Fill a and b with some values
-for {set i 0} {$i < 200} {incr i 1} {
- set_double $a $i 0.0
- set_double $b $i $i
-}
-
-# Add them and store result in c
-vector_add $a $b $c 200
-
-</pre></blockquote>
-The functions <tt>get_double</tt> and <tt>set_double</tt> can be used to access individual elements of an array. To convert from Tcl lists to C arrays, one could write a few functions in Tcl such as the following :<p>
-<p>
-<blockquote><pre># Tcl Procedure to turn a list into a C array
-proc Tcl2Array {l} {
- set len [llength $l]
- set a [new_double $len]
- set i 0
- foreach item $l {
- set_double $a $i $item
- incr i 1
- }
- return $a
-}
-
-# Tcl Procedure to turn a C array into a Tcl List
-proc Array2Tcl {a size} {
- set l {}
- for {set i 0} {$i < size} {incr i 1} {
- lappend $l [get_double $a $i]
- }
- return $l
-}
-
-</pre></blockquote>
-While not optimal, one could use these to turn a Tcl list into a C representation. The C representation could be used repeatedly in a variety of C functions without having to repeatedly convert from strings (Of course, if the Tcl list changed one would want to update the C version). Likewise, it is relatively simple to go back from C into Tcl. This is not the only way to manage arrays--typemaps can be used as well. The SWIG library file `<tt>array.i</tt>' also contains a variety of pre-written helper functions for managing different kinds of arrays.<p>
-<a name="n9"></a><h2> Building a simple OpenGL module</h2>
-In this example, we consider building a SWIG module out of the OpenGL graphics library. The OpenGL library consists of several hundred functions for building complex 3D images. By wrapping this library, we will be able to play with it interactively from a Tcl interpreter.<p>
-<a name="n45"></a><h3> Required files</h3>
-To build an OpenGL module, you will need to have some variant of OpenGL installed on your machine. If unavailable, the Mesa graphics library is an OpenGL clone that runs on most machines that support X11. We will use the "GL/gl.h", "GL/glu.h", and the GL Auxilliary libraries.<p>
-<a name="n46"></a><h3> Wrapping gl.h</h3>
-The first step is to build an interface from the gl.h file. To do this, follow these steps :<p>
-<p>
-<ul>
-<li>Copy the file <tt>gl.h</tt> to a file <tt>gl.i</tt> which will become the interface.
-<li>Edit the <tt>gl.i</tt> file by taking out unneeded C preprocessor directives and any other clutter that you find.
-<li>Put the following code at the beginning of the<tt> gl.i</tt> file
-<blockquote><pre>
-// gl.i : SWIG file for OpenGL
-%module gl
-%{
-#include <GL/gl.h>
-%}
-
-... Rest of edited gl.h file here ...
-
-</pre></blockquote>
-</ul>
-<p>
-A critical part of this first step is making sure you have the proper set of typedefs in the <tt>gl.i</tt> file. The first part of the file should include definitions such as the following :<p>
-<blockquote><pre>
-typedef unsigned int GLenum;
-typedef unsigned char GLboolean;
-typedef unsigned int GLbitfield;
-typedef signed char GLbyte;
-typedef short GLshort;
-typedef int GLint;
-typedef int GLsizei;
-typedef unsigned char GLubyte;
-typedef unsigned short GLushort;
-typedef unsigned int GLuint;
-typedef float GLfloat;
-typedef float GLclampf;
-typedef double GLdouble;
-typedef double GLclampd;
-typedef void GLvoid;
-</pre></blockquote>
-<a name="n47"></a><h3> Wrapping glu.h</h3>
-Next we write a module for the glu library. The procedure is essentially identical to <tt>gl.h</tt>--that is, we'll copy the header file and edit it slightly. In this case, <tt>glu.h</tt> contains a few functions involving function pointers and arrays. These may generate errors or warnings. As a result, we can simply edit those declarations out. Fortunately, there aren't many declarations like this. If access is required later, the problem can often be fixed with typemaps and helper functions. The final <tt>glu.i</tt> file will look something like this :<p>
-<p>
-<blockquote><pre>%module glu
-%{
-#include <GL/glu.h>
-%}
-
-... rest of edited glu.h file here ...
-
-</pre></blockquote>
-Given these two files, we have a fairly complete OpenGL package. Unfortunately, we still don't have any mechanism for opening a GL window and creating images. To to this, we can wrap the OpenGL auxilliary library which contains functions to open windows and draw various kinds of objects (while not the most powerful approach, it is the simplest to implement and works on most machines).<p>
-<a name="n48"></a><h3> Wrapping the aux library</h3>
-Wrapping the aux library follows exactly the same procedure as before. You will create a file <tt>glaux.i</tt> such as the following :<p>
-<p>
-<blockquote><pre>// File :glaux.i
-%module glaux
-%{
-#include "glaux.h"
-%}
-
-... Rest of edited glaux.h file ...
-
-</pre></blockquote>
-<a name="n49"></a><h3> A few helper functions</h3>
-Finally, to make our library a little easier to use, we need to have a few functions to handle arrays since quite a few OpenGL calls use them as arguments. Small 4 element arrays are particularly useful so we'll create a few helper functions in a file called <tt>help.i.</tt><p>
-<p>
-<blockquote><pre>// help.i : OpenGL helper functions
-
-%inline %{
-GLfloat *newfv4(GLfloat a,GLfloat b,GLfloat c,GLfloat d) {
- GLfloat *f;
- f = (GLfloat *) malloc(4*sizeof(GLfloat));
- f[0] = a; f[1] = b; f[2] = c; f[3] = d;
- return f;
-}
-void setfv4(GLfloat *fv, GLfloat a, GLfloat b, GLfloat c, GLfloat d) {
- fv[0] = a; fv[1] = b; fv[2] = c; fv[3] = d;
-}
-%}
-%name(delfv4) void free(void *);
-</pre></blockquote>
-<a name="n50"></a><h3> An OpenGL package</h3>
-Whew, we're almost done now. The last thing to do is to package up all of our interface files into a single file called <tt>opengl.i</tt>. <p>
-<p>
-<blockquote><pre>
-//
-// opengl.i. SWIG Interface file for OpenGL
-%module opengl
-
-%include gl.i // The main GL functions
-%include glu.i // The GLU library
-%include glaux.i // The aux library
-%include help.i // Our helper functions
-
-</pre></blockquote>
-To build the module, we can simply run SWIG as follows :<p>
-<blockquote><pre>
-unix > swig -tcl opengl.i # Build a dynamicly loaded extension
-
-</pre></blockquote>
-or<p>
-<p>
-<blockquote><pre>unix > swig -tcl -lwish.i opengl.i # Build a statically linked wish executable
-
-</pre></blockquote>
-Compile the file <tt>opengl_wrap.c</tt> with your C compiler and link with Tcl, Tk, and OpenGL to create the final module.<p>
-<a name="n51"></a><h3> Using the OpenGL module</h3>
-The module is now used by writing a Tcl script such as the following :<p>
-<p>
-<blockquote><pre>load ./opengl.so
-auxInitDisplayMode [expr {$AUX_SINGLE | $AUX_RGBA | $AUX_DEPTH}]
-auxInitPosition 0 0 500 500
-auxInitWindow "Lit-Sphere"
-
-# set up material properties
-set mat_specular [newfv4 1.0 1.0 1.0 1.0]
-set mat_shininess [newfv4 50.0 0 0 0]
-set light_position [newfv4 1.0 1.0 1.0 0.0]
-
-glMaterialfv $GL_FRONT $GL_SPECULAR $mat_specular
-glMaterialfv $GL_FRONT $GL_SHININESS $mat_shininess
-glLightfv $GL_LIGHT0 $GL_POSITION $light_position
-glEnable $GL_LIGHTING
-glEnable $GL_LIGHT0
-glDepthFunc $GL_LEQUAL
-glEnable $GL_DEPTH_TEST
-
-# Set up view
-glClearColor 0 0 0 0
-glColor3f 1.0 1.0 1.0
-glMatrixMode $GL_PROJECTION
-glLoadIdentity
-glOrtho -1 1 -1 1 -1 1
-glMatrixMode $GL_MODELVIEW
-glLoadIdentity
-
-# Draw it
-glClear $GL_COLOR_BUFFER_BIT
-glClear $GL_DEPTH_BUFFER_BIT
-auxSolidSphere 0.5
-
-# Clean up
-delfv4 $mat_specular
-delfv4 $mat_shininess
-delfv4 $light_position
-</pre></blockquote>
-<p>
-In our interpreted interface, it is possible to interactively change parameters and see the effects of various OpenGL functions. This a great way to figure out what various functions do and to try different things without having to recompile and run after each change.<p>
-<a name="n52"></a><h3> Problems with the OpenGL interface</h3>
-While the OpenGL interface we have generated is fully usable, it is not without problems.<p>
-<p>
-<ul>
-<li>OpenGL constants are installed as global variables. As a result, it is necessary to use the global keyword when writing Tcl subroutines. For example :
-<blockquote><pre>
-proc clear_screan { } {
- global GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT
- glClear $GL_COLOR_BUFFER_BIT
- glClear $GL_DEPTH_BUFFER_BIT
-}
-
-</pre></blockquote>
-<li>Arrays need to be accessed via helper functions such as our <tt>newfv4</tt>() function. This approach certainly works and its easy enough to implement, but it may be preferable to call certain OpenGL functions with a Tcl list instead. For example :
-<blockquote><pre>
-glMaterialfv $GL_FRONT $GL_SPECULAR {1.0 1.0 1.0 1.0}
-</pre></blockquote>
-</ul>
-<p>
-While these are only minor annoyances, it turns out that you can address both problems using SWIG typemaps (which are discussed shortly).<p>
-<a name="n10"></a><h2> Exception handling </h2>
-The <tt>%except</tt> directive can be used to create a user-definable exception handler in charge of converting exceptions in your C/C++ program into Tcl exceptions. The chapter on exception handling contains more details, but suppose you extended the array example into a C++ class like the following :<p>
-<blockquote><pre>
-class RangeError {}; // Used for an exception
-
-class DoubleArray {
- private:
- int n;
- double *ptr;
- public:
- // Create a new array of fixed size
- DoubleArray(int size) {
- ptr = new double[size];
- n = size;
- }
- // Destroy an array
- ~DoubleArray() {
- delete ptr;
- }
- // Return the length of the array
- int length() {
- return n;
- }
-
- // Get an item from the array and perform bounds checking.
- double getitem(int i) {
- if ((i >= 0) && (i < n))
- return ptr[i];
- else
- throw RangeError();
- }
-
- // Set an item in the array and perform bounds checking.
- void setitem(int i, double val) {
- if ((i >= 0) && (i < n))
- ptr[i] = val;
- else {
- throw RangeError();
- }
- }
- };
-</pre></blockquote>
-<p>
-The functions associated with this class can throw a C++ range exception for an out-of-bounds array access. We can catch this in our Tcl extension by specifying the following in an interface file :<p>
-<p>
-<blockquote><pre>%except(tcl) {
- try {
- $function // Gets substituted by actual function call
- }
- catch (RangeError) {
- interp->result = "Array index out-of-bounds";
- return TCL_ERROR;
- }
-}
-
-</pre></blockquote>
-or in Tcl 8.0<p>
-<p>
-<blockquote><pre>%except(tcl8) {
- try {
- $function // Gets substituted by actual function call
- }
- catch (RangeError) {
- Tcl_SetStringObj(tcl_result,"Array index out-of-bounds");
- return TCL_ERROR;
- }
-}
-
-</pre></blockquote>
-When the C++ class throws a <tt>RangeError</tt> exception, our wrapper functions will catch it, turn it into a Tcl exception, and allow a graceful death as opposed to just having some sort of mysterious program crash. We are not limited to C++ exception handling. Please see the chapter on exception handling for more details on other possibilities, including a method for language-independent exception handling..<p>
-<a name="n11"></a><h2> Typemaps</h2>
-This section describes how SWIG's treatment of various C/C++ datatypes can be remapped using the <tt>%typemap</tt> directive. While not required, this section assumes some familiarity with Tcl's C API. The reader is advised to consult a Tcl book. A glance at the chapter on SWIG typemaps will also be useful. <p>
-<a name="n53"></a><h3> What is a typemap?</h3>
-A typemap is mechanism by which SWIG's processing of a particular C datatype can be changed. A simple typemap might look like this :<p>
-<p>
-<blockquote><pre>%module example
-
-%typemap(tcl,in) int {
- $target = (int) atoi($source);
- printf("Received an integer : %d\n",$target);
-}
-...
-extern int fact(int n);
-</pre></blockquote>
-<p>
-Typemaps require a language name, method name, datatype, and conversion code. For Tcl, "tcl" should be used as the language name. For Tcl 8.0, "tcl8" should be used if you are using the native object interface. The "in" method in this example refers to an input argument of a function. The datatype `int' tells SWIG that we are remapping integers. The supplied code is used to convert from a Tcl string to the corresponding C datatype. Within the supporting C code, the variable <tt>$source</tt> contains the source data (a string in this case) and <tt>$target</tt> contains the destination of a conversion (a C local variable). <p>
-<p>
-When the example is compiled into a Tcl module, it will operate as follows :<p>
-<p>
-<blockquote><pre>% fact 6
-Received an integer : 6
-720
-%
-</pre></blockquote>
-<p>
-A full discussion of typemaps can be found in the main SWIG users reference. We will primarily be concerned with Tcl typemaps here.<p>
-<a name="n54"></a><h3> Tcl typemaps</h3>
-The following typemap methods are available to Tcl modules :<p>
-<p>
-<tt>%typemap(tcl,in)</tt> Converts a string to input function arguments<p>
-<tt>%typemap(tcl,out)</tt> Converts return value of a C function to a string<p>
-<tt>%typemap(tcl,freearg)</tt> Cleans up a function argument (if necessary)<p>
-<tt>%typemap(tcl,argout)</tt> Output argument processing<p>
-<tt>%typemap(tcl,ret)</tt> Cleanup of function return values<p>
-<tt>%typemap(tcl,const)</tt> Creation of Tcl constants<p>
-<tt>%typemap(memberin)</tt> Setting of C++ member data<p>
-<tt>%typemap(memberout)</tt> Return of C++ member data<p>
-<tt>%typemap(tcl, check)</tt> Check value of function arguments.<p>
-<a name="n55"></a><h3> Typemap variables</h3>
-The following variables may be used within the C code used in a typemap:<p>
-<p>
-<tt>$source</tt> Source value of a conversion<p>
-<tt>$target</tt> Target of conversion (where the result should be stored)<p>
-<tt>$type</tt> C datatype being remapped<p>
-<tt>$mangle</tt> Mangled version of data (used for pointer type-checking)<p>
-<tt>$value</tt> Value of a constant (const typemap only)<p>
-<tt>$arg</tt> Original function argument (usually a string)<p>
-<a name="n56"></a><h3> Name based type conversion</h3>
-Typemaps are based both on the datatype and an optional name attached to a datatype. For example :<p>
-<p>
-<blockquote><pre>%module foo
-
-// This typemap will be applied to all char ** function arguments
-%typemap(tcl,in) char ** { ... }
-
-// This typemap is applied only to char ** arguments named `argv'
-%typemap(tcl,in) char **argv { ... }
-
-</pre></blockquote>
-In this example, two typemaps are applied to the <tt>char **</tt> datatype. However, the second typemap will only be applied to arguments named `<tt>argv</tt>'. A named typemap will always override an unnamed typemap.<p>
-<p>
-Due to the name-based nature of typemaps, it is important to note that typemaps are independent of typedef declarations. For example :<p>
-<p>
-<blockquote><pre>%typemap(tcl, in) double {
- ... get a double ...
-}
-void foo(double); // Uses the above typemap
-typedef double Real;
-void bar(Real); // Does not use the above typemap (double != Real)
-
-</pre></blockquote>
-To get around this problem, the <tt>%apply</tt> directive can be used as follows :<p>
-<blockquote><pre>
-%typemap(tcl,in) double {
- ... get a double ...
-}
-void foo(double);
-
-typedef double Real; // Uses typemap
-%apply double { Real }; // Applies all "double" typemaps to Real.
-void bar(Real); // Now uses the same typemap.
-</pre></blockquote>
-<a name="n57"></a><h3> Converting a Tcl list to a char ** </h3>
-A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings. The following SWIG interface file allows a Tcl list to be used as a <tt>char **</tt> object.<p>
-<p>
-<blockquote><pre>%module argv
-
-// This tells SWIG to treat char ** as a special case
-%typemap(tcl,in) char ** {
- int tempc;
- if (Tcl_SplitList(interp,$source,&tempc,&$target) == TCL_ERROR)
- return TCL_ERROR;
-}
-
-// This gives SWIG some cleanup code that will get called after the function call
-%typemap(tcl,freearg) char ** {
- free((char *) $source);
-}
-
-// Return a char ** as a Tcl list
-%typemap(tcl,out) char ** {
- int i = 0;
- while ($source[i]) {
- Tcl_AppendElement(interp,$source[i]);
- i++;
- }
-}
-
-// Now a few test functions
-%inline %{
-int print_args(char **argv) {
- int i = 0;
- while (argv[i]) {
- printf("argv[%d] = %s\n", i,argv[i]);
- i++;
- }
- return i;
-}
-
-
-// Returns a char ** list
-char **get_args() {
- static char *values[] = { "Dave", "Mike", "Susan", "John", "Michelle", 0};
- return &values[0];
-}
-
-// A global variable
-char *args[] = { "123", "54", "-2", "0", "NULL", 0 };
-
-%}
-%include tclsh.i
-
-</pre></blockquote>
-When compiled, we can use our functions as follows :<p>
-<p>
-<blockquote><pre>% print_args {John Guido Larry}
-argv[0] = John
-argv[1] = Guido
-argv[2] = Larry
-3
-% puts [get_args]
-Dave Mike Susan John Michelle
-% puts [args_get]
-123 54 -2 0 NULL
-%
-</pre></blockquote>
-<p>
-Perhaps the only tricky part of this example is the implicit memory allocation that is performed by the <tt>Tcl_SplitList</tt> function. To prevent a memory leak, we can use the SWIG "freearg" typemap to clean up the argument value after the function call is made. In this case, we simply free up the memory that <tt>Tcl_SplitList</tt> allocated for us.<p>
-<a name="n58"></a><h3> Remapping constants</h3>
-By default, SWIG installs C constants as Tcl read-only variables. Unfortunately, this has the undesirable side effect that constants need to be declared as "global" when used in subroutines. For example :<p>
-<p>
-<blockquote><pre>proc clearscreen { } {
- global GL_COLOR_BUFFER_BIT
- glClear $GL_COLOR_BUFFER_BIT
-}
-
-</pre></blockquote>
-If you have hundreds of functions however, this quickly gets annoying. Here's a fix using hash tables and SWIG typemaps :<p>
-<p>
-<blockquote><pre>// Declare some Tcl hash table variables
-%{
-static Tcl_HashTable constTable; /* Hash table */
-static int *swigconst; /* Temporary variable */
-static Tcl_HashEntry *entryPtr; /* Hash entry */
-static int dummy; /* dummy value */
-%}
-
-// Initialize the hash table (This goes in the initialization function)
-
-%init %{
- Tcl_InitHashTable(&constTable,TCL_STRING_KEYS);
-%}
-
-// A Typemap for creating constant values
-// $source = the value of the constant
-// $target = the name of the constant
-
-%typemap(tcl,const) int, unsigned int, long, unsigned long {
- entryPtr = Tcl_CreateHashEntry(&constTable,"$target",&dummy);
- swigconst = (int *) malloc(sizeof(int));
- *swigconst = $source;
- Tcl_SetHashValue(entryPtr, swigconst);
- /* Make it so constants can also be used as variables */
- Tcl_LinkVar(interp,"$target", (char *) swigconst, TCL_LINK_INT | TCL_LINK_READ_ONLY);
-};
-
-// Now change integer handling to look for names in addition to values
-%typemap(tcl,in) int, unsigned int, long, unsigned long {
- Tcl_HashEntry *entryPtr;
- entryPtr = Tcl_FindHashEntry(&constTable,$source);
- if (entryPtr) {
- $target = ($type) (*((int *) Tcl_GetHashValue(entryPtr)));
- } else {
- $target = ($type) atoi($source);
- }
-}
-
-</pre></blockquote>
-In our Tcl code, we can now access constants by name without using the "global" keyword as follows :<p>
-<p>
-<blockquote><pre>proc clearscreen { } {
- glClear GL_COLOR_BUFFER_BIT
-}
-
-</pre></blockquote>
-<a name="n59"></a><h3> Returning values in arguments</h3>
-The "argout" typemap can be used to return a value originating from a function argument. For example :<p>
-<p>
-<blockquote><pre>// A typemap defining how to return an argument by appending it to the result
-%typemap(tcl,argout) double *outvalue {
- char dtemp[TCL_DOUBLE_SPACE];
- Tcl_PrintDouble(interp,*($source),dtemp);
- Tcl_AppendElement(interp, dtemp);
-}
-
-// A typemap telling SWIG to ignore an argument for input
-// However, we still need to pass a pointer to the C function
-%typemap(tcl,ignore) double *outvalue {
- static double temp; /* A temporary holding place */
- $target = &temp;
-}
-
-// Now a function returning two values
-int mypow(double a, double b, double *outvalue) {
- if ((a < 0) || (b < 0)) return -1;
- *outvalue = pow(a,b);
- return 0;
-};
-
-</pre></blockquote>
-When wrapped, SWIG matches the <tt>argout</tt> typemap to the "<tt>double *outvalue</tt>" argument. The "ignore" typemap tells SWIG to simply ignore this argument when generating wrapper code. As a result, a Tcl function using these typemaps will work like this :<p>
-<p>
-<blockquote><pre>% mypow 2 3 # Returns two values, a status value and the result
-0 8
-%
-</pre></blockquote>
-<p>
-An alternative approach to this is to return values in a Tcl variable as follows :<p>
-<p>
-<blockquote><pre>%typemap(tcl,argout) double *outvalue {
- char temp[TCL_DOUBLE_SPACE];
- Tcl_PrintDouble(interp,*($source),dtemp);
- Tcl_SetVar(interp,$arg,temp,0);
-}
-%typemap(tcl,in) double *outvalue {
- static double temp;
- $target = &temp;
-}
-
-</pre></blockquote>
-Our Tcl script can now do the following :<p>
-<p>
-<blockquote><pre>% set status [mypow 2 3 a]
-% puts $status
-0
-% puts $a
-8.0
-%
-</pre></blockquote>
-Here, we have passed the name of a Tcl variable to our C wrapper function which then places the return value in that variable. This is now very close to the way in which a C function calling this function would work.<p>
-<a name="n60"></a><h3> Mapping C structures into Tcl Lists</h3>
-Suppose you have a C structure like this :<p>
-<p>
-<blockquote><pre>typedef struct {
- char login[16]; /* Login ID */
- int uid; /* User ID */
- int gid; /* Group ID */
- char name[32]; /* User name */
- char home[256]; /* Home directory */
-} User;
-
-</pre></blockquote>
-By default, SWIG will simply treat all occurrences of "<tt>User</tt>" as a pointer. Thus, functions like this :<p>
-<p>
-<blockquote><pre>extern void add_user(User u);
-extern User *lookup_user(char *name);
-
-</pre></blockquote>
-will work, but they will be weird. In fact, they may not work at all unless you write helper functions to create users and extract data. A typemap can be used to fix this problem however. For example :<p>
-<p>
-<blockquote><pre>// This works for both "User" and "User *"
-%typemap(tcl,in) User * {
- int tempc;
- char **tempa;
- static User temp;
- if (Tcl_SplitList(interp,$source,&tempc,&tempa) == TCL_ERROR) return TCL_ERROR;
- if (tempc != 5) {
- free((char *) tempa);
- interp->result = "Not a valid User record";
- return TCL_ERROR;
- }
- /* Split out the different fields */
- strncpy(temp.login,tempa[0],16);
- temp.uid = atoi(tempa[1]);
- temp.gid = atoi(tempa[2]);
- strncpy(temp.name,tempa[3],32);
- strncpy(temp.home,tempa[4],256);
- $target = &temp;
- free((char *) tempa);
-}
-
-// Describe how we want to return a user record
-%typemap(tcl,out) User * {
- char temp[20];
- if ($source) {
- Tcl_AppendElement(interp,$source->login);
- sprintf(temp,"%d",$source->uid);
- Tcl_AppendElement(interp,temp);
- sprintf(temp,"%d",$source->gid);
- Tcl_AppendElement(interp,temp);
- Tcl_AppendElement(interp,$source->name);
- Tcl_AppendElement(interp,$source->home);
- }
-}
-</pre></blockquote>
-<p>
-These function marshall Tcl lists to and from our <tt>User</tt> data structure. This allows a more natural implementation that we can use as follows :<p>
-<p>
-<blockquote><pre>% add_user {beazley 500 500 "Dave Beazley" "/home/beazley"}
-% lookup_user beazley
-beazley 500 500 {Dave Beazley} /home/beazley
-
-</pre></blockquote>
-This is a much cleaner interface (although at the cost of some performance). The only caution I offer is that the pointer view of the world is pervasive throughout SWIG. Remapping complex datatypes like this will usually work, but every now and then you might find that it breaks. For example, if we needed to manipulate arrays of Users (also mapped as a "<tt>User *</tt>"), the typemaps defined here would break down and something else would be needed. Changing the representation in this manner may also break the object-oriented interface. <p>
-<a name="n61"></a><h3> Useful functions</h3>
-The following tables provide some functions that may be useful in writing Tcl typemaps. Both Tcl 7.x and Tcl 8.x are covered. For Tcl 7.x, everything is a string so the interface is relatively simple. For Tcl 8, everything is now a Tcl object so a more precise set of functions is required. Given the alpha-release status of Tcl 8, the functions described here may change in future releases.<p>
-<center>
-<img src="ch10.table.1.png"><br>
-<img src="ch10.table.2.png"><br>
-<img src="ch10.table.3.png"><br>
-<img src="ch10.table.4.png"><br>
-<img src="ch10.table.5.png"><br>
-<img src="ch10.table.6.png"><br>
-<img src="ch10.table.7.png">
-</center><p>
-<p>
-<a name="n62"></a><h3> Standard typemaps</h3>
-The following typemaps show how to convert a few common kinds of objects between Tcl and C (and to give a better idea of how typemaps work)<p>
-<center>
-<img src="ch10.table.8.png"><br>
-<img src="ch10.table.9.png"><br>
-<img src="ch10.table.10.png"><br>
-<img src="ch10.table.11.png">
-</center><p>
-<p>
-<a name="n63"></a><h3> Pointer handling</h3>
-SWIG pointers are mapped into Python strings containing the hexadecimal value and type. The following functions can be used to create and read pointer values.<p>
-<center><img src="ch10.table.12.png"></center><p>
-<p>
-These functions can be used in typemaps as well. For example, the following typemap makes an argument of "<tt>char *buffer</tt>" accept a pointer instead of a NULL-terminated ASCII string.<p>
-<p>
-<blockquote><pre>%typemap(tcl,in) char *buffer {
- if (SWIG_GetPtr($source, (void **) &$target, "$mangle")) {
- Tcl_SetResult(interp,"Type error. Not a pointer", TCL_STATIC);
- return TCL_ERROR;
- }
-}
-
-</pre></blockquote>
-Note that the <tt>$mangle</tt> variable generates the type string associated with the datatype used in the typemap.<p>
-<p>
-By now you hopefully have the idea that typemaps are a powerful mechanism for building more specialized applications. While writing typemaps can be technical, many have already been written for you. See the SWIG library reference for more information.<p>
-<a name="n12"></a><h2> Configuration management with SWIG</h2>
-After you start to work with Tcl for awhile, you suddenly realize that there are an unimaginable number of extensions, tools, and other packages. To make matters worse, there are about 20 billion different versions of Tcl, not all of which are compatible with each extension (this is to make life interesting of course).<p>
-<p>
-While SWIG is certainly not a magical solution to the configuration management problem, it can help out alot in a number of key areas :<p>
-<p>
-<ul>
-<li>SWIG generated code can be used with all versions of Tcl/Tk newer than 7.3/3.6. This includes the Tcl Netscape Plugin and Tcl 8.0a2.
-<li>The SWIG library mechanism can be used to manage various code fragments and initialization functions.
-<li>SWIG generated code usually requires no modification so it is relatively easy to switch between different Tcl versions as necessary or upgrade to a newer version when the time comes (of course, the Sun Tcl/Tk team might have changed other things to keep you occupied)
-</ul>
-<a name="n64"></a><h3> Writing a main program and Tcl_AppInit()</h3>
-The traditional method of creating a new Tcl extension required a programmer to write a special function called <tt>Tcl_AppInit()</tt> that would initialize your extension and start the Tcl interpreter. A typical <tt>Tcl_AppInit()</tt> function looks like the following :<p>
-<p>
-<blockquote><pre>/* main.c */
-#include <tcl.h>
-
-main(int argc, char *argv[]) {
- Tcl_Main(argc,argv);
- exit(0);
-}
-
-int Tcl_AppInit(Tcl_Interp *interp) {
- if (Tcl_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
-
- /* Initialize your extension */
- if (Your_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
-
- tcl_RcFileName = "~/.myapp.tcl";
- return TCL_OK;
-}
-
-</pre></blockquote>
-While relatively simple to write, there are tons of problems with doing this. First, each extension that you use typically has their own <tt>Tcl_AppInit()</tt> function. This forces you to write a special one to initialize everything by hand. Secondly, the process of writing a main program and initializing the interpreter varies between different versions of Tcl and different platforms. For example, in Tcl 7.4, the variable "<tt>tcl_RcFileName</tt>" is a C variable while in Tcl7.5 and newer versions its a Tcl variable instead. Similarly, the <tt>Tcl_AppInit</tt> function written for a Unix machine might not compile correctly on a Mac or Windows machine.<p>
-<p>
-In SWIG, it is almost never necessary to write a <tt>Tcl_AppInit()</tt> function because this is now done by SWIG library files such as <tt>tclsh.i</tt> or <tt>wish.i</tt>. To give a better idea of what these files do, here's the code from the SWIG <tt>tclsh.i</tt> file which is roughly comparable to the above code<p>
-<blockquote><pre>
-// tclsh.i : SWIG library file for rebuilding tclsh
-%{
-
-/* A TCL_AppInit() function that lets you build a new copy
- * of tclsh.
- *
- * The macro SWIG_init contains the name of the initialization
- * function in the wrapper file.
- */
-
-#ifndef SWIG_RcFileName
-char *SWIG_RcFileName = "~/.myapprc";
-#endif
-
-int Tcl_AppInit(Tcl_Interp *interp){
-
- if (Tcl_Init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- /* Now initialize our functions */
- if (SWIG_init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
-#if TCL_MAJOR_VERSION > 7 || TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION >= 5
- Tcl_SetVar(interp,"tcl_rcFileName",SWIG_RcFileName,TCL_GLOBAL_ONLY);
-#else
- tcl_RcFileName = SWIG_RcFileName;
-#endif
- return TCL_OK;
-}
-
-#if TCL_MAJOR_VERSION > 7 || TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION >= 4
-int main(int argc, char **argv) {
- Tcl_Main(argc, argv, Tcl_AppInit);
- return(0);
-
-}
-#else
-extern int main();
-#endif
-
-%}
-</pre></blockquote>
-<p>
-This file is essentially the same as a normal <tt>Tcl_AppInit()</tt> function except that it supports a variety of Tcl versions. When included into an interface file, the symbol <tt>SWIG_init</tt> contains the actual name of the initialization function (This symbol is defined by SWIG when it creates the wrapper code). Similarly, a startup file can be defined by simply defining the symbol <tt>SWIG_RcFileName</tt>. Thus, a typical interface file might look like this :<p>
-<p>
-<blockquote><pre>%module graph
-%{
-#include "graph.h"
-#define SWIG_RcFileName "graph.tcl"
-%}
-
-%include tclsh.i
-
-... declarations ...
-
-
-</pre></blockquote>
-By including the <tt>tclsh.i</tt>, you automatically get a <tt>Tcl_AppInit()</tt> function. A variety of library files are also available. <tt>wish.i</tt> can be used to build a new wish executable, <tt>expect.i</tt> contains the main program for Expect, and <tt>ish.i</tt>, <tt>itclsh.i</tt>, <tt>iwish.i</tt>, and <tt>itkwish.i</tt> contain initializations for various incarnations of [incr Tcl].<p>
-<a name="n65"></a><h3> Creating a new package initialization library</h3>
-If a particular Tcl extension requires special initialization, you can create a special SWIG library file to initialize it. For example, a library file to extend Expect looks like the following :<p>
-<p>
-<blockquote><pre>
-// expect.i : SWIG Library file for Expect
-%{
-
-/* main.c - main() and some logging routines for expect
-
-Written by: Don Libes, NIST, 2/6/90
-
-Design and implementation of this program was paid for by U.S. tax
-dollars. Therefore it is public domain. However, the author and NIST
-would appreciate credit if this program or parts of it are used.
-*/
-
-#include "expect_cf.h"
-#include <stdio.h>
-#include INCLUDE_TCL
-#include "expect_tcl.h"
-
-void
-main(argc, argv)
-int argc;
-char *argv[];
-{
- int rc = 0;
- Tcl_Interp *interp = Tcl_CreateInterp();
- int SWIG_init(Tcl_Interp *);
-
- if (Tcl_Init(interp) == TCL_ERROR) {
- fprintf(stderr,"Tcl_Init failed: %s\n",interp->result);
- exit(1);
- }
- if (Exp_Init(interp) == TCL_ERROR) {
- fprintf(stderr,"Exp_Init failed: %s\n",interp->result);
- exit(1);
- }
-
- /* SWIG initialization. --- 2/11/96 */
- if (SWIG_init(interp) == TCL_ERROR) {
- fprintf(stderr,"SWIG initialization failed: %s\n", interp->result);
- exit(1);
- }
-
- exp_parse_argv(interp,argc,argv);
- /* become interactive if requested or "nothing to do" */
- if (exp_interactive)
- (void) exp_interpreter(interp);
- else if (exp_cmdfile)
- rc = exp_interpret_cmdfile(interp,exp_cmdfile);
- else if (exp_cmdfilename)
- rc = exp_interpret_cmdfilename(interp,exp_cmdfilename);
-
- /* assert(exp_cmdlinecmds != 0) */
- exp_exit(interp,rc);
- /*NOTREACHED*/
-}
-%}
-</pre></blockquote>
-<p>
-In the event that you need to write a new library file such as this, the process usually isn't too difficult. Start by grabbing the original <tt>Tcl_AppInit()</tt> function for the package. Enclose it in a <tt>%{,%}</tt> block. Now add a line that makes a call to <tt>SWIG_init()</tt>. This will automatically resolve to the real initialization function when compiled.<p>
-<a name="n66"></a><h3> Combining Tcl/Tk Extensions</h3>
-A slightly different problem concerns the mixing of various extensions. Most extensions don't require any special initialization other than calling their initialization function. To do this, we also use SWIG library mechanism. For example :<p>
-<p>
-<blockquote><pre>// blt.i : SWIG library file for initializing the BLT extension
-%{
-#ifdef __cplusplus
-extern "C" {
-#endif
-extern int Blt_Init(Tcl_Interp *);
-#ifdef __cplusplus
-}
-#endif
-%}
-%init %{
- if (Blt_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
-%}
-
-
-// tix.i : SWIG library file for initializing the Tix extension
-%{
-#ifdef __cplusplus
-extern "C" {
-#endif
-extern int Tix_Init(Tcl_Interp *);
-#ifdef __cplusplus
-}
-#endif
-%}
-%init %{
- if (Tix_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
-%}
-
-</pre></blockquote>
-Both files declare the proper initialization function (to be C++ friendly, this should be done using <tt>extern "C"</tt>). A call to the initialization function is then placed inside a <tt>%init %{ ... %}</tt> block. <p>
-<p>
-To use our library files and build a new version of wish, we might now do the following :<p>
-<p>
-<blockquote><pre>// mywish.i : wish with a bunch of stuff added to it
-%include wish.i
-%include blt.i
-%include tix.i
-
-... additional declarations ...
-
-</pre></blockquote>
-Of course, the really cool part about all of this is that the file `<tt>mywish.i</tt>' can itself, serve as a library file. Thus, when building various versions of Tcl, we can place everything we want to use a special file and use it in all of our other interface files :<p>
-<p>
-<blockquote><pre>// interface.i
-%module mymodule
-
-%include mywish.i // Build our version of Tcl with extensions
-
-... C declarations ...
-
-</pre></blockquote>
-or we can grab it on the command line :<p>
-<p>
-<blockquote><pre>unix > swig -tcl -lmywish.i interface.i
-
-</pre></blockquote>
-<a name="n67"></a><h3> Limitations to this approach</h3>
-This interface generation approach is limited by the compatibility of each extension you use. If any one extension is incompatible with the version of Tcl you are using, you may be out of luck. It is also critical to pay careful attention to libraries and include files. An extension library compiled against an older version of Tcl may fail when linked with a newer version. <p>
-<a name="n68"></a><h3> Dynamic loading </h3>
-Newer versions of Tcl support dynamic loading. With dynamic loading, you compile each extension into a separate module that can be loaded at run time. This simplifies a number of compilation and extension building problems at the expense of creating new ones. Most notably, the dynamic loading process varies widely between machines and is not even supported in some cases. It also does not work well with C++ programs that use static constructors. Modules linked with older versions of Tcl may not work with newer versions as well (although SWIG only really uses the basic Tcl C interface). As a result, I usually find myself using both dynamic and static linking as appropriate. <p>
-<a name="n69"></a><h3> Turning a SWIG module into a Tcl Package.</h3>
-Tcl 7.4 introduced the idea of an extension package. By default, SWIG does not create "packages", but it is relatively easy to do. To make a C extension into a Tcl package, you need to provide a call to <tt>Tcl_PkgProvide() </tt>in the module initialization function<tt>.</tt> This can be done in an interface file as follows :<p>
-<p>
-<blockquote><pre>%init %{
- Tcl_PkgProvide(interp,"example","0.0");
-%}
-</pre></blockquote>
-<p>
-Where "example" is the name of the package and "0.0" is the version of the package. <p>
-<p>
-Next, after building the SWIG generated module, you need to execute the "<tt>pkg_mkIndex</tt>" command inside tclsh. For example :<p>
-<blockquote><pre>
-unix > tclsh
-% pkg_mkIndex . example.so
-% exit
-
-</pre></blockquote>
-This creates a file "<tt>pkgIndex.tcl</tt>" with information about the package. To use your<p>
-package, you now need to move it to its own subdirectory which has the same name as the package. For example :<p>
-<p>
-<blockquote><pre>./example/
- pkgIndex.tcl # The file created by pkg_mkIndex
- example.so # The SWIG generated module
-
-</pre></blockquote>
-<p>
-Finally, assuming that you're not entirely confused at this point, make sure that the example subdirectory is visible from the directories contained in either the <tt>tcl_library</tt> or <tt>auto_path</tt> variables. At this point you're ready to use the package as follows :<p>
-<blockquote><pre>
-unix > tclsh
-% package require example
-% fact 4
-24
-%
-</pre></blockquote>
-<p>
-If you're working with an example in the current directory and this doesn't work, do this instead :<p>
-<p>
-<blockquote><pre>unix > tclsh
-% lappend auto_path .
-% package require example
-% fact 4
-24
-
-</pre></blockquote>
-<p>
-As a final note, most SWIG examples do not yet use the <tt>package</tt> commands. For simple extensions it may be easier just to use the <tt>load</tt> command instead.<p>
-<a name="n13"></a><h2> Building new kinds of Tcl interfaces (in Tcl)</h2>
-One of the most interesting aspects of Tcl and SWIG is that you can create entirely new kinds of Tcl interfaces in Tcl using the low-level SWIG accessor functions. For example, suppose you had a library of helper functions to access arrays :<p>
-<p>
-<blockquote><pre>/* File : array.i */
-%module array
-
-%inline %{
-double *new_double(int size) {
- return (double *) malloc(size*sizeof(double));
-}
-void delete_double(double *a) {
- free(a);
-}
-double get_double(double *a, int index) {
- return a[index];
-}
-void set_double(double *a, int index, double val) {
- a[index] = val;
-}
-int *new_int(int size) {
- return (int *) malloc(size*sizeof(int));
-}
-void delete_int(int *a) {
- free(a);
-}
-int get_int(int *a, int index) {
- return a[index];
-}
-int set_int(int *a, int index, int val) {
- a[index] = val;
-}
-%}
-
-</pre></blockquote>
-While these could be called directly, we could also write a Tcl script like this :<p>
-<p>
-<blockquote><pre>proc Array {type size} {
- set ptr [new_$type $size]
- set code {
- set method [lindex $args 0]
- set parms [concat $ptr [lrange $args 1 end]]
- switch $method {
- get {return [eval "get_$type $parms"]}
- set {return [eval "set_$type $parms"]}
- delete {eval "delete_$type $ptr; rename $ptr {}"}
- }
- }
- # Create a procedure
- uplevel "proc $ptr args {set ptr $ptr; set type $type;$code}"
- return $ptr
-}
-</pre></blockquote>
-<p>
-Our script allows easy array access as follows :<p>
-<p>
-<blockquote><pre>set a [Array double 100] ;# Create a double [100]
-for {set i 0} {$i < 100} {incr i 1} { ;# Clear the array
- $a set $i 0.0
-}
-$a set 3 3.1455 ;# Set an individual element
-set b [$a get 10] ;# Retrieve an element
-
-set ia [Array int 50] ;# Create an int[50]
-for {set i 0} {$i < 50} {incr i 1} { ;# Clear it
- $ia set $i 0
-}
-$ia set 3 7 ;# Set an individual element
-set ib [$ia get 10] ;# Get an individual element
-
-$a delete ;# Destroy a
-$ia delete ;# Destroy ia
-</pre></blockquote>
-<p>
-The cool thing about this approach is that it makes a common interface for two different types of arrays. In fact, if we were to add more C datatypes to our wrapper file, the Tcl code would work with those as well--without modification. If an unsupported datatype was requested, the Tcl code would simply return with an error so there is very little danger of blowing something up (although it is easily accomplished with an out of bounds array access).<p>
-<a name="n70"></a><h3> Shadow classes</h3>
-A similar approach can be applied to shadow classes. The following example is provided by Erik Bierwagen and Paul Saxe. To use it, run SWIG with the <tt>-noobject</tt> option (which disables the builtin object oriented interface). When running Tcl, simply source this file. Now, objects can be used in a more or less natural fashion.<p>
-<p>
-<blockquote><pre># swig_c++.tcl
-# Provides a simple object oriented interface using
-# SWIG's low level interface.
-#
-
-proc new {objectType handle_r args} {
- # Creates a new SWIG object of the given type,
- # returning a handle in the variable "handle_r".
- #
- # Also creates a procedure for the object and a trace on
- # the handle variable that deletes the object when the
- # handle varibale is overwritten or unset
- upvar $handle_r handle
- #
- # Create the new object
- #
- eval set handle \[new_$objectType $args\]
- #
- # Set up the object procedure
- #
- proc $handle {cmd args} "eval ${objectType}_\$cmd $handle \$args"
- #
- # And the trace ...
- #
- uplevel trace variable $handle_r uw "{deleteObject $objectType $handle}"
- #
- # Return the handle so that 'new' can be used as an argument to a procedure
- #
- return $handle
-}
-
-proc deleteObject {objectType handle name element op} {
- #
- # Check that the object handle has a reasonable form
- #
- if {![regexp {_[0-9a-f]*_(.+)_p} $handle]} {
- error "deleteObject: not a valid object handle: $handle"
- }
- #
- # Remove the object procedure
- #
- catch {rename $handle {}}
- #
- # Delete the object
- #
- delete_$objectType $handle
-}
-
-proc delete {handle_r} {
- #
- # A synonym for unset that is more familiar to C++ programmers
- #
- uplevel unset $handle_r
-}
-</pre></blockquote>
-<p>
-To use this file, we simply source it and execute commands such as "new" and "delete" to manipulate objects. For example :<p>
-<p>
-<blockquote><pre>// list.i
-%module List
-%{
-#include "list.h"
-%}
-
-// Very simple C++ example
-
-class List {
-public:
- List(); // Create a new list
- ~List(); // Destroy a list
- int search(char *value);
- void insert(char *); // Insert a new item into the list
- void remove(char *); // Remove item from list
- char *get(int n); // Get the nth item in the list
- int length; // The current length of the list
-static void print(List *l); // Print out the contents of the list
-};
-</pre></blockquote>
-<p>
-Now a Tcl script using the interface...<p>
-<p>
-<blockquote><pre>load ./list.so list ; # Load the module
-source swig_c++.tcl ; # Source the object file
-
-new List l
-$l insert Dave
-$l insert John
-$l insert Guido
-$l remove Dave
-puts $l length_get
-
-delete l
-
-</pre></blockquote>
-The cool thing about this example is that it works with any C++ object wrapped by SWIG and requires no special compilation. Proof that a short, but clever Tcl script can be combined with SWIG to do many interesting things.<p>
-<a name="n14"></a><h2> Extending the Tcl Netscape Plugin</h2>
-SWIG can be used to extend the Tcl Netscape plugin with C functions. As of this writing it has only been tested with version 1.0 of the plugin on Solaris and Irix 6.2. It may work on other machines as well. However, first a word of caution --- doing this might result in serious injury as you can add just about any C function you want. Furthermore, it's not portable (hey, we're talking C code here). It seems like the best application of this would be creating a browser interface to a highly specialized application. Any scripts that you would write would not work on other machines unless they also installed the C extension code as well. Perhaps we should call this a plugin-plugin...<p>
-<p>
-To use the plugin, use the <tt>-plugin</tt> option :<p>
-<p>
-<blockquote><pre>swig -tcl -plugin interface.i
-
-</pre></blockquote>
-This adds a "safe" initialization function compatible with the plugin (in reality, it just calls the function SWIG already creates). You also need to put the following symbol in your interface file for it to work :<p>
-<p>
-<blockquote><pre>%{
-#define SAFE_SWIG
-%}
-
-</pre></blockquote>
-The folks at Sun are quite concerned about the security implications of this sort of extension and originally wanted the user to modify the wrapper code by hand to "remind" them that they were installing functions into a safe interpreter. However, having seen alot of SWIG generated wrapper code, I hated that idea (okay, so the output of SWIG is just a little messy). This is compromise--you need to put that <tt>#define</tt> into your C file someplace. You can also just make it a compiler option if you would like.<p>
-<a name="n71"></a><h3> The step-by-step process for making a plugin extension.</h3>
-Making a plugin extension is relatively straightforward but you need to follow these steps :<p>
-<p>
-<ul>
-<li>Make sure you have Tcl7.6/Tk4.2 installed on your machine. We're going to need the header files into order to compile the extension.
-<li>Make sure you have the Netscape plugin properly installed.
-<li>Run SWIG using the `<tt>-tcl -plugin</tt>' options.
-<li>Compile the extension using the Tcl 7.6/Tk4.2 header files, but linking against the plugin itself. For example :
-<blockquote><pre>
-unix > gcc -I/usr/local/include -c example.o interface_wrap.c
-unix > ld -shared example.o interface_wrap.o \
- -L/home/beazley/.netscape/plugins/libtclplugin.so -o example.so
-
-</pre></blockquote>
-<li>Copy the shared object file to the <tt>~/.tclplug/tcl7.7</tt> directory.
-</ul>
-<a name="n72"></a><h3> Using the plugin</h3>
-To use the plugin, place the following line in your Tcl scripts :<p>
-<p>
-<blockquote><pre>load $tcl_library/example.so example
-
-</pre></blockquote>
-With luck, you will now be ready to run (at least that's the theory).<p>
-<a name="n15"></a><h2> Tcl8.0 features</h2>
-SWIG 1.1 now supports Tcl 8.0. However, considering the beta release nature of Tcl 8.0, anything presented here is subject to change. Currently only Tcl 8.0b1 is supported. None of the alpha releases are supported due to a change in the C API. <p>
-<p>
-The Tcl 8.0 module uses the new Tcl 8.0 object interface whenever possible. Instead of using strings, the object interface provides more direct access to objects in their native representation. As a result, the performance is significantly better. The older Tcl SWIG module is also compatible with Tcl 8.0, but since it uses strings it will be much slower than the new version.<p>
-<p>
-In addition to using native Tcl objects, the Tcl8.0 manipulates pointers directly in in a special Tcl object. On the surface it still looks like a string, but internally its represented a (value,type) pair. This too, should offer somewhat better performance.<p>
-<p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:47:12 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/Typemaps.html b/swigweb/Doc1.1/HTML/Typemaps.html
deleted file mode 100644
index 615a2cb..0000000
--- a/swigweb/Doc1.1/HTML/Typemaps.html
+++ /dev/null
@@ -1,733 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Pointers, Constraints, and Typemaps</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1>6 Pointers, Constraints, and Typemaps</h1><p><ul>
-<li> <a href="#n1">Introduction</a>
-<li> <a href="#n2">The SWIG Pointer Library</a>
-<li> <a href="#n3">Introduction to typemaps</a>
-<li> <a href="#n4">Managing input and output parameters</a>
-<li> <a href="#n5">Applying constraints to input values</a>
-<li> <a href="#n6">Writing new typemaps</a>
-<li> <a href="#n7">Common typemap methods</a>
-<li> <a href="#n8">Writing typemap code</a>
-<li> <a href="#n9">Typemaps for handling arrays</a>
-<li> <a href="#n10">Typemaps and the SWIG Library</a>
-<li> <a href="#n11">Implementing constraints with typemaps</a>
-<li> <a href="#n12">Typemap examples</a>
-<li> <a href="#n13">How to break everything with a typemap</a>
-<li> <a href="#n14">Typemaps and the future</a>
-</ul>
-
-<a name="n1"></a><h2> Introduction</h2>
-For most applications, SWIG's treatment of basic datatypes and pointers is enough to build an interface. However, in certain cases, it is desirable to change SWIG's treatment of particular datatypes. For example, we may want a <tt>char ** </tt>to act like a list of strings instead of a pointer. In another instance, we may want to tell SWIG that <tt>double *result</tt> is the output value of a function. Similarly, we might want to map a datatype of <tt>float[4]</tt> into a 4 element tuple. This chapter describes advanced methods for managing pointers, arrays, and complex datatypes. It also describes how you can customize SWIG to handle new kinds of objects and datatypes.<p>
-<a name="n2"></a><h2> The SWIG Pointer Library</h2>
-If your interface involves C pointers, chances are you will need to work with these pointers in some way or another. The SWIG pointer library provides a collection of useful methods for manipulating pointers. To use the library, simply put the following declaration in your interface file :<p>
-<p>
-<blockquote><pre>%include pointer.i // Grab the SWIG pointer library
-
-</pre></blockquote>
-or run SWIG as follows :<p>
-<p>
-<blockquote><pre>swig -perl5 -lpointer.i interface.i
-
-</pre></blockquote>
-Doing so adds a collection of pointer manipulation functions that are described below. The functions are mainly designed to work with basic C datatypes, but can often be used with more complicated structures.<p>
-<a name="n15"></a><h3> Pointer Library Functions</h3>
-<b>ptrcreate(type,?value?,?nitems?)</b><p>
-<dl>
-<dt><dd>
-<dt><dd>Creates a new object and returns a pointer to it. <tt>type</tt> is a string containing the C datatype and may be one of "<tt>int</tt>","<tt>short</tt>","<tt>long</tt>","<tt>float</tt>","<tt>double</tt>","<tt>char</tt>","<tt>char *</tt>", or "<tt>void</tt>". <tt>value</tt> is the optional initial value to be assigned to the object. <tt>nitems</tt> is an optional parameter containing the number of objects to create. By default it is 1, but specifying another value allows you to create an array of values. This function is really just a wrapper around the C <tt>malloc()</tt> function.
-</dl>
-<b></b><p>
-<b>ptrfree(ptr)</b><p>
-<dl>
-<dt><dd>Destroys an object created by <tt>ptrcreate</tt>. It is generally unsafe to use this function on objects not created by <tt>ptrcreate</tt>. Calls the C <tt>free()</tt> function.
-</dl>
-<p>
-<b>ptrvalue(ptr,?index?,?type?)</b><p>
-<dl>
-<dt><dd>This dereferences a pointer and returns the value that it is pointing to. <tt>index</tt> is an optional parameter that allows array access by returning the value of <tt>ptr[index]</tt>. <tt>type</tt> is an optional parameter that explicitly specifies the datatype. Since SWIG pointers are encoded with type information, the type is usually unnecessary. The <tt>type</tt> parameter provides somewhat better performance and allows you to dereference a pointer of different type however.
-<dt><dd>
-</dl>
-<b>ptrset(ptr, value, ?index?, ?type?)</b><p>
-<dl>
-<dt><dd>Sets the value of the object a pointer is pointing to. <tt>value</tt> is the new value of the object. <tt>index </tt>is an optional parameter allowing array access by setting <tt>ptr[index] = value</tt>. <tt>type </tt>is an optional parameter that explicitly specifies the datatype as described above.
-<dt><dd>
-</dl>
-<b>ptrcast(ptr, newtype)</b><p>
-<dl>
-<dt><dd>Casts a pointer to a new datatype and returns the new value. <tt>newtype</tt> is a string containing the new datatype and may either be the "mangled" version used by SWIG (such as "<tt>_Vector_p</tt>") or the C version (such as "<tt>Vector *</tt>"). This function works with any kind of pointer value. In additional to pointers, <tt>ptr</tt> may also hold an integer value in which case the integer is turned into a pointer of given type.
-<dt><dd>
-</dl>
-<b>ptradd(ptr, offset)</b><p>
-<dl>
-<dt><dd>Adds an offset to a pointer and returns a new pointer. <tt>offset</tt> is specified as the number of objects except for unknown complex datatypes in which case it is the number of bytes. For example, is <tt>ptr</tt> is a "<tt>double *</tt>", <tt>ptradd(ptr,1)</tt> will return the next double. On the other hand, if if <tt>ptr</tt> is "<tt>Vector *</tt>", then <tt>ptradd(ptr,1)</tt> will update the pointer by 1 byte.
-<dt><dd>
-</dl>
-<b>ptrmap(type1,type2)</b><p>
-<dl>
-<dt><dd>This performs a "runtime typedef" and makes SWIG recognize pointers of <tt>type1</tt> and <tt>type2</tt> as equivalent. <tt>type1</tt> and <tt>type2</tt> are specified as strings. Not generally needed, but sometimes useful.
-</dl>
-<a name="n16"></a><h3> A simple example</h3>
-Suppose you have the following C function :<p>
-<blockquote><pre>
-void add(double a, double b, double *result) {
- *result = a + b;
-}
-
-</pre></blockquote>
-To manage the result output, we can write an interface file like this :<p>
-<p>
-<blockquote><pre>%module example
-%include pointer.i
-
-extern void add(double a, double b, double *result);
-
-</pre></blockquote>
-Now, let's use the pointer library (shown for a few languages) :<p>
-<blockquote><pre>
-# Tcl
-set result [ptrcreate double] ;# Create a double
-add 4.5 3 $result ;# Call our C function
-puts [ptrvalue $result] ;# Print out the result
-ptrfree $result ;# Destroy the double
-
-# Perl5
-use example;
-package example; # Functions are in example package
-$result = ptrcreate("double"); # Create a double
-add(4.5,3,$result); # Call C function
-print ptrvalue($result),"\n"; # Print the result
-ptrfree($result); # Destroy the double
-
-# Python
-import example
-result = example.ptrcreate("double") # Create a double
-example.add(4.5,3,result) # Call C function
-print example.ptrvalue(result) # Print the result
-example.ptrfree(result) # Destroy the double
-
-</pre></blockquote>
-In this case, the idea is simple--we create a pointer, pass it to our C function, and dereference it to get the result. It's essentially identical to how we would have done it in C (well, minus the function call to dereference the value).<p>
-<a name="n17"></a><h3> Creating arrays</h3>
-Now suppose you have a C function involving arrays :<p>
-<p>
-<blockquote><pre>void addv(double a[], double b[], double c[], int nitems) {
- int i;
- for (i = 0; i < nitems; i++) {
- c[i] = a[i]+b[i];
- }
-}
-
-</pre></blockquote>
-This is also easily handled by our pointer library. For example (in Python) :<p>
-<p>
-<blockquote><pre># Python function to turn a list into an "array"
-def build_array(l):
- nitems = len(l)
- a = ptrcreate("double",0,nitems)
- i = 0
- for item in l:
- ptrset(a,item,i)
- i = i + 1
- return a
-
-# Python function to turn an array into list
-def build_list(a,nitems):
- l = []
- for i in range(0,nitems):
- l.append(ptrvalue(a,i))
- return l
-
-# Now use our functions
-a = listtoarray([0.0,-2.0,3.0,9.0])
-b = build_array([-2.0,3.5,10.0,22.0])
-c = ptrcreate("double",0,4) # For return result
-add(a,b,c,4) # Call our C function
-result = build_list(c) # Build a python list from the result
-print result
-ptrfree(a)
-ptrfree(b)
-ptrfree(c)
-
-</pre></blockquote>
-This example may look quite inefficient on the surface (due to the translation of Python lists to and from C arrays). However, if you're working with lots of C functions, it's possible to simply pass C pointers around between them without any translation. As a result, applications can run fast--even when controlled from a scripting language. It's also worth emphasizing that the <tt>ptrcreate()</tt> function created a real C array that can be interchanged with other arrays. The <tt>ptrvalue()</tt> function can also dereference a C pointer even if it wasn't created from Python. <p>
-<a name="n18"></a><h3> Packing a data structure</h3>
-The pointer library can even be used to pack simple kinds of data-structures, perhaps for sending across a network, or simply for changing the value. For example, suppose you had this data structure:<p>
-<p>
-<blockquote><pre>struct Point {
- double x,y;
- int color;
-};
-
-</pre></blockquote>
-<p>
-You could write a Tcl function to set the fields of the structure as follows :<p>
-<p>
-<blockquote><pre>proc set_point { ptr x y c } {
- set p [ptrcast $ptr "double *"] ;# Make a double *
- ptrset $p $x ;# Set x component
- set p [ptradd $p 1] ;# Update pointer
- ptrset $p $y ;# Set y component
- set p [ptrcast [ptradd $p 1] "int *"] ;# Update pointer and cast
- ptrset $p $c ;# Set color component
-}
-</pre></blockquote>
-<p>
-This function could be used even if you didn't tell SWIG anything about the "Point" structure above. <p>
-<a name="n3"></a><h2> Introduction to typemaps</h2>
-Sometimes it's desirable to change SWIG behavior in some manner. For example, maybe you want to automatically translate C arrays to and from Perl lists. Or perhaps you would like a particular function argument to behave as an output parameter. Typemaps provide a mechanism for doing just this by modifying SWIG's code generator. Typemaps are new to SWIG 1.1, but it should be emphasized that they are not required to build an interface. <p>
-<a name="n19"></a><h3> The idea (in a nutshell)</h3>
-The idea behind typemaps is relatively simple--given the occurrence of a particular C datatype, we want to apply rules for special processing. For example, suppose we have a C function like this :<p>
-<p>
-<blockquote><pre>void add(double a, double b, double *result) {
- *result = a + b;
-}
-</pre></blockquote>
-<p>
-It is clear to us that the result of the function is being returned in the <tt>result</tt> parameter. Unfortunately, SWIG isn't this smart--after all "result" is just like any other pointer. However, with a typemap, we can make SWIG recognize "<tt>double *result</tt>" as a special datatype and change the handling to do exactly what we want.<p>
-<p>
-So, despite being a common topic of discussion on the SWIG mailing list, a typemap is really just a special processing rule that is applied to a particular datatype. Each typemap relies on two essential attributes--a datatype and a name (which is optional). When trying to match parameters, SWIG looks at both attributes. Thus, special processing applied to a parameter of "<tt>double *result</tt>" will not be applied to "<tt>double *input</tt>". On the other hand, special processing defined for a datatype of "<tt>double *</tt>" could be applied to both (since it is more general). <p>
-<a name="n20"></a><h3> Using some typemaps</h3>
-It is easy to start using some typemaps right away. To wrap the above function, simply use the <tt>typemaps.i</tt> library file (which is part of the SWIG library) as follows :<p>
-<p>
-<blockquote><pre>// Simple example using typemaps
-%module example
-%include typemaps.i // Grab the standard typemap library
-
-%apply double *OUTPUT { double *result };
-extern void add(double a, double b, double *result);
-
-</pre></blockquote>
-The <tt>%apply</tt> directive tells SWIG that we are going to apply special processing to a datatype. The "<tt>double *OUTPUT</tt>" is the name of a rule describing how to return an output value from a "<tt>double *</tt>" (this rule is defined in the file <tt>typemaps.i</tt>). The rule gets applied to all of the datatypes listed in curly braces-- in this case "<tt>double *result</tt>".<p>
-<p>
-While it may sound complicated, when you compile the module and use it, you get a function that works as follows :<p>
-<p>
-<blockquote><pre># Perl code to call our add function
-
-$a = add(3,4);
-print $a,"\n";
-7
-
-</pre></blockquote>
-Our function is much easier to use and it is no longer necessary to create a special double * object and pass it to the function. Typemaps took care of this automatically.<p>
-<a name="n4"></a><h2> Managing input and output parameters</h2>
-By default, when SWIG encounters a pointer, it makes no assumptions about what it is (well, other than the fact that it's a pointer). The <tt>typemaps.i</tt> library file contains a variety of methods for changing this behavior. The following methods are available in this file :<p>
-<a name="n21"></a><h3> Input Methods</h3>
-These methods tell SWIG that a pointer is a single input value. When used, functions will expect values instead of pointers.<p>
-<blockquote><pre>
-int *INPUT
-short *INPUT
-long *INPUT
-unsigned int *INPUT
-unsigned short *INPUT
-unsigned long *INPUT
-double *INPUT
-float *INPUT
-</pre></blockquote>
-<p>
-Suppose you had a C function like this :<p>
-<blockquote><pre>
-double add(double *a, double *b) {
- return *a+*b;
-}
-
-</pre></blockquote>
-You could wrap it with SWIG as follows :<p>
-<p>
-<blockquote><pre>%module example
-%include typemaps.i
-...
-extern double add(double *INPUT, double *INPUT);
-
-</pre></blockquote>
-Now, when you use your function ,it will work like this :<p>
-<p>
-<blockquote><pre>% set result [add 3 4]
-% puts $result
-7
-</pre></blockquote>
-<a name="n22"></a><h3> Output Methods</h3>
-These methods tell SWIG that pointer is the output value of a function. When used, you do not need to supply the argument when calling the function, but multiple return values can be returned.<p>
-<p>
-<blockquote><pre>int *OUTPUT
-short *OUTPUT
-long *OUTPUT
-unsigned int *OUTPUT
-unsigned short *OUTPUT
-unsigned long *OUTPUT
-double *OUTPUT
-float *OUTPUT
-
-</pre></blockquote>
-These methods can be used as shown in an earlier example. For example, if you have this C function :<p>
-<p>
-<blockquote><pre>void add(double a, double b, double *c) {
- *c = a+b;
-}
-</pre></blockquote>
-<p>
-A SWIG interface file might look like this :<p>
-<p>
-<blockquote><pre>%module example
-%include typemaps.i
-...
-extern void add(double a, double b, double *OUTPUT);
-
-</pre></blockquote>
-In this case, only a single output value is returned, but this is not a restriction. For example, suppose you had a function like this :<p>
-<p>
-<blockquote><pre>// Returns a status code and double
-int get_double(char *str, double *result);
-
-</pre></blockquote>
-When declared in SWIG as :<p>
-<p>
-<blockquote><pre>int get_double(char *str, double *OUTPUT);
-
-</pre></blockquote>
-The function would return a list of output values as shown for Python below :as follows :<p>
-<p>
-<blockquote><pre>>>> get_double("3.1415926") # Returns both a status and value
-[0, 3.1415926]
->>>
-</pre></blockquote>
-<a name="n23"></a><h3> Input/Output Methods</h3>
-When a pointer serves as both an input and output value you can use the following methods :<p>
-<blockquote><pre>
-int *BOTH
-short *BOTH
-long *BOTH
-unsigned int *BOTH
-unsigned short *BOTH
-unsigned long *BOTH
-double *BOTH
-float *BOTH
-
-</pre></blockquote>
-A typical C function would be as follows :<p>
-<p>
-<blockquote><pre>void negate(double *x) {
- *x = -(*x);
-}
-
-</pre></blockquote>
-To make x function as both and input and output value, declare the function like this in an interface file :<p>
-<p>
-<blockquote><pre>%module example
-%include typemaps.i
-...
-extern void negate(double *BOTH);
-
-</pre></blockquote>
-Now within a script, you can simply call the function normally :<p>
-<p>
-<blockquote><pre>$a = negate(3); # a = -3 after calling this
-
-</pre></blockquote>
-<a name="n24"></a><h3> Using different names</h3>
-By explicitly using the parameter names of INPUT, OUTPUT, and BOTH in your declarations, SWIG performs different operations. If you would like to use different names, you can simply use the <tt>%apply</tt> directive. For example :<p>
-<p>
-<blockquote><pre>// Make double *result an output value
-%apply double *OUTPUT { double *result };
-
-// Make Int32 *in an input value
-%apply int *INPUT { Int32 *in };
-
-// Make long *x both
-%apply long *BOTH {long *x};
-
-</pre></blockquote>
-<tt>%apply</tt> only renames the different type handling rules. You can use it to match up with the naming scheme used in a header file and so forth. To later clear a naming rule, the <tt>%clear</tt> directive can be used :<p>
-<p>
-<blockquote><pre>%clear double *result;
-%clear Int32 *in, long *x;
-</pre></blockquote>
-<a name="n5"></a><h2> Applying constraints to input values</h2>
-In addition to changing the handling of various input values, it is also possible to apply constraints. For example, maybe you want to insure that a value is positive, or that a pointer is non-NULL. This can be accomplished including the <tt>constraints.i</tt> library file (which is also based on typemaps).<p>
-<a name="n25"></a><h3> Simple constraint example</h3>
-The constraints library is best illustrated by the following interface file :<p>
-<p>
-<blockquote><pre>// Interface file with constraints
-%module example
-%include constraints.i
-
-double exp(double x);
-double log(double POSITIVE); // Allow only positive values
-double sqrt(double NONNEGATIVE); // Non-negative values only
-double inv(double NONZERO); // Non-zero values
-
-void free(void *NONNULL); // Non-NULL pointers only
-
-</pre></blockquote>
-The behavior of this file is exactly as you would expect. If any of the arguments violate the constraint condition, a scripting language exception will be raised. As a result, it is possible to catch bad values, prevent mysterious program crashes and so on.<p>
-<a name="n26"></a><h3> Constraint methods</h3>
-The following constraints are currently available<p>
-<blockquote><pre>
-POSITIVE Any number > 0 (not zero)
-NEGATIVE Any number < 0 (not zero)
-NONNEGATIVE Any number >= 0
-NONPOSITIVE Any number <= 0
-NONZERO Nonzero number
-NONNULL Non-NULL pointer (pointers only).
-</pre></blockquote>
-<a name="n27"></a><h3> Applying constraints to new datatypes</h3>
-The constraints library only supports the built-in C datatypes, but it is easy to apply it to new datatypes using <tt>%apply</tt>. For example :<p>
-<p>
-<blockquote><pre>// Apply a constraint to a Real variable
-%apply Number POSITIVE { Real in };
-
-// Apply a constraint to a pointer type
-%apply Pointer NONNULL { Vector * };
-
-</pre></blockquote>
-The special types of "Number" and "Pointer" can be applied to any numeric and pointer variable type respectively. To later remove a constraint, the %clear directive can be used :<p>
-<p>
-<blockquote><pre>%clear Real in;
-%clear Vector *;
-</pre></blockquote>
-<a name="n6"></a><h2> Writing new typemaps</h2>
-So far, we have only seen a high-level picture of typemaps and have utilized pre-existing typemaps in the SWIG library. However, it is possible to do more if you're willing to get your hands dirty and dig into the internals of SWIG and your favorite scripting language.<p>
-<p>
-Before diving in, first ask yourself do I really need to change SWIG's default behavior? The basic pointer model works pretty well most of the time and I encourage you to use it--after all, I wanted SWIG to be easy enough to use so that you didn't need to worry about low level details. If, after contemplating this for awhile, you've decided that you really want to change something, a word of caution is in order. Writing a typemap from scratch usually requires a detailed knowledge of the internal workings of a particular scripting language. It is also quite easy to break all of the output code generated by SWIG if you don't know what you're doing. On the plus side, once a typemap has been written it can be reused over and over again by putting it in the SWIG library (as has already been demonstrated). This section describes the basics of typemaps. Language specific information (which can be quite technical) is contained in the later chapters.<p>
-<a name="n28"></a><h3> Motivations for using typemaps</h3>
-Suppose you have a few C functions such as the following :<p>
-<p>
-<blockquote><pre>void glLightfv(GLenum light, Glenum pname, GLfloat parms[4]);
-
-</pre></blockquote>
-In this case, the third argument takes a 4 element array. If you do nothing, SWIG will convert the last argument into a pointer. When used in the scripting language, you will need to pass a "<tt>GLfloat *</tt>" object to the function to make it work. <p>
-<a name="n29"></a><h3> Managing special data-types with helper functions</h3>
-Helper functions provide one mechanism for dealing with odd datatypes. With a helper function, you provide additional functionality for creating and destroying objects or converting values into a useful form. These functions are usually just placed into your interface file with the rest of the functions. For example, a few helper functions to work with 4 element arrays for the above function, might look like this :<p>
-<p>
-<blockquote><pre>%inline %{
-/* Create a new GLfloat [4] object */
-GLfloat *newfv4(double x, double y, double z, double w) {
- GLfloat *f = (GLfloat *) malloc(4*sizeof(GLfloat));
- f[0] = x;
- f[1] = y;
- f[2] = z;
- f[3] = w;
- return f;
-}
-
-/* Destroy a GLfloat [4] object */
-void delete_fv4(GLfloat *d) {
- free(d);
-}
-%}
-</pre></blockquote>
-<p>
-When wrapped, our helper functions will show up the interface and can be used as follows :<p>
-<p>
-<blockquote><pre>% set light [newfv4 0.0 0.0 0.0 1.0] # Creates a GLfloat *
-% glLightfv GL_LIGHT0 GL_AMBIENT $light # Pass it to the function
-...
-% delete_fv4 $light # Destroy it (When done)
-</pre></blockquote>
-<p>
-<p>
-While not the most elegant approach, helper functions provide a simple mechanism for working with more complex datatypes. In most cases, they can be written without diving into SWIG's internals. Before typemap support was added to SWIG, helper functions were the only method for handling these kinds of problems. The pointer.i library file described earlier is an example of just this sort of approach. As a rule of thumb, I recommend that you try to use this approach before jumping into typemaps. <p>
-<a name="n30"></a><h3> A Typemap Implementation</h3>
-As we have seen, a typemap can often eliminate the need for helper functions. Without diving into the details, a more sophisticated typemap implementation of the previous example can permit you to pass an array or list of values directly into the C function like this :<p>
-<p>
-<blockquote><pre>% glLightfv GL_LIGHT0 GL_AMBIENT {0.0 0.0 0.0 1.0}
-
-</pre></blockquote>
-This is a more natural implementation that replaces the low-level pointer method. Now we will look into how one actually specifies a typemap.<p>
-<a name="n31"></a><h3> What is a typemap?</h3>
-A typemap is specified using the <tt>%typemap</tt> directive in your interface file. A simple typemap might look liks this :<p>
-<p>
-<blockquote><pre>%module example
-%typemap(tcl,in) int {
- $target = atoi($source);
- printf("Received an integer : %d\n", $target);
-}
-
-int add(int a, int b);
-</pre></blockquote>
-<p>
-In this case, we changed the processing of integers as input arguments to functions. When used in a Tcl script, we would get the following debugging information:<p>
-<p>
-<blockquote><pre>% set a [add 7 13]
-Received an integer : 7
-Received an integer : 13
-
-</pre></blockquote>
-In the typemap specification, the symbols <tt>$source</tt> and <tt>$target</tt> are holding places for C variable names that SWIG is going to use when generating wrapper code. In this example, <tt>$source</tt> would contain a Tcl string containing the input value and <tt>$target</tt> would be the C integer value that is going to be passed into the "add" function.<p>
-<a name="n32"></a><h3> Creating a new typemap</h3>
-A new typemap can be created as follows :<p>
-<blockquote><pre>
-%typemap(lang,method) Datatype {
- ... Conversion code ...
-}
-
-</pre></blockquote>
-<tt>lang</tt> specifies the target language, <tt>method</tt> defines a particular conversion method, and <tt>Datatype</tt> gives the corresponding C datatype. The code corresponding to the typemap is enclosed in braces after the declaration. There are about a dozen different kinds of typemaps that are used within SWIG, but we will get to that shortly.<p>
-<p>
-A single conversion can be applied to multiple datatypes by giving a comma separated list of datatypes. For example :<p>
-<p>
-<blockquote><pre>%typemap(tcl,in) int, short, long, signed char {
- $target = ($type) atol($source);
-}
-
-</pre></blockquote>
-Here, <tt>$type</tt> will be expanded into the real datatype during code generation. Datatypes may also carry names as in<p>
-<p>
-<blockquote><pre>%typemap(perl5,in) char **argv {
- ... Turn a perl array into a char ** ...
-}
-
-</pre></blockquote>
-A "named"typemap will only apply to an object that matches both the C datatype and the name. Thus the <tt>char **argv</tt> typemap will only be applied to function arguments that exactly match "<tt>char **argv</tt>". In some cases, the name may correspond to a function name (as is the case for return values).<p>
-<p>
-Finally, there is a shortened form of the typemap directive :<p>
-<p>
-<blockquote><pre>%typemap(method) Datatype {
- ...
-}
-
-</pre></blockquote>
-When the language name is ommitted, the typemap will be applied to the current target language. This form is only recommended for typemap methods that are language independent (there are a few). It is not recommended if you are building interfaces for multiple languages.<p>
-<a name="n33"></a><h3> Deleting a typemap</h3>
-A typemap can be deleted by providing no conversion code. For example :<p>
-<p>
-<blockquote><pre>%typemap(lang,method) Datatype; // Deletes this typemap
-</pre></blockquote>
-<a name="n34"></a><h3> Copying a typemap</h3>
-A typemap can be copied using the following declaration :<p>
-<p>
-<blockquote><pre>%typemap(python,out) unsigned int = int; // Copies a typemap
-
-</pre></blockquote>
-This specifies that the typemap for "<tt>unsigned int</tt>" should be the same as the "<tt>int</tt>" typemap.<p>
-This is most commonly used when working with library files.<p>
-<a name="n35"></a><h3> Typemap matching rules</h3>
-When you specify a typemap, SWIG is going to try and match it with all future occurrences of the datatype you specify. The matching process is based upon the target language, typemap method, datatype, and optional name. Because of this, it is perfectly legal for multiple typemaps to exist for a single datatype at any given time. For example :<p>
-<p>
-<blockquote><pre>%typemap(tcl,in) int * {
- ... Convert an int * ...
-}
-%typemap(tcl,in) int [4] {
- ... Convert an int[4] ...
-}
-%typemap(tcl,in) int out[4] {
- ... Convert an out[4] ...
-}
-%typemap(tcl,in) int *status {
- ... Convert an int *status ...
-}
-
-</pre></blockquote>
-These typemaps all involve the "<tt>int *</tt>" datatype in one way or another, but are all considered to be distinct. There is an extra twist to typemaps regarding the similarity between C pointers and arrays. A typemap applied to a pointer will also work for any array of the same type. On the other hand, a typemap applied to an array will only work for arrays, not pointers. Assuming that you're not completely confused at this point, the following rules are applied in order to match pointers and arrays :<p>
-<p>
-<ul>
-<li>Named arrays
-<li>Unnamed arrays
-<li>Named datatypes
-<li>Unnamed datatypes
-</ul>
-<p>
-The following interface file shows how these rules are applied.<p>
-<p>
-<blockquote><pre>void foo1(int *); // Apply int * typemap
-void foo2(int a[4]); // Apply int[4] typemap
-void foo3(int out[4]); // Apply int out[4] typemap
-void foo4(int *status); // Apply int *status typemap
-void foo5(int a[20]); // Apply int * typemap (because int [20] is an int *)
-
-</pre></blockquote>
-Because SWIG uses a name-based approach, it is possible to attach special properties to named parameters. For example, we can make an argument of "<tt>int *OUTPUT</tt>" always be treated as an output value of a function or make a "<tt>char **argv</tt>" always accept a list of string values.<p>
-<a name="n7"></a><h2> Common typemap methods</h2>
-The following methods are supported by most SWIG language modules. Individual language may provide any number of other methods not listed here.<p>
-<center>
-<img src="ch6.table.1.png"><br>
-<img src="ch6.table.2.png"><br>
-</center>
-<p>
-Understanding how some of these methods are applied takes a little practice and better understanding of what SWIG does when it creates a wrapper function. The next few diagrams show the anatomy of a wrapper function and how the typemaps get applied. More detailed examples of typemaps can be found on the chapters for each target language.<p>
-<p>
-<center><img src="ch6.1.png">
-<p></center>
-<p>
-<center><img src="ch6.2.png">
-<p></center>
-<a name="n8"></a><h2> Writing typemap code</h2>
-The conversion code supplied to a typemap needs to follow a few conventions described here.<p>
-<a name="n36"></a><h3> Scope</h3>
-Typemap code is enclosed in braces when it is inserted into the resulting wrapper code (using C's block-scope). It is perfectly legal to declare local and static variables in a typemap. However, local variables will only exist in the tiny portion of code you supply. In other words, any local variables that you create in a typemap will disappear when the typemap has completed its execution.<p>
-<a name="n37"></a><h3> Creating local variables</h3>
-Sometimes it is necessary to declare a new local variable that exists in the scope of the entire wrapper function. This can be done by specifying a typemap with parameters as follows :<p>
-<p>
-<blockquote><pre>%typemap(tcl,in) int *INPUT(int temp) {
- temp = atoi($source);
- $target = &temp;
-}
-
-</pre></blockquote>
-What happens here is that <tt>temp</tt> becomes a local variable in the scope of the entire wrapper function. When we set it to a value, that values persists for the duration of the wrapper function and gets cleaned up automatically on exit. This is particularly useful when working with pointers and temporary values.<p>
-<p>
-It is perfectly safe to use multiple typemaps involving local variables in the same function. For example, we could declare a function as :<p>
-<p>
-<blockquote><pre>void foo(int *INPUT, int *INPUT, int *INPUT);
-
-</pre></blockquote>
-When this occurs, SWIG will create three different local variables named `temp'. Of course, they don't all end up having the same name---SWIG automatically performs a variable renaming operation if it detects a name-clash like this.<p>
-<p>
-Some typemaps do not recognize local variables (or they may simply not apply). At this time, only the "in", "argout", "default", and "ignore" typemaps use local variables.<p>
-<a name="n38"></a><h3> Special variables</h3>
-The following special variables may be used within a typemap conversion code :<p>
-<center><img src="ch6.table.3.png"></center>
-<p>
-When found in the conversion code, these variables will be replaced with the correct values. Not all values are used in all typemaps. Please refer to the SWIG reference manual for the precise usage. <p>
-<a name="n9"></a><h2> Typemaps for handling arrays</h2>
-One of the most common uses of typemaps is providing some support for arrays. Due to the subtle differences between pointers and arrays in C, array support is somewhat limited unless you provide additional support. For example, consider the following structure appears in an interface file :<p>
-<p>
-<blockquote><pre>struct Person {
- char name[32];
- char address[64];
- int id;
-};
-
-</pre></blockquote>
-When SWIG is run, you will get the following warnings :<p>
-<p>
-<blockquote><pre>swig -python example.i
-Generating wrappers for Python
-example.i : Line 2. Warning. Array member will be read-only.
-example.i : Line 3. Warning. Array member will be read-only.
-</pre></blockquote>
-<p>
-These warning messages indicate that SWIG does not know how you want to set the name and address fields. As a result, you will only be able to query their value.<p>
-<p>
-To fix this, we could supply two typemaps in the file such as the following :<p>
-<blockquote><pre>
-
-%typemap(memberin) char [32] {
- strncpy($target,$source,32);
-}
-%typemap(memberin) char [64] {
- strncpy($target,$source,64);
-}
-
-</pre></blockquote>
-The "memberin" typemap is used to set members of structures and classes. When you run the new version through SWIG, the warnings will go away and you can now set each member. It is important to note that <tt>char[32]</tt> and <tt>char[64]</tt> are different datatypes as far as SWIG typemaps are concerned. However, both typemaps can be combined as follows :<p>
-<p>
-<blockquote><pre>// A better typemap for char arrays
-%typemap(memberin) char [ANY] {
- strncpy($target,$source,$dim0);
-}
-
-</pre></blockquote>
-The <tt>ANY</tt> keyword can be used in a typemap to match any array dimension. When used, the special variable <tt>$dim0</tt> will contain the real dimension of the array and can be used as shown above.<p>
-<p>
-Multidimensional arrays can also be handled by typemaps. For example :<p>
-<p>
-<blockquote><pre>// A typemap for handling any int [][] array
-%typemap(memberin) int [ANY][ANY] {
- int i,j;
- for (i = 0; i < $dim0; i++)
- for (j = 0; j < $dim1; j++) {
- $target[i][j] = *($source+$dim1*i+j);
- }
-}
-
-</pre></blockquote>
-When multi-dimensional arrays are used, the symbols <tt>$dim0,</tt> <tt>$dim1</tt>,<tt> $dim2</tt>, etc... get replaced by the actual array dimensions being used. <p>
-<p>
-The ANY keyword can be combined with any specific dimension. For example :<p>
-<p>
-<blockquote><pre>%typemap(python,in) int [ANY][4] {
- ...
-}
-</pre></blockquote>
-A typemap using a specific dimension always has precedence over a more general version. For example, <tt>[ANY][4]</tt> will be used before<tt>[ANY][ANY]</tt>.<p>
-<a name="n10"></a><h2> Typemaps and the SWIG Library</h2>
-Writing typemaps is a tricky business. For this reason, many common typemaps can be placed into a SWIG library file and reused in other modules without having to worry about nasty underlying details. To do this, you first write a file containing typemaps such as this :<p>
-<p>
-<blockquote><pre>// file : stdmap.i
-// A file containing a variety of useful typemaps
-
-%typemap(tcl,in) int INTEGER {
- ...
-}
-%typemap(tcl,in) double DOUBLE {
- ...
-}
-%typemap(tcl,out) int INT {
- ...
-}
-%typemap(tcl,out) double DOUBLE {
- ...
-}
-%typemap(tcl,argout) double DOUBLE {
- ...
-}
-// and so on...
-
-</pre></blockquote>
-This file may contain dozens or even hundreds of possible mappings. Now, to use this file with other modules, simply include it in other files and use the <tt>%apply</tt> directive :<p>
-<p>
-<blockquote><pre>// interface.i
-// My interface file
-
-%include stdmap.i // Load the typemap library
-
-// Now grab the typemaps we want to use
-%apply double DOUBLE {double};
-
-// Rest of your declarations
-</pre></blockquote>
-<p>
-In this case, <tt>stdmap.i</tt> contains a variety of standard mappings. The <tt>%apply</tt> directive lets us apply specific versions of these to new datatypes without knowing the underlying implementation details.<p>
-<p>
-To clear a typemap that has been applied, you can use the <tt>%clear</tt> directive. For example :<p>
-<p>
-<blockquote><pre>%clear double x; // Clears any typemaps being applied to double x
-</pre></blockquote>
-<a name="n11"></a><h2> Implementing constraints with typemaps</h2>
-One particularly interesting application of typemaps is the implementation of argument constraints. This can be done with the "check" typemap. When used, this allows you to provide code for checking the values of function arguments. For example :<p>
-<p>
-<blockquote><pre>%module math
-
-%typemap(perl5,check) double *posdouble {
- if ($target < 0) {
- croak("Expecting a positive number");
- }
-}
-
-...
-double sqrt(double posdouble);
-
-</pre></blockquote>
-This provides a sanity check to your wrapper function. If a negative number is passed to this function, a Perl exception will be raised and your program terminated with an error message.<p>
-<p>
-This kind of checking can be particularly useful when working with pointers. For example :<p>
-<p>
-<blockquote><pre>%typemap(python,check) Vector * {
- if ($target == 0) {
- PyErr_SetString(PyExc_TypeError,"NULL Pointer not allowed");
- return NULL;
- }
-}
-
-</pre></blockquote>
-will prevent any function involving a <tt>Vector *</tt> from accepting a NULL pointer. As a result, SWIG can often prevent a potential segmentation faults or other run-time problems by raising an exception rather than blindly passing values to the underlying C/C++ program.<p>
-<a name="n12"></a><h2> Typemap examples</h2>
-Typemaps are inherently language dependent so more examples appear in later chapters. The SWIG<tt> Examples </tt>directory also includes a variety of examples. Sophisticated users may gain more by examining the <tt>typemaps.i</tt> and <tt>constraints.i </tt>SWIG library files.<p>
-<a name="n13"></a><h2> How to break everything with a typemap</h2>
-It should be emphasized that typemaps provide a direct mechanism for modifying SWIG's output. As a result, it can be very easy to break almost everything if you don't know what you're doing. For this reason, it should be stressed that typemaps are not required in order to use SWIG with most kinds of applications. Power users, however, will probably find typemaps to be a useful tool for creating extremely powerful scripting language extensions. <p>
-<a name="n14"></a><h2> Typemaps and the future</h2>
-The current typemap mechanism, while new, will probably form the basis of SWIG 2.0. Rather than having code buried away inside a C++ module, it may soon be possible to redefine almost all of SWIG's code generation on the fly. Future language modules will rely upon typemaps almost exclusively. <p>
-<p>
-
-<p><hr>
-
-<address>SWIG 1.1 - Last Modified : Mon Aug 4 10:46:56 1997</address>
-</body>
-</html>
diff --git a/swigweb/Doc1.1/HTML/ch1.1.png b/swigweb/Doc1.1/HTML/ch1.1.png
deleted file mode 100644
index 70705c8..0000000
--- a/swigweb/Doc1.1/HTML/ch1.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch1.2.png b/swigweb/Doc1.1/HTML/ch1.2.png
deleted file mode 100644
index ad97299..0000000
--- a/swigweb/Doc1.1/HTML/ch1.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.1.png b/swigweb/Doc1.1/HTML/ch10.1.png
deleted file mode 100644
index edfde09..0000000
--- a/swigweb/Doc1.1/HTML/ch10.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.1.png b/swigweb/Doc1.1/HTML/ch10.table.1.png
deleted file mode 100644
index 8495fdf..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.10.png b/swigweb/Doc1.1/HTML/ch10.table.10.png
deleted file mode 100644
index 8c12802..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.10.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.11.png b/swigweb/Doc1.1/HTML/ch10.table.11.png
deleted file mode 100644
index 2849d8e..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.11.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.12.png b/swigweb/Doc1.1/HTML/ch10.table.12.png
deleted file mode 100644
index 9080290..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.12.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.2.png b/swigweb/Doc1.1/HTML/ch10.table.2.png
deleted file mode 100644
index 2e6b904..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.3.png b/swigweb/Doc1.1/HTML/ch10.table.3.png
deleted file mode 100644
index afac75d..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.4.png b/swigweb/Doc1.1/HTML/ch10.table.4.png
deleted file mode 100644
index 41537e4..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.4.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.5.png b/swigweb/Doc1.1/HTML/ch10.table.5.png
deleted file mode 100644
index 4f83fba..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.5.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.6.png b/swigweb/Doc1.1/HTML/ch10.table.6.png
deleted file mode 100644
index feac182..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.6.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.7.png b/swigweb/Doc1.1/HTML/ch10.table.7.png
deleted file mode 100644
index e3e93d1..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.7.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.8.png b/swigweb/Doc1.1/HTML/ch10.table.8.png
deleted file mode 100644
index b6e845d..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.8.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch10.table.9.png b/swigweb/Doc1.1/HTML/ch10.table.9.png
deleted file mode 100644
index 2f82556..0000000
--- a/swigweb/Doc1.1/HTML/ch10.table.9.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch11.1.png b/swigweb/Doc1.1/HTML/ch11.1.png
deleted file mode 100644
index 2cc2bec..0000000
--- a/swigweb/Doc1.1/HTML/ch11.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch11.2.png b/swigweb/Doc1.1/HTML/ch11.2.png
deleted file mode 100644
index e6d1b55..0000000
--- a/swigweb/Doc1.1/HTML/ch11.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch11.3.png b/swigweb/Doc1.1/HTML/ch11.3.png
deleted file mode 100644
index 54ee724..0000000
--- a/swigweb/Doc1.1/HTML/ch11.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch12.1.png b/swigweb/Doc1.1/HTML/ch12.1.png
deleted file mode 100644
index 2072f06..0000000
--- a/swigweb/Doc1.1/HTML/ch12.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch2.1.png b/swigweb/Doc1.1/HTML/ch2.1.png
deleted file mode 100644
index 1f5800e..0000000
--- a/swigweb/Doc1.1/HTML/ch2.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch2.2.png b/swigweb/Doc1.1/HTML/ch2.2.png
deleted file mode 100644
index 4c340df..0000000
--- a/swigweb/Doc1.1/HTML/ch2.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch3.1.png b/swigweb/Doc1.1/HTML/ch3.1.png
deleted file mode 100644
index fe08d6a..0000000
--- a/swigweb/Doc1.1/HTML/ch3.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch5.1.png b/swigweb/Doc1.1/HTML/ch5.1.png
deleted file mode 100644
index 2b233cb..0000000
--- a/swigweb/Doc1.1/HTML/ch5.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch5.2.png b/swigweb/Doc1.1/HTML/ch5.2.png
deleted file mode 100644
index ac95aa9..0000000
--- a/swigweb/Doc1.1/HTML/ch5.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch5.3.png b/swigweb/Doc1.1/HTML/ch5.3.png
deleted file mode 100644
index 67eaa59..0000000
--- a/swigweb/Doc1.1/HTML/ch5.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch6.1.png b/swigweb/Doc1.1/HTML/ch6.1.png
deleted file mode 100644
index 30b0fae..0000000
--- a/swigweb/Doc1.1/HTML/ch6.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch6.2.png b/swigweb/Doc1.1/HTML/ch6.2.png
deleted file mode 100644
index 01d27d7..0000000
--- a/swigweb/Doc1.1/HTML/ch6.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch6.table.1.png b/swigweb/Doc1.1/HTML/ch6.table.1.png
deleted file mode 100644
index de8905f..0000000
--- a/swigweb/Doc1.1/HTML/ch6.table.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch6.table.2.png b/swigweb/Doc1.1/HTML/ch6.table.2.png
deleted file mode 100644
index 2f4e002..0000000
--- a/swigweb/Doc1.1/HTML/ch6.table.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch6.table.3.png b/swigweb/Doc1.1/HTML/ch6.table.3.png
deleted file mode 100644
index f5083c3..0000000
--- a/swigweb/Doc1.1/HTML/ch6.table.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.1.png b/swigweb/Doc1.1/HTML/ch8.1.png
deleted file mode 100644
index fd2f8e7..0000000
--- a/swigweb/Doc1.1/HTML/ch8.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.2.png b/swigweb/Doc1.1/HTML/ch8.2.png
deleted file mode 100644
index 46bcf55..0000000
--- a/swigweb/Doc1.1/HTML/ch8.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.3.png b/swigweb/Doc1.1/HTML/ch8.3.png
deleted file mode 100644
index 96eac3e..0000000
--- a/swigweb/Doc1.1/HTML/ch8.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.1.png b/swigweb/Doc1.1/HTML/ch8.table.1.png
deleted file mode 100644
index 5493504..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.2.png b/swigweb/Doc1.1/HTML/ch8.table.2.png
deleted file mode 100644
index 84f1fc8..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.3.png b/swigweb/Doc1.1/HTML/ch8.table.3.png
deleted file mode 100644
index 3194983..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.4.png b/swigweb/Doc1.1/HTML/ch8.table.4.png
deleted file mode 100644
index 626e3d9..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.4.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.5.png b/swigweb/Doc1.1/HTML/ch8.table.5.png
deleted file mode 100644
index 03cb80f..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.5.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.6.png b/swigweb/Doc1.1/HTML/ch8.table.6.png
deleted file mode 100644
index ab23503..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.6.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch8.table.7.png b/swigweb/Doc1.1/HTML/ch8.table.7.png
deleted file mode 100644
index 787efe8..0000000
--- a/swigweb/Doc1.1/HTML/ch8.table.7.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.1.png b/swigweb/Doc1.1/HTML/ch9.1.png
deleted file mode 100644
index b6ccca2..0000000
--- a/swigweb/Doc1.1/HTML/ch9.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.2.png b/swigweb/Doc1.1/HTML/ch9.2.png
deleted file mode 100644
index c55b7d9..0000000
--- a/swigweb/Doc1.1/HTML/ch9.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.3.png b/swigweb/Doc1.1/HTML/ch9.3.png
deleted file mode 100644
index e600293..0000000
--- a/swigweb/Doc1.1/HTML/ch9.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.1.png b/swigweb/Doc1.1/HTML/ch9.table.1.png
deleted file mode 100644
index e7e2d87..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.1.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.10.png b/swigweb/Doc1.1/HTML/ch9.table.10.png
deleted file mode 100644
index 9257773..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.10.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.2.png b/swigweb/Doc1.1/HTML/ch9.table.2.png
deleted file mode 100644
index ac6647e..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.3.png b/swigweb/Doc1.1/HTML/ch9.table.3.png
deleted file mode 100644
index 0992c6e..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.3.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.4.png b/swigweb/Doc1.1/HTML/ch9.table.4.png
deleted file mode 100644
index b9f910a..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.4.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.5.png b/swigweb/Doc1.1/HTML/ch9.table.5.png
deleted file mode 100644
index 4e56e53..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.5.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.6.png b/swigweb/Doc1.1/HTML/ch9.table.6.png
deleted file mode 100644
index bff037c..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.6.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.7.png b/swigweb/Doc1.1/HTML/ch9.table.7.png
deleted file mode 100644
index 533ea69..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.7.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.8.png b/swigweb/Doc1.1/HTML/ch9.table.8.png
deleted file mode 100644
index b794fa6..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.8.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/HTML/ch9.table.9.png b/swigweb/Doc1.1/HTML/ch9.table.9.png
deleted file mode 100644
index 55b0e50..0000000
--- a/swigweb/Doc1.1/HTML/ch9.table.9.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Advanced.pdf b/swigweb/Doc1.1/PDF/Advanced.pdf
deleted file mode 100644
index 2deb099..0000000
--- a/swigweb/Doc1.1/PDF/Advanced.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Contents.pdf b/swigweb/Doc1.1/PDF/Contents.pdf
deleted file mode 100644
index 937bc28..0000000
--- a/swigweb/Doc1.1/PDF/Contents.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Documentation.pdf b/swigweb/Doc1.1/PDF/Documentation.pdf
deleted file mode 100644
index 16a5ad6..0000000
--- a/swigweb/Doc1.1/PDF/Documentation.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Exceptions.pdf b/swigweb/Doc1.1/PDF/Exceptions.pdf
deleted file mode 100644
index 66d6665..0000000
--- a/swigweb/Doc1.1/PDF/Exceptions.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Extending.pdf b/swigweb/Doc1.1/PDF/Extending.pdf
deleted file mode 100644
index f433b05..0000000
--- a/swigweb/Doc1.1/PDF/Extending.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Index.pdf b/swigweb/Doc1.1/PDF/Index.pdf
deleted file mode 100644
index 2312436..0000000
--- a/swigweb/Doc1.1/PDF/Index.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Introduction.pdf b/swigweb/Doc1.1/PDF/Introduction.pdf
deleted file mode 100644
index cc4a73d..0000000
--- a/swigweb/Doc1.1/PDF/Introduction.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Library.pdf b/swigweb/Doc1.1/PDF/Library.pdf
deleted file mode 100644
index 72430e8..0000000
--- a/swigweb/Doc1.1/PDF/Library.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Perl5.pdf b/swigweb/Doc1.1/PDF/Perl5.pdf
deleted file mode 100644
index 7f46658..0000000
--- a/swigweb/Doc1.1/PDF/Perl5.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Preface.pdf b/swigweb/Doc1.1/PDF/Preface.pdf
deleted file mode 100644
index 28f69d0..0000000
--- a/swigweb/Doc1.1/PDF/Preface.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Python.pdf b/swigweb/Doc1.1/PDF/Python.pdf
deleted file mode 100644
index 2f0fa62..0000000
--- a/swigweb/Doc1.1/PDF/Python.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Reference.pdf b/swigweb/Doc1.1/PDF/Reference.pdf
deleted file mode 100644
index 5f8df74..0000000
--- a/swigweb/Doc1.1/PDF/Reference.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/SWIG.pdf b/swigweb/Doc1.1/PDF/SWIG.pdf
deleted file mode 100644
index f6699b2..0000000
--- a/swigweb/Doc1.1/PDF/SWIG.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/SWIGManual.pdf b/swigweb/Doc1.1/PDF/SWIGManual.pdf
deleted file mode 100644
index 4d3e778..0000000
--- a/swigweb/Doc1.1/PDF/SWIGManual.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Scripting.pdf b/swigweb/Doc1.1/PDF/Scripting.pdf
deleted file mode 100644
index 535a66e..0000000
--- a/swigweb/Doc1.1/PDF/Scripting.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Tcl.pdf b/swigweb/Doc1.1/PDF/Tcl.pdf
deleted file mode 100644
index 6d93906..0000000
--- a/swigweb/Doc1.1/PDF/Tcl.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Title.pdf b/swigweb/Doc1.1/PDF/Title.pdf
deleted file mode 100644
index df33473..0000000
--- a/swigweb/Doc1.1/PDF/Title.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/Doc1.1/PDF/Typemaps.pdf b/swigweb/Doc1.1/PDF/Typemaps.pdf
deleted file mode 100644
index ecfc285..0000000
--- a/swigweb/Doc1.1/PDF/Typemaps.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/INSTALL b/swigweb/INSTALL
deleted file mode 100644
index d578913..0000000
--- a/swigweb/INSTALL
+++ /dev/null
@@ -1,217 +0,0 @@
-Installation: SWIG 1.1
-June 24, 1997
-
-Installation (Unix)
--------------------
-
-To compile and use SWIG, you will need the following on your machine:
-
- A C++ compiler (ie. g++)
- An ANSI C compiler (ie. gcc)
- yacc or bison (only needed to rebuild the SWIG parser).
-
-To compile and install SWIG, type the following :
-
- ./configure
- make
- make install
-
-The configuration script will attempt to locate various packages on
-your machine, including Tcl, Perl5, and Python. Don't panic if
-you get 'not found' messages--SWIG does not need these packages
-to compile or run. The configure script is actually looking for
-these packages so that you can try out the SWIG examples contained
-in the 'Examples' directory. See the Examples section below for
-more details.
-
-The 'make runtime' option is an optional step that can be used to
-build the SWIG runtime libraries. These libraries are only used with
-larger packages and are not necessary for learning SWIG or trying
-the examples (please refer to the "Advanced topics" section of the
-SWIG Users manual for more details).
-
-Typing 'make test' will run a rather extensive series of tests
-and can be run before running 'make install' (if you are paranoid).
-
-There are a number of configuration options that you can give to
-'configure' :
-
- --prefix=/usr/local
-
- Set the installation prefix. SWIG installs into
- /usr/local by default.
-
- --exec_prefix=/usr/local
-
- Set the prefix used to install platform specific
- files (binaries and libraries). Use this if the
- location is different than that given with --prefix.
-
- --with-lang={TCL,TCL8,PYTHON,PERL5,PERL4,GUILE}
-
- This lets you choose the default SWIG target language.
- By default, SWIG chooses TCL, but you can select
- another as shown :
-
- ./configure --with-lang=PYTHON
-
- --with-doc={ASCII,LATEX,HTML,NODOC}
-
- This lets you choose the default SWIG documentation
- method. By default, SWIG chooses ASCII.
-
-To test the SWIG parser after compilation, type 'make test'.
-
-Site specific installation
---------------------------
-
-While not required for compiling SWIG, the configuration script looks
-for various packages in order to create a makefile for compiling the
-examples. This makefile is also installed with the SWIG package.
-The following configuration options can be used to set the location
-of various packages.
-
---with-tcl=pathname - Set root directory of Tcl installation.
- SWIG will use $pathname/include and
- $pathname/lib.
-
---with-tclincl=pathname - Set exact location of Tcl include files
-
---with-tcllib=pathname - Set exact location of Tcl library files
-
---with-itcl=pathname - Same as above but for [incr Tcl]
-
---with-itclincl=pathname - Location of [incr Tcl] include files
-
---with-itcllib=pathname - Location of [incr Tcl] libraries
-
---with-py=pathname - Set package location of Python. This is usually
- something like /usr/local. configure will attempt
- to locate the appropriate include and library files.
-
---with-pyincl=pathname - Set location of Python include files
- (for example, /usr/local/include)
-
---with-pylib=pathname - Set location of Python library files
- (for example, /usr/local/lib)
-
---with-perl5=executable - Specify your perl5 executable. SWIG will figure
- out where files are by running this version of
- Perl and grabbing its configuration data.
-
-
-Other options :
-
---without-yacc - Try to compile SWIG using a pregenerated YACC
- file generated by Berkeley YACC (byacc). Only recommended
- if you get compiler errors when trying to compile parser.y
- or parser.cxx.
-
-
-How to use a different C++ compiler (IMPORTANT)
-------------------------------------------------
-Normally, the configure script will probably use g++ as the
-C++ compiler. If you want to use a different compiler, do
-the following before running configure.
-
- setenv CXX CC # Set CXX to your C++ compiler
- ./configure
- make
-
-Changing the Makefiles to use a different C++ compiler after
-configuration is not recommended! If you need to do this,
-do this :
-
- rm config.cache
- setenv CXX CC
- ./configure
- make
-
-To change the C compiler (for compiling examples), follow the
-same procedure above, change the symbol 'CC' instead of 'CXX'.
-
-Testing :
----------
-
-There are several tests that can be done after compilation :
-
-make test - Tests the SWIG parser and performs regression tests
-make testbuild - Tests SWIG ability to build various modules
- (see below)
-
-make testall - Test both of the above
-
-The testing process requires the use of the 'bash' shell and Perl.
-If you don't have these, don't expect the tests to work.
-
-*** Warning : Full testing requires about 20 Mbytes of disk space
-and creates a collection of regression testing files. After
-performing the tests, you can do a 'make testclean' to clean up
-the test directories to their initial distribution state.
-
-The SWIG Makefiles
-------------------
-
-SWIG creates a Makefile with rules on how to build all kinds of
-modules for different languages. This makefile is called
-'Makefile.template' in the top level directory and is installed with
-the SWIG library as 'swig_lib/Makefile'.
-
-Prior to installation, it is highly recommended that you run a
-'make testbuild' to test this Makefile. This test will report
-which kinds of extensions can be built. It is normal that
-some tests will fail (depending on your system and installation),
-but if the tests fail for a language you want to use, you will
-want to edit the file 'Makefile.template' by hand. In this
-process, you can repeatedly try 'make testbuild' until you
-are satisfied.
-
-In addition to the 'Makefile.template' SWIG 1.1 attempts to configure
-more advanced makefiles for each scripting language. These are
-located in 'swig_lib/tcl/Makefile', 'swig_lib/perl5/Makefile', and
-'swig_lib/python/Makefile'. Prior to installation, you may want
-to examine these Makefiles to make sure they accurately reflect
-your local setup.
-
-If you're happy with the setup, proceed to installation.
-
-Installation
-------------
-
-Type 'make install' to install SWIG. This will install the following :
-
- - The SWIG Library (containing interface files)
- - swig.h (Headers for building SWIG extensions)
- - libswig.a (SWIG library for building SWIG extensions)
- - swig.1 (man page)
- - swig_lib/Makefile Makefile for building extensions
- - Runtime libraries (if built earlier).
-
-Troubleshooting
---------------
-
-See the file TROUBLESHOOTING for solutions to several problems.
-
-While I have access to a large number of machines, it's impossible for
-me to test everything. If you can't get SWIG to build successfully,
-please send me email at beazley@cs.utah.edu.
-
-
-Installation for Windows 95 and NT
-----------------------------------
-
-The Win directory contains makefiles for Microsoft Visual C++ 4.x.
-See the README file in the Win directory for specific build
-instructions.
-
-Installation for Macintosh
---------------------------
-
-The Mac directory contains information about building SWIG on
-the Macintosh. At this time, the Macintosh version is
-distributed separately as a binary release. Source is also
-available, but is non-trivial to build due to dependencies
-on other packages.
-
-
-
diff --git a/swigweb/Makefile b/swigweb/Makefile
deleted file mode 100644
index 516d3b8..0000000
--- a/swigweb/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-# Simple makefile to create the web pages and update/synchronise to the real web server
-
-USERNAME=wsfulton
-
-all: makeweb rsync
-
-makeweb:
- python makeweb.py
-
-rsync:
- rsync -r --cvs-exclude --rsh="ssh" . $(USERNAME)@shell.sf.net:/home/groups/s/sw/swig/swigweb
-
diff --git a/swigweb/article_cpp.ht b/swigweb/article_cpp.ht
deleted file mode 100644
index 11ff34b..0000000
--- a/swigweb/article_cpp.ht
+++ /dev/null
@@ -1,275 +0,0 @@
-Thoughts on the Insanity C++ Parsing
-
-<h2>Thoughts on the Insanity of C++ Parsing</h2>
-
-<center>
-<em>
-"Parsing C++ is simply too complex to do correctly." -- Anonymous
-</em>
-</center>
-<p>
-Author: David Beazley (beazley@cs.uchicago.edu)
-
-<p>
-August 12, 2002
-
-<p>
-A central goal of the SWIG project is to generate extension modules by
-parsing the contents of C++ header files. It's not too hard to come up
-with reasons why this might be useful---after all, if you've got
-several hundred class definitions, do you really want to go off and
-write a bunch of hand-crafted wrappers? No, of course not---you're
-busy and like everyone else, you've got better things to do with
-your time.
-
-<p>
-Okay, so there are many reasons why parsing C++ would be nice.
-However, parsing C++ is also a nightmare. In fact, C++ would
-probably the last language that any normal person would choose to
-serve as an interface specification language. It's hard to parse,
-hard to analyze, and it involves all sorts
-of nasty little problems related to scoping, typenames, templates,
-access, and so forth. Because of this, most of the tools that claim
-to "parse" C++ don't. Instead, they parse a subset of the language
-that happens to match the C++ programming style used by the tool's
-creator (believe me, I know---this is how SWIG started). Not
-surprisingly, these tools tend to break down when presented with code
-that starts to challenge the capabilities of the C++ compiler.
-Needless to say, critics see this as opportunity to make bold claims
-such as "writing a C++ parser is folly" or "this whole approach is too
-hard to ever work correctly."
-
-<p>
-Well, one does have to give the critics a little credit---writing a
-C++ parser certainly <em>is</em> hard and writing a parser that
-actually works correctly is even harder. However, these tasks are
-certainly not "impossible." After all, there would be no working C++
-compiler if such claims were true! Therefore, the question of whether
-or not a wrapper generator can parse C++ is clearly the wrong question
-to ask. Instead, the real question is whether or not a wrapper
-generation tool that parses C++ can actually do anything useful.
-
-<h3>The problem with using C++ as an interface definition language</h3>
-
-If you cut through all of the low-level details of parsing, the primary
-problem of using C++ as an module specification language is that of
-ambiguity. Consider a declaration like this:
-
-<blockquote>
-<pre>
-void foo(double *x, int n);
-</pre>
-</blockquote>
-
-If you look at this declaration, you can ask yourself the question,
-what is "x"? Is it a single input value? Is it an output value
-(modified by the function)? Is it an array? Is "n" somehow related?
-Perhaps the real problem in this example is that of expressing the
-programmer's intent. Yes, the function clearly accepts a pointer to
-some object and an integer, but the declaration does not contain
-enough additional information to determine the purpose of these
-parameters--information that could be useful in generating a suitable
-set of a wrappers.
-
-<p>
-IDL compilers associated with popular component frameworks (e.g.,
-CORBA, COM, etc.) get around this problem by requiring interfaces to
-be precisely specified--input and output values are clearly indicated
-as such. Thus, one might adopt a similar approach and extend C++
-syntax with some special modifiers or qualifiers. For example:
-
-<blockquote>
-<pre>
-void foo(%output double *x, int n);
-</pre>
-</blockquote>
-
-The problem with this approach is that it breaks from C++ syntax and
-it requires the user to annotate their input files (a task that C++
-wrapper generators are supposed to eliminate). Meanwhile, critics sit
-back and say "Ha! I told you C++ parsing would never work."
-
-<p>
-Another problem with using C++ as an input language is that interface
-building often involves more than just blindly wrapping declarations. For instance,
-users might want to rename declarations, specify exception handling procedures,
-add customized code, and so forth. This suggests that a
-wrapper generator really needs to do
-more than just parse C++---it must give users the freedom to customize
-various aspects of the wrapper generation process. Again, things aren't
-looking too good for C++.
-
-<h3>The SWIG approach: pattern matching</h3>
-
-SWIG takes a different approach to the C++ wrapping problem.
-Instead of trying to modify C++ with all sorts of little modifiers and
-add-ons, wrapping is largely controlled by a pattern matching mechanism that is
-built into the underlying C++ type system.
-
-<p>
-One part of the pattern matcher is programmed to look for specific sequences of
-datatypes and argument names. These patterns, known as typemaps, are
-responsible for all aspects of data conversion. They work by simply attaching
-bits of C conversion code to specific datatypes and argument names in the
-input file. For example, a typemap might be used like this:
-
-<blockquote>
-<pre>
-%typemap(in) <b>double *items</b> {
- // Get an array from the input
- ...
-}
-...
-void foo(<b>double *items</b>, int n);
-</pre>
-</blockquote>
-
-With this approach, type and argument names are used as
-a basis for specifying customized wrapping behavior. For example, if a program
-always used an argument of <tt>double *items</tt> to refer to an
-array, SWIG can latch onto that and use it to provide customized
-processing. It is even possible to write pattern matching rules for
-sequences of arguments. For example, you could write the following:
-
-<blockquote>
-<pre>
-%typemap(in) (<b>double *items, int n</b>) {
- // Get an array of items. Set n to number of items
- ...
-}
-...
-void foo(<b>double *items, int n</b>);
-</pre>
-</blockquote>
-
-The precise details of typemaps are not so important (in fact, most of
-this pattern matching is hidden from SWIG users). What is important
-is that pattern matching allows customized data handling to be
-specified without breaking C++ syntax--instead, a user merely has to
-define a few patterns that get applied across the declarations that
-appear in C++ header files. In some sense, you might view this
-approach as providing customization through naming conventions rather than
-having to annotate arguments with extra qualifiers.
-
-<p>
-The other pattern matching mechanism used by SWIG is a declaration annotator
-that is used to attach properties to specific declarations. A simple example of declaration
-annotation might be renaming. For example:
-
-<blockquote>
-<pre>
-%rename(cprint) print; // Rename all occurrences of 'print' to 'cprint'
-</pre>
-</blockquote>
-
-A more advanced form of declaration matching would be exception handling.
-For example:
-
-<blockquote>
-<pre>
-%exception Foo::getitem(int) {
- try {
- $action
- } catch (std::out_of_range& e) {
- SWIG_exception(SWIG_IndexError,const_cast<char*>(e.what()));
- }
-}
-
-...
-template<class T> class Foo {
-public:
- ...
- T &getitem(int index); // Exception handling code attached
- ...
-};
-</pre>
-</blockquote>
-
-Like typemaps, declaration matching does not break from C++ syntax.
-Instead, a user merely specifies special processing rules in advance.
-These rules are then attached to any matching C++
-declaration that appears later in the input. This means that raw C++
-header files can often be parsed and customized with few, if any,
-modifications.
-
-<h3>The SWIG difference</h3>
-
-Pattern based approaches to wrapper code generation are not unique to SWIG.
-However, most prior efforts have based their pattern matching engines on simple
-regular-expression matching. The key difference between SWIG and these systems
-is that SWIG's customization features are fully integrated into the
-underlying C++ type system. This means that SWIG is able to deal with very
-complicated types of C/C++ code---especially code that makes heavy use of
-<tt>typedef</tt>, namespaces, aliases, class hierarchies, and more. To
-illustrate, consider some code like this:
-
-<blockquote>
-<pre>
-// A simple SWIG typemap
-%typemap(in) int {
- $1 = PyInt_AsLong($input);
-}
-
-...
-// Some raw C++ code (included later)
-namespace X {
- typedef int Integer;
-
- class _FooImpl {
- public:
- typedef Integer value_type;
- };
- typedef _FooImpl Foo;
-}
-
-namespace Y = X;
-using Y::Foo;
-
-class Bar : public Foo {
-};
-
-void spam(Bar::value_type x);
-</pre>
-</blockquote>
-
-If you trace your way through this example, you will find that the
-<tt>Bar::value_type</tt> argument to function <tt>spam()</tt> is
-really an integer. What's more, if you take a close look at the SWIG
-generated wrappers, you will find that the typemap pattern defined for
-<tt>int</tt> is applied to it--in other words, SWIG does exactly the right thing despite
-our efforts to make the code confusing.
-
-<p>
-Similarly, declaration annotation is integrated into the type system
-and can be used to define properties that span inheritance hierarchies
-and more (in fact, there are many similarities between the operation of
-SWIG and tools developed for Aspect Oriented Programming).
-
-<h3>What does this mean?</h3>
-
-Pattern-based approaches allow wrapper generation tools to parse C++
-declarations and to provide a wide variety of high-level customization
-features. Although this approach is quite different than that found
-in a typical IDL, the use of patterns makes it possible to work from
-existing header files without having to make many (if any) changes to
-those files. Moreover, when the underlying pattern matching mechanism
-is integrated with the C++ type system, it is possible to build
-reliable wrappers to real software---even if that software is filled
-with namespaces, templates, classes, <tt>typedef</tt> declarations,
-pointers, and other bits of nastiness.
-
-<h3>The bottom line</h3>
-
-Not only is it possible to generate extension modules by parsing C++,
-it is possible to do so with real software and with a high degree of
-reliability. Don't believe me? Download SWIG-1.3.14 and try it for
-yourself.
-
-
-
-
-
-
-
-
-
diff --git a/swigweb/blank.jpg b/swigweb/blank.jpg
deleted file mode 100644
index 3784c9f..0000000
--- a/swigweb/blank.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/bugs.ht b/swigweb/bugs.ht
deleted file mode 100644
index 44af4f4..0000000
--- a/swigweb/bugs.ht
+++ /dev/null
@@ -1,23 +0,0 @@
-SWIG Bug Tracking
-
-<p><img src="images/bugs.png" alt="Bugs">
-
-<p>A <a href="http://sourceforge.net/bugs/?group_id=1645">bug-tracking system</a> for SWIG
-is located on <a href="http://sourceforge.net">SourceForge</a>.
-Please log on to SourceForge before submitting a bug.
-Anonymous bug submitters won't be able to receive emails on the bug progress.
-This might be a problem should we require further feedback on the bug.
-
-<p>
-Users who have found a bug and fixed it themselves can submit a
-<a href="http://sourceforge.net/patch/?group_id=1645">patch</a>.
-Please give the SWIG version or CVS snapshot date that the patch is against.
-Again, please log on to SourceForge before submitting patches.
-
-<p>
-Please note that due to time constraints, bug reports may not
-receive an immediate response.
-If you have an urgent problem, you may want to
-post a message to the <a href="mail.html">swig</a> mailing list
-instead.
-
diff --git a/swigweb/cgi-bin/surveyresponse.pl b/swigweb/cgi-bin/surveyresponse.pl
deleted file mode 100644
index 88f116d..0000000
--- a/swigweb/cgi-bin/surveyresponse.pl
+++ /dev/null
@@ -1,115 +0,0 @@
-#!/usr/bin/perl
-
-# This is a CGI script which takes the input from the simple survey submitted in
-# survey.html. The user's intended languages and operating systems are stored in
-# simple comma separated value files.
-
-use CGI;
-$q = new CGI;
-
-# Start the response web page
-print "Content-type:text/html\n\n";
-print <<EndHTML;
-<html><head><title>SWIG Survey Submission</title></head>
-<body>
-<p/>
-<table> <tr>
-<td bgcolor="#000000" align=center><font color="#ffffff"><b>SWIG Survey Submission</b></font></td>
-</tr> </table>
-
-EndHTML
-
-
-# Extract all the variables out of the response
-$remoteHost = $ENV{'REMOTE_HOST'};
-$remoteAddr = $ENV{'REMOTE_ADDR'};
-$ipAddress = ($remoteHost == '') ? $remoteAddr : $remoteHost;
-
-$langChicken = $q->param('langChicken');
-$langCSharp = $q->param('langCSharp');
-$langGuile = $q->param('langGuile');
-$langJava = $q->param('langJava');
-$langMzscheme = $q->param('langMzscheme');
-$langOcaml = $q->param('langOcaml');
-$langPerl = $q->param('langPerl');
-$langPhp = $q->param('langPhp');
-$langPike = $q->param('langPike');
-$langPython = $q->param('langPython');
-$langRuby = $q->param('langRuby');
-$langSexp = $q->param('langSexp');
-$langTcl = $q->param('langTcl');
-$langXml = $q->param('langXml');
-$langSpareLang1 = $q->param('langSpareLang1');
-$langSpareLang2 = $q->param('langSpareLang2');
-$langSpareLang3 = $q->param('langSpareLang3');
-$langOtherLang = $q->param('langOtherLang');
-
-$namedLanguage = $q->param('namedLanguage');
-
-$osBSD = $q->param('osBSD');
-$osHPUX = $q->param('osHPUX');
-$osLinux = $q->param('osLinux');
-$osMacOSX = $q->param('osMacOSX');
-$osSolaris = $q->param('osSolaris');
-$osWindows = $q->param('osWindows');
-$osOtherOS = $q->param('osOtherOS');
-
-$namedOS = $q->param('namedOS');
-
-# Get log date
-($seconds, $minutes, $hours, $day_of_month, $month, $year, $wday, $yday, $isdst) = gmtime;
-$logDate = sprintf("%04d/%02d/%02d %02d:%02d", $year+1900, $month+1, $day_of_month, $hours, $minutes);
-
-# Create new file each month
-$fileName = sprintf("../survey/swigsurvey-%04d-%02d.csv", $year+1900, $month+1);
-
-if (!-e $fileName) {
- create_file($fileName);
-}
-
-# Open file for appending and lock it to prevent concurrent access
-open(fileOUT, ">>$fileName") or construct_thankyou_page_and_exit(); # We can't log the info if we can't open the file, quietly give up.
-flock(fileOUT, 2);
-seek(fileOUT, 0, 2);
-
-# Dump all the surveyed data to file in comma separated value (CSV) format
-print fileOUT "$logDate,$ipAddress,";
-print fileOUT "$langChicken,$langCSharp,$langGuile,$langJava,$langMzscheme,$langOcaml,$langPerl,$langPhp,$langPike,$langPython,$langRuby,$langSexp,$langTcl,$langXml,$langSpareLang1,$langSpareLang2,$langSpareLang3,$langOtherLang,$namedLanguage,";
-print fileOUT "$osBSD,$osHPUX,$osLinux,$osMacOSX,$osSolaris,$osWindows,$osSpareOS1,$osSpareOS2,$osSpareOS3,$osOtherOS,$namedOS";
-print fileOUT "\n";
-close(fileOUT);
-
-# Create html page response
-construct_thankyou_page_and_exit();
-
-sub create_file($)
-{
- my($fileToCreate) = @_;
-
- open(fileOUT, ">$fileToCreate") or construct_thankyou_page_and_exit(); # We can't log the info if we can't create the file, quietly give up.
-
- # Generate field heading names
- print fileOUT "LogDate,IPAddress,";
- print fileOUT "Chicken,CSharp,Guile,Java,Mzscheme,Ocaml,Perl,Php,Pike,Python,Ruby,Sexp,Tcl,Xml,SpareLang1,SpareLang2,SpareLang3,OtherLang,NamedLanguage,";
- print fileOUT "BSD,HPUX,Linux,MacOSX,Solaris,Windows,SpareOS1,SpareOS2,SpareOS3,OtherOS,NamedOS";
- print fileOUT "\n";
-}
-
-sub construct_thankyou_page_and_exit
-{
- print <<EndHTML;
-
- Thank you for taking the time to fill out the survey. Please continue to the
- <a href="../download.html">Download area</a> or return to the <a href="../index.html">SWIG home</a> page.
- </body></html>
-
-EndHTML
- exit;
-}
-
-
-
-
-
-
-
diff --git a/swigweb/compare.ht b/swigweb/compare.ht
deleted file mode 100644
index 3130a3f..0000000
--- a/swigweb/compare.ht
+++ /dev/null
@@ -1,111 +0,0 @@
-SWIG Features
-
-<h2>SWIG Features</h2>
-
-<p>
-This information is based on the SWIG-1.3.22 release.
-
-<h3>Code Generation</h3>
-
-SWIG current generates wrapper code for thirteen different target languages:
-
-<ul>
-<li>Allegro CL
-<li>C#
-<li>Chicken
-<li>Guile
-<li>Java
-<li>Modula-3
-<li>Mzscheme
-<li>OCAML
-<li>Perl
-<li>PHP
-<li>Python
-<li>Ruby
-<li>Tcl
-</ul>
-
-In addition to this, an XML output module is also available and work
-is in progress on a Pike module.
-
-<h3>ANSI C</h3>
-
-SWIG is capable of wrapping all of ANSI C. Features include:
-
-<ul>
-<li>Handling of <em>all</em> ANSI C datatypes.
-<li>Global functions, global variables, and constants.
-<Li>Structures and unions.
-<li>Pointers.
-<li>Arrays and multidimensional arrays.
-<li>Pointers to functions.
-<li>Variable length arguments.
-<li>Typedef.
-<li>Enums.
-</ul>
-
-<h3>ANSI C++</h3>
-
-SWIG provides wrapping support for almost all of ANSI C++.
-
-<ul>
-<Li>All C++ datatypes.
-<Li>References.
-<li>Pointers to members.
-<li>Classes.
-<li>Inheritance and multiple inheritance.
-<li>Overloaded functions and methods (using dynamic dispatch).
-<li>Overloaded operators.
-<li>Static members.
-<li>Namespaces (including using declarations, aliases, nesting, etc.)
-<li>Templates
-<li>Member templates
-<li>Template specialization and partial specialization.
-<li>Smart pointers
-<li>Library support for strings, STL vectors, and more.
-</ul>
-
-The only major C++ feature not currently supported by SWIG is the
-wrapping of nested classes--a problem we're working on. SWIG also
-does not allow C++ virtual methods to be implemented in certain
-target languages (a subtle feature that might be useful in projects that
-rely heavily on the use of callback functions).
-
-<p>
-C++ users who rely on advanced template programming techniques
-(e.g., template meta-programming) should also be aware that SWIG
-currently requires manual instantiation of all template classes.
-Therefore, if your application somehow involves the instantiation of 50000
-template classes, your mileage might vary.
-
-<h3>Preprocessing</h3>
-
-SWIG provides a full C preprocessor with the following features:
-
-<ul>
-<li>Macro expansion.
-<li>Automatic wrapping of #define statements as constants (when applicable).
-<li>Support for C99 (variadic macro expansion).
-
-</ul>
-
-<h3>Customization features</h3>
-
-SWIG provides control over most aspects of wrapper generation. Most
-of these customization options are fully integrated into the C++ type
-system--making it easy to apply customizations across inheritance
-hierarchies, template instantiations, and more. Features include:
-
-<ul>
-<li>Customizated type conversion/marshaling.
-<Li>Exception handling.
-<li>Class/structure extension.
-<li>Memory management.
-<li>Ambiguity resolution.
-<li>Template instantiation.
-<li>File import and cross-module linking.
-<li>Code inclusion, helper function support.
-<li>Extensive diagnostics (error/warning messages).
-<li>Extended SWIG macro handling.
-</ul>
-
diff --git a/swigweb/compat.ht b/swigweb/compat.ht
deleted file mode 100755
index dd645d2..0000000
--- a/swigweb/compat.ht
+++ /dev/null
@@ -1,95 +0,0 @@
-SWIG Compatibility
-
-<p>
-<img src="images/compat.png" alt="Compatibility">
-
-<p>
-SWIG is known to work on the following platforms :
-
-<ul>
-<li> Unix
-
-<blockquote>
-SWIG is configured and built using an autoconf script so it is
-relatively easy to install on almost any flavor of Unix. However, most of
-SWIG's development has taken place under Linux and Solaris.
-While the configuration script tries to determine the proper settings
-for your machine, some tweaking may be required to compile the
-examples included in the distribution (especially if you are using a
-version of Unix such as AIX or HPUX).
-</blockquote>
-
-<li> Microsoft Windows
-
-<blockquote>
-SWIG works on 32 bit versions of Windows such as Windows 95/98/NT/2000/XP.
-However, given that SWIG is primarily developed under Unix, the Windows
-version is not as thoroughly tested, but is used widely and successfully under Windows.
-Currently the Windows version of SWIG 1.3 is compiled and tested under <a href="http://www.cygwin.com">Cygwin</a> and <a href="http://www.mingw.org">Mingw</a> using gcc, but should be compilable by any other Windows C++ compiler. SWIG 1.1 can be compiled with Visual C++ 4.x/5.x/6.x or with the Borland C++ 5.x
-compiler. However, SWIG 1.1 has only been officially tested using the
-Visual C++ compiler. You may also need to determine which compiler
-has been used to compile the various scripting languages that you will
-be using. In general, using SWIG with a different C++ compiler than
-the one that was used to compile the target scripting language may
-not work (for example, trying to create a Tcl/Tk module using the
-Borland compiler when Tcl/Tk has been compiled with Visual C++).
-
-</blockquote>
-
-<li> Macintosh
-
-<blockquote>
-A highly experimental version of SWIG has been compiled using
-Metrowerks Code Warrior 10. Given the limited availability and
-experience with the Macintosh, this version of SWIG should only
-be used by exceptionally brave users. SWIG has not been fully tested with Python or
-Perl on the Macintosh although some users have reported success.
-<p>
-<b>Note:</b>SWIG-1.3.12 does support OS-X/Darwin. Simply download the Unix
-sources, configure, and build from the command terminal.
-</blockquote>
-</ul>
-
-<h3><a name="SupportedLanguages"></a> Supported Languages </h3>
-
-The following scripting languages were supported in the final SWIG 1.1 release.
-
-<ul>
-<li> Tcl 8.0 and newer versions.
-<li> Python 1.5 and newer.
-<li> Perl 5.003 or newer.
-<li> Guile 1.3.4 and newer.
-</ul>
-
-The following languages are also supported in SWIG 1.3.6 onwards.
-
-<ul>
-<li> Java JDK 1.1 and newer.
-<li> Ruby.
-<li> Mzscheme.
-</ul>
-
-PHP support was added in SWIG 1.3.11.<br>
-Objective Caml (Ocaml) and Pike support was added in SWIG 1.3.14.<br>
-Support for C# and the Chicken scheme compiler was added in SWIG 1.3.18.<br>
-Support for Allegro CL and Modula-3 was added in SWIG-1.3.22.<br>
-<p>
-
-Any newer versions of these languages should be assumed to be
-supported unless otherwise indicated.
-
-There is also <a href="http://www.ultravioletconsulting.com/projects/swigjs">SwigJS</a>, a JavaScript module for SWIG
-and <a href="http://efsa.sourceforge.net/archive/cozzi/swigeiffel.htm">SWIGEiffel</a> for Eiffel.
-
-<h3> Compilation Requirements </h3>
-
-SWIG is implemented in C and C++ and is distributed in source form.
-You will need a working C++ compiler (e.g. g++) to build SWIG and at
-least one of the supported scripting languages to use it (or else it
-isn't going to be very useful). SWIG does not depend upon any of the
-supported scripting languages for its own compilation. Finally,
-although SWIG is partly written in C++, a C++ compiler is not required to use
-SWIG--it works just fine with both ANSI C and C++.
-
-
-
diff --git a/swigweb/copyfun.ht b/swigweb/copyfun.ht
deleted file mode 100644
index c88eeb4..0000000
--- a/swigweb/copyfun.ht
+++ /dev/null
@@ -1,14 +0,0 @@
-Proposed SWIG Copyright
-
-<p>
-<img src="images/copyright.png" alt="Copyright">
-
-<pre>
-Simplified Wrapper and Interface Generator (SWIG)
-
-Copyright (C) 1995-2003
-The University of Chicago
-All Rights Reserved
-
-It's free.
-</pre>
diff --git a/swigweb/copyright.ht b/swigweb/copyright.ht
deleted file mode 100644
index 9c79feb..0000000
--- a/swigweb/copyright.ht
+++ /dev/null
@@ -1,75 +0,0 @@
-SWIG Copyright
-
-<p>
-<img src="images/copyright.png" alt="Copyright">
-
-<pre>
-Simplified Wrapper and Interface Generator (SWIG)
-
-SWIG is distributed under the following terms:
-=================================================
-
-I.
-
-This software includes contributions that are Copyright (c) 1998-2002
-University of Chicago.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-Redistributions of source code must retain the above copyright notice,
-this list of conditions and the following disclaimer. Redistributions
-in binary form must reproduce the above copyright notice, this list of
-conditions and the following disclaimer in the documentation and/or
-other materials provided with the distribution. Neither the name of
-the University of Chicago nor the names of its contributors may be
-used to endorse or promote products derived from this software without
-specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY OF CHICAGO AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OF
-CHICAGO OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
-TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-II.
-
-Copyright (c) 1995-1998
-The University of Utah and the Regents of the University of California
-All Rights Reserved
-
-Permission is hereby granted, without written agreement and without
-license or royalty fees, to use, copy, modify, and distribute this
-software and its documentation for any purpose, provided that
-(1) The above copyright notice and the following two paragraphs
-appear in all copies of the source code and (2) redistributions
-including binaries reproduces these notices in the supporting
-documentation. Substantial modifications to this software may be
-copyrighted by their authors and need not follow the licensing terms
-described here, provided that the new terms are clearly indicated in
-all files where they apply.
-
-IN NO EVENT SHALL THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, THE
-UNIVERSITY OF UTAH OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
-PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
-EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
-THE POSSIBILITY OF SUCH DAMAGE.
-
-THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, AND THE UNIVERSITY OF UTAH
-SPECIFICALLY DISCLAIM ANY WARRANTIES,INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND
-THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
-SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-
-</pre>
-
diff --git a/swigweb/cpp.ht b/swigweb/cpp.ht
deleted file mode 100644
index 413b9fc..0000000
--- a/swigweb/cpp.ht
+++ /dev/null
@@ -1,168 +0,0 @@
-New C++ Features
-
-<h2>Dave's Most Desired C++ Features</h2>
-
-In writing SWIG, I have developed a whole new appreciation for the
-language that is C++. However, I have also come to discover a number
-of serious limitations in the language. Therefore, in the interest of
-public service, I now present my semi-official list of C++ features
-I would most like to see implemented:
-
-<ul>
-<li><b>The slightly ambiguous reference.</b> This would be a variation
-on the ever-so-useful C++ reference (&) used to denote a quantity
-that refers to either the object itself (by value) to a reference to
-an object. The preferred syntax for this is to enclose the variable
-name in brackets and use the ampersand like this
-<tt><&foo></tt>.
-
-<blockquote>
-<pre>
-void foo(Bar <&b>) {
- b.frag(3); // Call some method
- ...
-}
-</pre>
-</blockquote>
-
-In this case, <tt>foo</tt> would either be passed a copy of a
-<tt>Bar</tt> type (pass by value) or a reference to an existing
-<tt>Bar</tt>. The precise choice, of course, would be up to the
-implementation. Obviously, the compiler would pick the best
-option--making it a good choice for programmers too stupid to know whether
-they should use a pointer or not.
-<p>
-Obviously, there are a few complicated cases such as:
-
-<blockquote>
-<pre>
-void foo(const Bar *const *<&b>);
-</pre>
-</blockquote>
-
-The interpretation of this is left as an exercise to the reader (hey,
-it's good to be a professor).
-
-<li><p><b>Circular shift operators.</b> Sure, one doesn't really need to
-do a circular bit shift very often, but they are sometimes useful in
-cryptographic algorithms and for general-purpose bit-twiddling. I
-propose the inclusion of the triple angle bracket operators
-(<tt><<<</tt> and <tt>>>></tt>) for this purpose. Of
-course, these operators could also be overloaded just like the normal
-shift operators. It's not that I really need these operators, but it
-is yet another opportunity to include more angle brackets into the
-language.
-
-<li><p><b>The survival cast.</b> I'm not really sure where I got this idea,
-but basically it works like this: given an object, you can cast it using
-a <tt>survival_cast</tt> like this
-
-<blockquote>
-<pre>
-Bar *x = survival_cast<Bar *>(y);
-</pre>
-</blockquote>
-
-Afterwards, the object that <tt>x</tt> points to is guaranteed to be
-undeletable--even if a program repeatedly calls <tt>delete</tt> or
-<tt>free()</tt> on it. This effect applies to the object itself, not
-the pointer (thus, the cast implicitly applies to all other pointers referring to
-the same object). Furthermore, the cast remains in effect until the
-program terminates--making this a particularly good way to avoid those
-pesky memory management problems such as calling delete too many times
-by accident.
-
-<p>
-The survival cast can be applied to the individual elements of an array
-or container. However, in this case, the implementation must ensure
-that deletion of the array or container only deletes those members for
-which the survival cast has not been applied.
-
-<p>
-When too many objects have been cast using the survival cast, they may
-decide to spontaneously delete themselves along with an unspecified
-number of non-survival objects. This is a feature. However, the
-precise mechanism and scope of destruction is implementation specific
-and may depend on the type of objects to which the survival cast has
-been applied.
-
-<li><p><b>The non-castable function pointer</b>. Since function pointers are
-too confusing for everyone, it should be impossible to cast them into any
-other type. Oh wait, this is already a C++ feature.
-
-<li><p><b>The identifier length cast</b>. Since we're on the subject of casting.... I would
-also like to propose the identifier length cast. This is a cast that only works
-if the identifier names of the two types are exactly the same length in
-characters. For example:
-
-<blockquote>
-<pre>
-Bar *x = identifier_length_cast<Foo *>(y); // Ok
-FooBar *x = identifier_length_cast<Foo *>(y); // Error
-</pre>
-</blockquote>
-
-In addition, there should be an <tt>identifier_case_cast</tt> that works similarly, but
-which looks at the case of the type names. I'm not really sure what purpose these casts
-would serve, but that doesn't really distinguish them from any of the other casts.
-
-<li><p><b>The instance goto</b>. In a nutshell, I really want to be able to do
-this:
-
-<blockquote>
-<pre>
-class Foo {
-public:
- ...
- bar:
- printf("Hello world\n");
- ... some code here ...
- break;
-};
-
-int main() {
- Foo *f = new Foo;
- goto f.bar;
- ...
-}
-</pre>
-</blockquote>
-Obviously, the benefits of this feature are self-evident. However,
-there are still a few tricky points. First, the goto should work with
-inheritance when the goto label happens to appear in a base-class. Second,
-the goto should certainly take advantage of dynamic binding much like virtual
-member functions. Finally, I believe that there would be many interesting
-possibilities of combining template classes with goto. For example:
-
-<blockquote>
-<pre>
-template class Foo<x> {
-public:
- x:
- ... some code here ...
- break;
- ...
-};
-</pre>
-</blockquote>
-
-Clearly, the number of applications is endless.
-
-<li><p><b>MP3 player</b>. Since compiling a C++ application takes so long, I think
-it would be useful to modify the C++ compiler to go out and search the net for an
-appropriate symphony or sonata to download and play while it is working. Ahhhh. Yes.
-Of course, if you have a DVD player handy, I have personally found that watching "Apocalypse Now"
-is a relaxing way to pass the time.
-
-</ul>
-
-Have a further feature suggestion? Please let me know.
-
-
-
-
-
-
-
-
-
diff --git a/swigweb/cvs.ht b/swigweb/cvs.ht
deleted file mode 100644
index 3402040..0000000
--- a/swigweb/cvs.ht
+++ /dev/null
@@ -1,128 +0,0 @@
-SWIG CVS
-
-<p>
-<img src="images/cvs.png" alt="CVS">
-
-<p>
-Development versions of SWIG are available through the CVS server located at SourceForge.
-
-<h3> Disclaimer </h3>
-
-The CVS release represents work in progress and is not guaranteed to compile on your machine or be functional in any
-manner.
-
-<h3> Required Tools </h3>
-
-To compile SWIG from its CVS repository, you will need the following tools:
-
-<ul>
-<li> Autoconf 2.58 or higher
-<li> Automake 1.7.2 or higher
-<li> A working C++ compiler.
-<li> yacc or bison (to compile the SWIG parser).
-</ul>
-
-<p>
-It is important to note that the CVS repository does not include the C++ code
-generated by yacc nor the files produced by Autoconf or Automake (these
-are however included in a normal release). Thus, you will have
-to install these tools on your machine for everything to work.
-
-<h3>To check out the latest version </h3>
-There are
-<a href="http://sourceforge.net/cvs/?group_id=1645">generic CVS instructions</a>
-available on the SourceForge site, but the steps below should be all you need.
-The instructions below are for those who have read only access for cvs, developers should
-consult the generic CVS instructions above.
-
-<ol>
-<li><p> Set the location of CVSROOT
-
-<pre>
- % setenv CVSROOT :pserver:anonymous@cvs.sourceforge.net:/cvsroot/swig </pre>
-<p>
-(Alternatively, you can use the -d option to CVS)
-
-<li><p> Log into the cvs server by issuing the following command:
-
-<pre>
-% cvs login
-CVS password: <press enter here>
-</pre>
-
-<li><p>The latest development version of SWIG can be retrieved using
-
-<pre>
-% cvs checkout SWIG
-</pre>
-
-<li><p>To build the system, follow these steps
-
-<pre>
-% cd SWIG
-% ./autogen.sh
-% ./configure --prefix=/some/directory
-% make
-% make install
-</pre>
-
-<li><p>To check the build, run the tests:
-
-<pre>
-% make -k check </pre>
-This could take up to an hour or longer. If you are interested in a particular language,
-just check the examples and test-suite for that language. For example, the Python tests:
-<pre>
-% make check-python-examples
-% make check-python-test-suite
-</pre>
-
-</ol>
-
-<b>Note:</b> The CVS repository is read-only so the system will not
-accept code modifications unless you are a developer.
-
-<h3> Build Issues </h3>
-Here are some guidelines should you be experiencing problems building SWIG from CVS.
-
-<ol>
-
-<li>Check that you have a complete update from the SWIG CVS repository.
-A fresh checkout from CVS often solves build problems.
-</li>
-
-<li>
-Make sure you have run <tt>./autogen.sh</tt> and <tt>./configure</tt>.
-Both these steps will be necessary if you have a fresh CVS checkout or if the build files in the repository have changed since a previous update.
-</li>
-
-<li>
-Check that the appropriate versions of your autotools (Autoconf and Automake) are installed properly.
-The autotools are in a state of flux and there are backward compatibility issues which are solved in different ways on different operating systems.
-</li>
-
-<li>
-Check that all the autotool bootstrap programs which are executed when running <tt>./autogen.sh</tt> are up to date and match your installed autotool versions.
-For example <tt>aclocal --version</tt> should report a matching version of Automake or Autoconf, something like "aclocal (GNU automake) 1.7.6".
-</li>
-</ol>
-
-If you are still having problems, send an email to <a href="mail.html">swig-dev</a> mailing list.
-
-<h3>Developer Access</h3>
-
-We are always looking for people to help out with various projects.
-
-<ul>
-<li><p> Send email to to the <a href="mail.html">swig-dev</a> mailing list.
-if you are interested in doing developer work and gaining write access to the CVS repository.
-
-<li><p> The <a href="mail.html">swig-dev</a> mailing list is the developer mailing list
-and should be used to discuss coding issues, bugs, patches, and so forth.
-Subscription information and archives of recent activity can be found on the <a href="mail.html">mailing lists</a> page.
-</ul>
-
-
-
-
-
diff --git a/swigweb/default.corner b/swigweb/default.corner
deleted file mode 100644
index 4c12e82..0000000
--- a/swigweb/default.corner
+++ /dev/null
@@ -1,3 +0,0 @@
-<center>
-<img src="images/swig17.png" alt="SWIG image">
-</center>
diff --git a/swigweb/default.footer b/swigweb/default.footer
deleted file mode 100644
index 7dfa867..0000000
--- a/swigweb/default.footer
+++ /dev/null
@@ -1,6 +0,0 @@
-<hr>
-Feedback and questions concerning this site should be posted to the <a href="mail.html">swig-dev</a> mailing list.
-
-<p>
-Last modified : $mtime
-
diff --git a/swigweb/default.html b/swigweb/default.html
deleted file mode 100644
index b029f67..0000000
--- a/swigweb/default.html
+++ /dev/null
@@ -1,62 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<title>$title</title>
-<body bgcolor="#ffffff" link="#0000ff" vlink="#8000ff">
-
-<table width=780 border=0 cellpadding=0 cellspacing=0 summary="Main web page">
-<tr>
- <td valign=middle bgcolor="#000000">
- <table width=180 cellpadding=0 cellspacing=0 summary="Corner section">
- <tr>
- <td>
-$corner
- </td>
- </tr>
- </table>
- </td>
- <td valign=middle bgcolor="#e0e0e0">
- <table width=600 cellpadding=0 cellspacing=0 summary="Top section">
- <tr>
- <td valign=middle>
-$top
- </td>
- </tr>
- </table>
- </td>
-</tr>
-<tr>
- <td valign=top bgcolor="#e0e0e0">
- <table width=180 summary="Side section">
- <tr>
- <td>
-$side
- </td>
- </tr>
- </table>
- </td>
- <td valign=top>
- <table width=600 summary="Web page body">
- <tr>
- <td>
-$body
-
-$footer
- </td>
- </tr>
- </table>
- </td>
-</tr>
-</table>
-
-</body>
-</html>
-
-
-
-
-
-
-
-
-
-
diff --git a/swigweb/default.side b/swigweb/default.side
deleted file mode 100644
index 76a5443..0000000
--- a/swigweb/default.side
+++ /dev/null
@@ -1,42 +0,0 @@
-<table width="100%" summary="Side section links">
-<tr>
-<td bgcolor="#000000" align=center><font color="#ffffff"><b>Information</b></font></td>
-</tr>
-<tr><td><a href="exec.html">What is SWIG?</a></td></tr>
-<tr><td><a href="compat.html">Compatibility</a></td></tr>
-<tr><td><a href="compare.html">Features</a></td></tr>
-<tr><td><a href="tutorial.html">Tutorial</a></td></tr>
-<tr><td><a href="doc.html">Documentation</a></td></tr>
-<tr><td><a href="cvs.html">The Bleeding Edge</a></td></tr>
-<tr><td><a href="history.html">History</a></td></tr>
-<tr><td><a href="subversion.html">Subversion</a></td></tr>
-<tr><td><a href="guilty.html">Guilty Parties</a></td></tr>
-<tr><td><a href="projects.html">Accessories</a></td></tr>
-<tr><td><a href="copyright.html">Legal Department</a></td></tr>
-<tr><td><a href="links.html">Links</a></td></tr>
-<tr><td><a href="survey.html">Download</a></td></tr>
-<tr><td><a href="http://www.signal6.com/cgi-bin/wiki.pl">SwigWiki</a></td></tr>
-
-<tr><td bgcolor="#000000" align=center><font color="#ffffff"><b>Exits</b></font></td></tr>
-<tr><td><a href="http://www.perl.com">Perl</a></td></tr>
-<tr><td><a href="http://www.python.org">Python</a></td></tr>
-<tr><td><a href="http://www.tcl.tk">Tcl/Tk</a></td></tr>
-<tr><td><a href="http://www.gnu.org/software/guile/guile.html">Guile</a></td></tr>
-<tr><td><a href="http://www.plt-scheme.org/software/mzscheme/">MzScheme</a></td></tr>
-<tr><td><a href="http://www.ruby-lang.org">Ruby</a></td></tr>
-<tr><td><a href="http://java.sun.com">Java</a></td></tr>
-<tr><td><a href="http://www.php.net">PHP</a></td></tr>
-<tr><td><a href="http://www.call-with-current-continuation.org/chicken.html">CHICKEN</a></td></tr>
-<tr><td><a href="http://www.ocaml.org/">Ocaml</a></td></tr>
-
-<tr><td bgcolor="#000000" align=center><font color="#ffffff"><b>Our Generous Host</b></font></td></tr>
-<tr><td align=center><a href="http://sourceforge.net"><img src="http://sourceforge.net/images/sflogo2-steel.png" vspace="0" border=0 alt="SourceForge logo"></A></td></tr>
-</table>
-
-
-
-
-
-
-
-
diff --git a/swigweb/default.top b/swigweb/default.top
deleted file mode 100644
index 60b34e8..0000000
--- a/swigweb/default.top
+++ /dev/null
@@ -1,8 +0,0 @@
-<table width="100%" cellpadding=0 border=0 summary="Top section links">
-<tr>
-<td><a href="index.html">Home</a></td>
-<td><a href="http://sourceforge.net/project/?group_id=1645">Development</a></td>
-<td><a href="mail.html">Mailing Lists</a></td>
-<td><a href="bugs.html">Bugs and Patches</a></td>
-</tr>
-</table>
diff --git a/swigweb/doc.ht b/swigweb/doc.ht
deleted file mode 100644
index 2ee198b..0000000
--- a/swigweb/doc.ht
+++ /dev/null
@@ -1,91 +0,0 @@
-SWIG Documentation, Presentations, and Papers
-
-<p><img src="images/doc.png" alt="Documentation">
-
-<H3>SWIG-1.3</h3>
-<ul>
-
-<li> <a href="Doc1.3/index.html">Development Documentation</a> for latest release.
-</ul>
-
-<h3>SWIG-1.1</h3>
-<ul>
-<li> <a href="Doc1.1/HTML/Contents.html">Online Users Manual</a>.
-<li> Also available in <a href="Doc1.1/PDF/SWIGManual.pdf">PDF</a> (318 pages).
-</ul>
-
-<h3> Online Papers about SWIG </h3>
-
-<ul>
-<li> <b><a href="papers/Perl98/swigperl.htm">Perl Extension Building with SWIG</a></b>.
-This paper, presented at the 1998 O'Reilly Perl Conference, describes the use
-of SWIG with Perl5 and covers many advanced topics.
-[ <a href="papers/Perl98/swigperl.pdf">PDF</a> ]. <br>
-
-<li><p> <b><a href="papers/Tcl98/TclChap.html">Tcl and SWIG as a C/C++ Development Tool</a></b>.
-Originally written as a draft for a book chapter, this paper provides an overview of
-using Tcl and SWIG. It also appears on the CD-ROM accompanying "Tcl/Tk for Real Programmers"
-by Clif Flynt.<br>
-
-<li><p> <b><a href="papers/Tcl96/tcl96.html">SWIG : An Easy to Use Tool for Integrating Scripting Languages with C and C++</a></b>.
-While a little dated, this is the first SWIG paper. Presented at
-the 4th Tcl/Tk Workshop, Monterey, California, July 6-10, 1996. Also available
-from <a href="http://www.usenix.org/publications/library/proceedings/tcl96/beazley.html">USENIX</a>. <br>
-
-<li><p> <b><a href="papers/Py96/python96.html">Using SWIG to Control, Prototype, and Debug
-C Programs with Python</a></b>. Presented at the 4th International Python Conference,
-Livermore, California, June, 1996. <br>
-
-<li> <b><a href="papers/Py97/beazley.html">Feeding a Large-scale Physics Application to Python</a></b>. Presented at the 6th International Python Conference, San Jose, California.
-October 14-17, 1997. This paper describes the use of Python/SWIG with a high-performance
-physics application. This application was a runner-up in the 1998
-Gordon-Bell prize for achieving 10 Gflops sustained performance on the
-<a href="http://loki-www.lanl.gov/papers/sc98/">Avalon</a> Linux
-Cluster at Los Alamos National Laboratory. <br>
-
-</ul>
-
-<h3> Tutorials about SWIG </h3>
-
-<ul>
-<li> <b><a href="papers/PyTutorial98/PyTutorial98.pdf">Interfacing C/C++ and Python with SWIG</a></b> (PDF).
-Half-day tutorial presented at the 7th International Python Conference, November, 1998. <br>
-
-<li><p> <b><a href="papers/PyTutorial97/PyTutorial97.pdf">Interfacing C/C++ and Python with SWIG</a></b> (PDF).
-Half-day tutorial presented at the 6th International Python Conference, October, 1997. <br>
-
-<li><p> <b><a href="papers/TclTutorial98/TclTutorial98.pdf">Tcl Extension Building with SWIG</a></b> (PDF). Tutorial presented at the 1998 Tcl/Tk Conference. <br>
-</ul>
-
-<h3> Other Resources </h3>
-
-<ul>
-<li> Perl users can find more information about SWIG in the O'Reilly book
-<a href="http://www.ora.com/catalog/advperl">"Advanced Perl Programming"</a>. <br>
-
-<li><p> Daniel Blezek wrote an article about SWIG in the November, 1998 issue
-of the <a href="http://www.cuj.com/archive/1611/index.html">C/C++ Users Journal</a>.
-
-<li><p>An article about SWIG appeared in the February, 1998 issue
-of <a href="http://www.ddj.com/ddj/1998/1998_02/index.htm">Dr. Dobb's Journal</a> on
-Scripting and Alternative Languages. <br>
-
-<li><p>Scott Bolte wrote an article about SWIG in the Winter, 1997 issue of
-<a href="http://www.tpj.com">The Perl Journal</a>. <br>
-
-
-<li><p> John Ousterhout's <a href="http://home.pacbell.net/ouster/scripting.html">
-paper </a> on scripting languages provides a good overview
-of the use of scripting languages and their relationship to
-systems programming languages. SWIG was developed with many of these issues
-in mind so this paper might be of interest to users who are new to
-SWIG and its goals. <br>
-
-<li><p> <b><a href="http://www.supercomp.org/sc96/proceedings/SC96PROC/BEAZLEY/INDEX.HTM"> Lightweight Computational Steering of Very Large Scale Molecular Dynamics Simulations </a></b>.
-Presented at Supercomputing'96. This paper describes the application that
-motivated the development of SWIG. (See why SWIG was originally developed). <br>
-
-</ul>
-
-
-
diff --git a/swigweb/download.ht b/swigweb/download.ht
deleted file mode 100644
index cfaf395..0000000
--- a/swigweb/download.ht
+++ /dev/null
@@ -1,68 +0,0 @@
-Download SWIG
-<p>
-<img src="images/download.png" alt="Download">
-
-<p>
-SourceForge is now the primary site for SWIG distributions.
-
-<ul>
-<li><a href="http://sourceforge.net/project/showfiles.php?group_id=1645">All releases</a>.
-<li><a href="ftp://swig.sourceforge.net/pub/swig/">Older stuff</a>.
-</ul>
-
-<p>
-SWIG has also been distributed as source code from the following locations:
-
-<ul>
-<li> <a href="ftp://ftp.mcc.ac.uk/pub/mvc/swig">ftp.mcc.ac.uk/pub/mvc/swig</a> (UK)
-<li> <a href="ftp://ftp.rge.com/pub/languages/swig/">ftp.rge.com/pub/languages/swig</a> (New York).
-<li> <a href="ftp://ftp.python.org/pub/python/contrib/System/">ftp.python.org/pub/python/contrib/System</a> (Python contributed software).
-<li> <a href="http://www.perl.com/CPAN//authors/Dave_Beazley">CPAN (Comprehensive Perl Archive Network)</a>
-</ul>
-
-You can also find SWIG in the following locations :
-
-<ul>
-<li> <a href="http://cgi.debian.org/www-master/debian.org/Packages/stable/interpreters/swig.html">Debian GNU/Linux</a>.
-<li> <a href="http://www.freebsd.org/ports/devel.html">FreeBSD</a>.
-<li> <a href="http://www.cygwin.com">Cygwin</a>.
-<li> <a href="http://www.oreilly.com/catalog/python/noframes.html">Programming Python</a> (Included on CD-ROM).
-<li> <a href="http://www.mkp.com/books_catalog/0-12261-205-1.asp">Tcl/Tk for Real Programmers</a> (Included on CD-ROM).
-</ul>
-
-Note : If you received SWIG on CD-ROM, you may want to upgrade to the latest release.
-
-<h3> The Latest Release </h3>
-
-<p>
-<a href="http://prdownloads.sourceforge.net/swig/swig-1.3.25.tar.gz">SWIG
-1.3.25</a> is the latest development release (2005/06/11). View the
-<a href="release.html">release notes</a>. Windows users should download
-<a href="http://prdownloads.sourceforge.net/swig/swigwin-1.3.25.zip">swigwin-1.3.25</a>
-which includes a prebuilt executable.
-
-<p>
-<b>Note:</b> The following releases pertain to SWIG-1.1 which was a widely distributed release
-from several years ago. Unless you really need backwards compatibility, you should use
-SWIG-1.3.x instead of SWIG-1.1 (especially since 1.3 is much more capable).
-
-<p>
-<a href="http://prdownloads.sourceforge.net/swig/swig1.1p5.tar.gz">SWIG 1.1p5</a>
-is the latest stable release of SWIG-1.1 (1998/02/05).
-
-<b>Note (2000/01/18) </b>SWIG-1.1p5 has a number of compilation issues
-with ANSI C++ compilers and will probably generate a lot of compiler
-warnings. Sorry.
-
-<p>
-<a href="http://prdownloads.sourceforge.net/swig/swig1.1-883.tar.gz">SWIG1.1-883</a> is the last maintenance version of SWIG-1.1 (December 1999). This isn't really a
-"release", but the last nightly build that was completed before
-development work shifted to SWIG-1.3. It fixes a number of bugs in
-SWIG1.1p5.
-
-
-
-
-
-
-
diff --git a/swigweb/exec.ht b/swigweb/exec.ht
deleted file mode 100644
index a1a9987..0000000
--- a/swigweb/exec.ht
+++ /dev/null
@@ -1,112 +0,0 @@
-Executive Summary
-
-<p>
-<img src="images/exec.png" alt="Executive Summary">
-
-<p>
-SWIG is an interface compiler that connects programs written in C and
-C++ with scripting languages such as Perl, Python, Ruby, and Tcl. It
-works by taking the declarations found in C/C++ header files and using
-them to generate the wrapper code that scripting languages need to
-access the underlying C/C++ code. In addition, SWIG provides a
-variety of customization features that let you tailor the wrapping
-process to suit your application.
-
-<p>
-John Ousterhout (creator of Tcl) has written a
-<a href="http://home.pacbell.net/ouster/scripting.html">paper</a>
-that describes the
-benefits of scripting languages. SWIG makes it fairly easy to connect scripting
-languages with C/C++ code.
-
-<p>SWIG is used in a number of ways:
-
-<ul>
-<li><p><b>Building more powerful C/C++ programs</b>. Using SWIG, you can
-replace the main() function of a C program with a scripting
-interpreter from which you can control the application. This adds
-quite a lot of flexibility and makes the program "programmable." That
-is, the scripting interface allows users and developers to easily
-modifiy the behavior of the program without having to modify low-level
-C/C++ code. The benefits of this are numerous. In fact think of all
-of the large software packages that you use every day---nearly all of
-them include special a macro language, configuration language, or even
-a scripting engine that allows users to make customizations.
-
-<li><p><b>Rapid prototyping and debugging</b>. SWIG allows C/C++ programs to be placed in
-a scripting environment that can be used for testing and debugging.
-For example, you might test a library with a collection of scripts or use the scripting
-interpreter as an interactive debugger. Since SWIG requires no modifications to the
-underlying C/C++ code, it can be used even if the final product does not rely upon scripting.
-
-<li><p><b>Systems integration</b>. Scripting languages work fairly well
-for controlling and gluing loosely-coupled software components
-together. With SWIG, different C/C++ programs can be turned into
-scripting language extension modules. These modules can then be
-combined together to create new and interesting applications.
-
-<li><p><b>Construction of scripting language extension modules</b>. SWIG
-can be used to turn common C/C++ libraries into components for use in
-popular scripting languages. Of course, you will still want to make
-sure that no-one else has already created a module before doing this.
-</ul>
-
-SWIG is sometimes compared to interface definition language (IDL)
-compilers such as those you find with systems such as CORBA and COM.
-Although there are a few similarities, the whole point of SWIG is to
-make it so you don't have to add an extra layer of IDL specifications
-to your application. If anything, it's much more of a rapid
-application development and prototyping tool. Specifically:
-
-<ul>
-<li><p><b>ANSI C/C++ syntax</b>. SWIG parses ANSI C++ that has been
-extended with a number of special directives. As a result, interfaces
-are usually built by grabbing a header file and tweaking it a little
-bit. This particular approach is especially useful when the
-underlying C/C++ program undergoes frequent modification.
-
-<li><p><b>SWIG is not a stub generator</b>. SWIG produces code that you
-simply compile and run. You don't have to fill in any stubs or write
-special client/server code as you do with RPC-like systems.
-
-<li><p><b>SWIG does not define a protocol nor is it a component
-framework.</b> SWIG does not define mechanisms or enforce rules
-regarding the way in which software components are supposed to
-interact with each other. Nor is it a specialized runtime library
-or alternative scripting language API. SWIG is merely a code generator
-that provides the glue necessary to hook C/C++ to other languages.
-
-<li><p><b>Designed to work with existing C/C++ code</b>. SWIG
-requires little, if any, modifications to existing code. For the most
-part, it encourages you to keep a clean separation between C/C++ and
-its scripting interface.
-
-<li><p><b>Extensibility</b>. SWIG provides a variety of customization options that
-allow you to blow your whole leg off if that's what you want to do.
-SWIG is not here to enforce programming morality.
-</ul>
-
-Finally, it is worth noting that even though SWIG is occasionally compared
-to other more specialized scripting language extension building tools
-(e.g., Perl XS, Python bgen, etc.), its primary audience is C/C++
-programmers who want to add a scripting language component to their
-applications. Because of this, SWIG tends to have a slightly
-different focus than tools designed to build small modules for
-widespread use in a scripting language distribution. applications.
-
-<p>
-A number of <a href="doc.html">papers and tutorials</a> describing SWIG are available.
-You can also view a simple <a href="tutorial.html">tutorial</a> to see an
-example of SWIG in action, or check out how other people are using SWIG
-in their <a href="projects.html">projects</a>.
-
-<p>
-SWIG has been freely available in various forms since February, 1996
-and a large number of developers have made contributions. Today, SWIG
-remains an all-volunteer effort. Approximately 875 people subscribe
-to the <a href="mail.html">swig</a> mailing list and a public CVS
-repository is available at SourceForge. Versions of
-SWIG can now be found in most Linux distributions (however, you'll almost
-certainly want to get the latest version here).
-
-
diff --git a/swigweb/faq.ht b/swigweb/faq.ht
deleted file mode 100644
index d84b83f..0000000
--- a/swigweb/faq.ht
+++ /dev/null
@@ -1,17 +0,0 @@
-SWIG FAQ
-
-<p>
-<img src="images/faq.png" alt="FAQ">
-
-<p>
-To date, there has been no FAQ for SWIG. As a result, you may want to
-check the following locations:
-
-<ul>
-<li>The <a href="doc.html">online documentation</a>.
-<li>The <a href="bugs.html">bug tracking database</a>.
-<li>The <a href="mail.html">Mailing list archive</a>.
-</ul>
-
-At this time, I am looking into the creation of a FAQ. However, this would be
-much much easier if there were a volunteer to help.
diff --git a/swigweb/faq.nt b/swigweb/faq.nt
deleted file mode 100644
index f7e8ef8..0000000
--- a/swigweb/faq.nt
+++ /dev/null
@@ -1,17 +0,0 @@
-SWIG FAQ
-
-<p>
-<img src="images/faq.gif">
-
-<p>
-To date, there has been no FAQ for SWIG. As a result, you may want to
-check the following locations:
-
-<ul>
-<li>The <a href="doc.html">online documentation</a>.
-<li>The <a href="bugs.html">bug tracking database</a>.
-<li>The <a href="mail.html">Mailing list archive</a>.
-</ul>
-
-At this time, I am looking into the creation of a FAQ. However, this would be
-much much easier if there were a volunteer to help.
diff --git a/swigweb/future.ht b/swigweb/future.ht
deleted file mode 100644
index b76de79..0000000
--- a/swigweb/future.ht
+++ /dev/null
@@ -1,367 +0,0 @@
-SWIG-1.3.12, SWIG-2.0 and Beyond
-
-<h2>SWIG-1.3.12, SWIG 2.0, and Beyond</h2>
-
-<p>
-Author: David Beazley (beazley@cs.uchicago.edu)
-
-<p>
-June 2, 2002
-
-<p>
-With the release of SWIG-1.3.12, I thought I'd take a few moments of
-everyone's time to talk about the past, the present, and the future of
-SWIG development. I'm really quite excited about the current release
-because I think it represents a huge turning point in SWIG's
-development. Furthermore, it is only the beginning of bigger and
-better things to come. However, we definitely need your help.
-
-<p>
-To put a little perspective on the discussion, I'd start with a few
-development statistics. In the last 12 months, there have been over
-300 entries added to the CHANGES log and over 4000 CVS commits.
-Although that may not sound like a lot compared to a huge software
-project, it is significant in the context of SWIG. As a point of
-comparison, there has been more SWIG development this year than in any
-other year of the project and more than in the previous three years
-combined. This even includes the first few years of development in
-which there was also a lot of activity. Furthermore, many of the
-recent changes have been extremely non-trivial (e.g., templates,
-namespaces, type system, operators, etc.). As a result, SWIG is more
-capable than I ever imagined possible.
-
-<p>
-Regrettably, I must admit that I've been a little negligent in
-discussing the roadmap for where I thought this flurry of SWIG
-development was actually headed. In part, this is because I've been
-buried in work. However, the real reason is that I didn't really know
-where we were going---except that in a time far far far away in the
-future, we might arrive at some kind of "stable" release with a
-version number other than "1.3.x". Needless to say, that's not a very
-compelling story.
-<p>
-That said, I've spent a lot of time thinking about SWIG and trying to
-wrap my brain around it. Specifically, just what is (or should be)
-the primary focus of this project and what are we really trying to do?
-That's what the rest of this message is about.
-
-<h3>SWIG Prehistory</h3>
-
-<p>
-The first version of SWIG was written in 1995. The original system
-was developed to help with some software wrapping problems I
-encountered while writing molecular dynamics software at Los
-Alamos. Later that year, I became interested in extending the wrapper
-generator to support other scripting languages so it was rewritten in
-C++ and modified with multiple backends (Tcl, Perl, and Guile). This
-led to a first public release in February, 1996. Feedback from this
-release led to a series of enhancements and the release of SWIG 1.0 in
-September 1996. Throughout this process, my intent was to create a
-tool that I would want to use---I never viewed the project as an
-CS experiment in programming languages or software engineering.
-
-<h3>SWIG 1.1</h3>
-
-SWIG-1.1 (June, 1997) represented a series of enhancements that were
-added in response to feedback at conferences and from users. Shadow
-classes, exception handling, typemaps, and a number of more useful
-features were added. However, the overall structure of the system was
-relatively unchanged from the initial version. Following the release
-of 1.1, a series of minor patch releases were made. This resulted in
-the release of SWIG-1.1p5 in February, 1998. Unfortunately, this
-release would remain the last "stable" release for quite a long
-time---in fact, it is still listed as the last "stable" release on the
-SWIG web page!
-
-<h3>SWIG Hell</h3>
-
-Even during the development of SWIG-1.1, it was clear that the whole
-design of the system was deeply flawed. The implementation was a mess
-and the C/C++ support was full of holes and nasty corner cases.
-Furthermore, there was no unifying principle that tied all of the
-different SWIG directives together. Not only that, fixing these
-problems appeared to be nothing short of impossible---requiring a
-total ground-up rewrite at best. The only redeeming quality was that
-the system basically worked "well enough," it was extensively
-documented, and its flaws mostly known. People could use it and there
-were work-arounds for most common problems.
-
-<p>
-To deal with the design problem, there were at least four attempts to
-completely rewrite SWIG, some of which were attempted in parallel with
-the work on SWIG-1.1. Unfortunately, none of these were ever
-completed. The primary problem was a strong "second system" effect and
-a desire to make SWIG do everything that one might conceivably want to
-do with a wrapper generator (somehow). Clearly, this was a recipe for
-disaster. In fact, all such attempts to rewrite SWIG were eventually
-abandoned several years ago. In hindsight, I think the real problem
-was that these rewrite efforts focused far too much attention on
-implementation technique rather than principles. In short, the
-failure of these efforts was due to a lack of clarity in understanding
-how SWIG ought to work (regardless of how it was actually
-implemented).
-
-<h3>SWIG Restart (1.3a1-1.3a5)</h3>
-
-<p>
-Having languished for several years, the SWIG1.1p5 release had a
-growing pile of maintenance issues. It didn't work for newer versions
-of certain language modules and a lot of minor bug reports and feature
-requests had been building up. With a lot of help from Loic Dachary and
-Thien-Thi Nguyen, we put together the 1.3a1 release (February,
-2000). This was mostly a bug fix release to 1.1p5 except that the
-preprocessor module from SWIG1.2 was added and a lot of minor
-enhancements were added.
-
-<p>
-For the next six months, a massive effort was made to rewrite all of
-SWIG's internal data structures (strings, lists, hashes, etc.). This
-work was all going on underneath the covers while we tried to keep
-SWIG in an operational state. The primary focus of this work was
-really one of cleanup. Having given up on a total rewrite, perhaps
-we could settle with making the implementation incrementally better
-than before. In addition this, Matthias Koppe jumped on board to
-reimplement the Guile module and to make other improvements to the system.
-
-<p>
-An important aspect of these releases was that many parts of the
-system not directly related to wrapper code generation were removed.
-This included the documentation system and Objective-C support. These
-were not removed because they weren't useful. Instead, the
-documentation system was removed because it accounted for nearly half
-of the special SWIG directives, yet had no direct bearing on what SWIG
-actually did. Obective-C support was removed because it was tangled
-with C++ support in a way that was very difficult to understand and
-maintain. The removal of these features was seen as a way to vastly
-simplify cleanup--and to buy some time where we could rethink their
-role in a future release.
-
-<h3>SWIG Redux (1.3.6-1.3.11)</h3>
-
-This work, started in February 2001, is the beginning of the current
-SWIG implementation. With the help of William Fulton, Matthias Koppe,
-Lyle Johnson, Luigi Ballabio, Jason Stewart, Richard Palmer, Sam
-Liddicot, and others, this work can best be described as the wholesale
-destruction of everything remaining from SWIG-1.1. The language
-module API, type system, the parser, numerous SWIG directives, and
-SWIG library files---all destroyed or rewritten. Not only that, we
-started introducing significant incompatibilities with
-SWIG-1.1---mostly in an effort to correct past wrongs and get
-ourselves out of the tangled mess of earlier versions. A huge number
-of long-standing bugs and difficult feature requests have also been
-resolved.
-
-<p>
-The general goal of this development could best be described as an
-attempt to reduce SWIG to an easily described set of general "ideas"
-about how it should operate. Special SWIG directives have been
-eliminated or combined with others. Different parts of the system have
-been better integrated. Features not directly related to wrapper code
-generation have been removed and the system has become more
-focused. Changes in internal data structures and APIs have allowed
-SWIG to capture more information from interface files and to resolve
-hard corner cases. More often than not, these are things that you
-never notice unless you are an old user and you suddenly realize that
-a problem you had several years back has disappeared.
-
-<p>
-Along with the destruction of old code, this work has quietly
-introduced a new core--the most significant features of which are a
-new C++ type system and multi-pass compilation. More importantly,
-this work has really tried to provide a more principled foundation for
-future SWIG development. However, just what is this "more principled
-foundation?"
-
-<h3>Convergence (1.3.12)</h3>
-
-With the upcoming 1.3.12 release, SWIG is about to take a big leap
-forward. Almost all of this is due to one realization---that almost
-every hard problem in past SWIG releases has been directly related to
-errors and limitations in its type system. Types are the key to
-understanding the structure of C and C++ code. They are at the heart
-of understanding advanced language features like namespaces, nested
-classes, and templates. They are directly related to the data
-marshalling that occurs in wrappers. Not only that, they interact
-with nearly every SWIG directive. A proper type system *is* the
-necessary foundation for moving SWIG forward.
-
-<p>
-To be honest, I don't think that the emphasis on types is entirely
-obvious. In fact, a great deal of work in past SWIG rewrites has
-focused on the problem of C++ parsing. For instance, modifying the
-parser to handle more advanced C++ code or representing parse trees as
-XML. Furthermore, if one looks at the SWIG mailing list, you can find
-a *lot* of messages related to issues of C++ parsing whereas almost no
-one ever talks about types (well, other than typemaps). Even other
-wrapper generation tools seems to spend a lot of time dealing with the
-parsing issue. Although parsing is clearly important, I don't think it
-has ever been the real problem in SWIG. This is because even though a
-parser can tell you what's in a header file, it doesn't tell you
-anything about how the different pieces of the system behave or how
-they might interact. To do that, you need to do a lot more than just
-parsing--and that's really the whole point.
-
-<p>
-Although earlier 1.3 releases have made big improvements to the type
-system, SWIG-1.3.12 is the first release that really tries to tackle
-the type-system issue in a major way. We have patched nearly all
-remaining holes in the type system and we have added full support for
-C++ namespaces. Not only that, we have completely reimplemented C++
-template support in a way that supports templates, member templates,
-and template specialization. Luigi and I are currently using this to
-work on proper SWIG library support for parts of the C++ standard
-library and the Standard Template Library (STL). Although some crusty
-C programmers (present company excepted), might balk at such apparent
-insanity, this work has impacted all parts of SWIG at all levels.
-Even a variety of subtle errors in C support have been fixed by this
-work.
-
-<p>
-In addition to the type system work, SWIG-1.3.12 contains continued
-reduction in the implementation. Directives have been removed,
-refined, renamed, or consolidated. We're still narrowing the focus of
-the system and working towards some kind of convergence. "Convergence
-to what?!?", you ask.
-
-<h3>So, what is SWIG?</h3>
-
-In a nutshell, SWIG is a C/C++ declaration compiler that generates
-wrapper code (okay, so you knew that much). However, to really
-understand what SWIG is doing and where SWIG-1.3.x is headed, it is
-useful to know that the whole system is essentially being built around
-three extensions to the C++ type system:
-
-<ul>
-
-<li><p><b>Typemaps.</b> Typemaps are rules that define the process by which
- data is converted between languages. They are fully integrated
- with the C++ type system and they are applied using a type-based
- pattern matching mechanism. All data conversion SWIG is
- defined by typemaps and is fully reconfigurable.
-
-<li><p><b>Declaration annotation.</b> There are special directives that modify
- the wrapping behavior of individual declarations. Declarations
- can be selectively identified and decorated with arbitrary
- attributes that affect wrapper generation. Like typemaps,
- declaration matching is fully integrated with the C++ type system.
- Almost all SWIG customization directives are a form of declaration
- annotation.
-
-<li><p><b>Class extension.</b> The ability to extend classes and structures
- with new methods/attributes when building wrappers. Classes
- are part of the type system so class extension is naturally
- integrated with the C++ type system as well (big surprise).
-
-</ul>
-<p>
-And that's it--this is the end-game of SWIG-1.3.x development. When
-stabilized and documented it will become SWIG-2.0.
-
-<h3>The Bigger Picture</h3>
-
-I really want to emphasize that all of this work is part of a much
-bigger picture. SWIG is used by a surprising number of people in
-industry, government, and academia. It's used to build systems used
-by millions of people every day. It has even shown up in video games
-and other unlikely settings. Although SWIG doesn't have the same
-visibility as many large software projects, over 12000 people have
-downloaded SWIG-1.3.11 in the last 4 months. Clearly someone is using
-it for something! Because of this, I think it is important for us to
-work on moving SWIG towards a more solid foundation. Doing so will
-give the system more credibility and long term viability---and it will
-be a lot more fun to use!
-
-<p>
-It's also worth noting that there are some rather interesting CS
-connections at work here. Extensions to the type system and typemaps
-have some interesting relations to work in programming languages. The
-SWIG declaration annotation system and class extension feature seem
-oddly similar to work in the emerging area of Aspect Oriented
-Programming (AOP). There are undoubtedly connections to other areas
-of software engineering and architecture.
-
-<p>
-The key point is that SWIG isn't going to connect to anything if
-no-one can quite describe what it is or how it works.
-
-<h3>SWIG-2.0 and the Future</h3>
-
-SWIG-1.3.12 still represents work in progress. There are bugs, the
-documentation is still incomplete, and there are parts of the
-implementation that are rather ugly. We are also still working out a
-few very hard problems like nested classes, callback functions, and
-overloading. A few old features are still missing (Objective-C,
-documentation). However, I believe the end of the 1.3.x series is
-near and achievable.
-
-<p>
-Over the summer, a few more 1.3.x releases may appear but the current
-plan is to aim for a SWIG-2.0 release in September. This release is
-really moving towards the design principles described above and will
-be a very major enhancement over SWIG-1.1.
-
-<p>
-As for the future, a number of interesting ideas are on the table. I
-want to add support for contracts/assertions in order to solve some
-reliability issues that arise when retrofitting legacy codes with a
-scripting interface. Support for an extension language has been
-promoted by David Fletcher and was suggested by someone else on the
-mailing list rather recently. I have a graduate student working on
-SWIG support for the Microsoft CLR and .NET languages. Other work
-might include support for alternative parsers, dynamically loadable
-language modules, and so forth. However, none of this is really going
-to materialize if we can't get the 2.0 release stablized. In fact, I
-see SWIG-2.0 as a necessary step for moving forward with these ideas.
-
-<h3>We need your help! Yes, you.</h3>
-
-Nobody gets paid to work on SWIG. The developers are volunteers who
-work in their spare time. Furthermore, SWIG is not supported by
-investors, a large corporation, or research grants. I work on it
-because it's fun, challenging, and useful. I presume that other
-developers do the same. However, we only have limited resources and
-we need your help.
-
-<ul>
-<li><p>
-If you like SWIG and find it useful, we need you to try new versions.
- We want you to torture test the releases and to break them. We need
- bug reports. No bug is too obscure or unimportant---we *will* fix it
- if we can. We also need feedback about things that are annoying or
- compatibility features that might help in going from 1.1 to 2.0.
-
-<li><p> We need help with documentation, examples, testing, libraries, and all
- sorts of other aspects of the release. Even if you have never
- written a SWIG language module or dived into its implementation,
- there are many ways that you can help. Consider writing a case study
- about how you wrapped a big library. Contribute tests that break the
- implementation in horrible ways. Help with the web page or FAQ.
-
-<li><p> Most of the SWIG-1.3.x work has focused on the SWIG core. However, as
- the 2.0 release nears, we will be working on a variety of enhancements
- to the language modules. If there are things you would like to see
- in any of the language modules, you need to let us know.
-
-<li><p> There are SWIG language modules that have not made it into the
- distribution. Examples that I know about include ITCL, Swig-Eiffel,
- and Swig-Lua. We would gladly make these part of the standard SWIG
- distribution. However, we also need help to do it. Porting from
- SWIG-1.1 is no easy task, but we're more than willing to help. It's
- not as bad as one might imagine.
-
-<li><p> We are always looking for developers. Subscribe to
- to the <a href="mail.html">swig-dev</a> mailing list
- or send me email to get involved.
-</ul>
-
-<h3>Acknowledgements</h3>
-
-I'd just like to thank everyone who has submitted feedback, bugs, made
-contributions, and put up with my occasional thrashing over the years.
-I welcome any comments about this document and how we can make SWIG even
-better.
-
-<p>
-Dave Beazley (beazley@cs.uchicago.edu) <br>
-June 2, 2002
-
diff --git a/swigweb/guilty.ht b/swigweb/guilty.ht
deleted file mode 100644
index 857f270..0000000
--- a/swigweb/guilty.ht
+++ /dev/null
@@ -1,189 +0,0 @@
-Guilty Parties
-
-<p><img src="images/guilty.png" alt="Guilty Parties">
-
-<p>
-<b>Active Developers</b>
-
-<table cellpadding=0 cellspacing=8 width="100%" border=0 summary="Developer mugshots">
-<tr>
-<td>
-<img src="images/Dave3.jpg" alt="Dave Beazley"><br>
-<b>Dave Beazley (Chicago, Illinois).</b><br>
-SWIG core, type system, Python, Tcl, Perl.
-</td>
-<td>
-<img src="images/luigi.jpg" alt="Luigi Ballabio"><br>
-<b>Luigi Ballabio (Milano, Italy).</b><br>
-STL libraries (Python, Ruby, MzScheme, Guile).
-</td>
-</tr>
-
-<tr>
-<td>
-<img src="images/fulton3.jpg" alt="William Fulton"><br>
-<b>William Fulton (Bath, UK).</b> <br>
-Java and C# modules. Cygwin/Windows.
-</td>
-<td>
-<img src="images/lyle.jpg" alt="Lyle Johnson"><br>
-<b>Lyle Johnson (Madison, Alabama).</b><br>
-Ruby module.
-</td>
-</tr>
-
-<tr>
-<td>
-<img src="images/mkoeppe.jpg" alt="Matthias Köppe"><br>
-<b>Matthias Köppe (Magdeburg, Germany).</b> <br>
-Guile module.
-</td>
-<td>
-<img src="images/lenz.jpg" alt="John Lenz (Madison, Wisconsin)"><br>
-<b>John Lenz</b> <br>
-Chicken, Guile, and MzScheme modules, runtime type system.
-</td>
-</tr>
-
-<tr>
-<td>
-<img src="images/marcelo.jpg" alt="Marcelo Matus"><br>
-<b>Marcelo Matus (ACMS, Tuscon, AZ).</b> <br>
-Evil C++ testing, SWIG core, template support, STL,
-Python, and Ruby and Tcl when needed
-</td>
-<td>
-<img src="blank.jpg" alt="Blank"><br>
-<b>Jason Stewart (Albuquerque, New Mexico).</b> <br>
-Perl module.
-</td>
-</tr>
-
-<tr>
-<td>
-<img src="images/arty.jpg" alt="Art Yerkes"><br>
-<b>Art Yerkes (Chicago, Illinois).</b> <br>
-OCAML module.
-</td>
-<td>
-<img src="images/yoshiki.jpg" alt="Shibukawa Yoshiki"><br>
-<b>Shibukawa Yoshiki (Tokyo, Japan).</b> <br>
-Japanese translation.
-</td>
-</tr>
-</table>
-
-<p>
-<b>Students</b>
-<ul>
-<li>Songyan Feng (Chicago).
-<li>Xinghua Shi (Chicago).
-<li>Jing Cao (Chicago).
-<li>Aquinas Hobor (Chicago).
-</ul>
-
-<p>
-<b>Major contributors</b>
-
-<ul>
-<li>Thien-Thi Nguyen
-<li>Loic Dachary
-<li>Oleg Tolmatcev
-<li>Masaki Fukushima
-<li>Edward Zimmermann
-<li>David Ascher
-<li>John Buckman
-<li>Kevin Butler
-<li>Dominique Dumont
-<li>Pier Giorgio Esposito
-<li>David Fletcher
-<li>Gary Holt
-<li>Harco de Hilster
-<li>Dustin Mitchell
-<li>Ian Cooke
-<li>Hasan Baran Kovuk
-<li>Klaus Wiederänders
-<li>Richard Palmer
-<li>Sam Liddicott
-</ul>
-
-<p>
-<b>Bug reports and patches</b>
-<blockquote>
-Adam Hupp,
-Brad Clements,
-Brett Williams,
-Buck Hodges,
-Burkhard Kloss,
-Chia-Liang Kao,
-Craig Files,
-Dennis Marsa,
-Dieter Baron,
-Drake Diedrich,
-Fleur Diana Dragan,
-Gary Pennington,
-Geoffrey Hort,
-Gerald Williams,
-Greg Anderson,
-Greg Kochanski,
-Greg Troxel,
-Henry Rowley.
-Irina Kotlova,
-Israel Taller,
-James Bailey,
-Jim Fulton,
-Joel Reed,
-Jon Travis,
-Junio Hamano,
-Karl Forner,
-Keith Davidson,
-Krzysztof Kozminski,
-Larry Virden,
-Magnus Ljung,
-Marc Zonzon,
-Marcio Luis Teixeira
-Mark Howson,
-Micahel Scharf,
-Michel Sanner,
-Mike Romberg,
-Mike Simons,
-Mike Weiblen,
-Paul Brannan,
-Ram Bhamidipaty,
-Reinhard Fobbe,
-Rich Wales,
-Richard Salz,
-Robin Dunn,
-Roy Lecates,
-Rudy Albachten,
-Scott Drummonds
-Scott Michel,
-Shaun Lowry,
-Steve Galser,
-Tal Shalif,
-Tarn Weisner Burton,
-Tony Seward,
-Uwe Steinmann,
-Vadim Chugunov,
-Wyss Clemens,
-Zhong Ren.
-</blockquote>
-
-<p><b>Friends</b>
-<ul>
-<li>The F street crew
-<li>Peter Lomdahl
-<li>Tim Germann
-<li>Chris Myers
-<li>John Schmidt
-<li>Paul Dubois
-<li>Kurtis Bleeker
-<li>Larry Virden
-<li>Peter-Pike Sloan
-<li>Patrick Tullmann
-</ul>
-
-Apologies to anyone missed....
-
-
-
diff --git a/swigweb/history.ht b/swigweb/history.ht
deleted file mode 100644
index 5181030..0000000
--- a/swigweb/history.ht
+++ /dev/null
@@ -1,66 +0,0 @@
-SWIG History
-
-<p>
-<img src="images/history.png" alt="History">
-
-<p>
-Just the facts:
-
-<ul>
-<li>July, 1995. Dave develops SWIG while working in the Theoretical
-Physics Division at Los Alamos National Laboratory. Originally, it
-was conceived as an extension building tool for a customized scripting
-language that had been created for the Connection Machine 5.
-
-<li>January, 1996. SWIG rewritten in C++ at the University of Utah and expanded to cover Tcl, Perl, and Guile.
-
-<li>February, 1996. First alpha release.
-
-<li>September, 1996. Version 1.0 released. Support for Python added.
-
-<li>September, 1997. Version 1.1 released with a variety of improvements such as shadow classes.
-
-<li>February, 1998. SWIG1.1p5 released.
-
-<li>1997-1999. Various unsuccessful attempts to create SWIG2.0.
-Aside from various second system effects, there were other
-distractions such as a dissertation and searching for a job. All
-of this work was abandoned although parts of it are found in
-newer SWIG releases.
-
-<li>July, 1998. SWIG development moves to the University of Chicago.
-
-<li>January 1, 2000. Dave survives his most pleasant Y2K flight to Chicago O'Hare.
-
-<li>February 11, 2000. SWIG1.3 alpha released. This is the first in
-a series of releases that slowly migrate most of SWIG's implementation
-back to ANSI C.
-
-<li>March 1, 2000. SWIG1.3a2 released.
-<li>June 18, 2000. SWIG1.3a3 released.
-<li>September 4, 2000. SWIG1.3a4 released.
-<li>September 22, 2000. SWIG1.3a5 released.
-<li>July 9, 2001. SWIG-1.3.6 released.
-<li>September 3, 2001. SWIG-1.3.7 released. Support for templates and better
-handling of overloaded functions added.
-<li>September 23, 2001. SWIG-1.3.8 released.
-<li>September 25, 2001. SWIG-1.3.9 released.
-<li>December 10, 2001. SWIG-1.3.10 released.
-<li>January 31, 2002. SWIG-1.3.11 released.
-<li>June 2, 2002. SWIG-1.3.12 released.
-<li>June 17, 2002. SWIG-1.3.13 released.
-<li>August 12, 2002. SWIG-1.3.14 released.
-<li>September 9, 2002. SWIG-1.3.15 released.
-<li>October 14, 2002. SWIG-1.3.16 released.
-<li>November 22, 2002. SWIG-1.3.17 released.
-<li>March 23, 2003. SWIG-1.3.18 released.
-<li>March 28, 2003. SWIG-1.3.19 released.
-<li>December 17, 2003. SWIG-1.3.20 released.
-<li>January 17, 2004. SWIG-1.3.21 released.
-<li>September 4, 2004. SWIG-1.3.22 released.
-<li>November 11, 2004. SWIG-1.3.23 released.
-<li>December 14, 2004. SWIG-1.3.24 released.
-<li>June 11, 2005. SWIG-1.3.25 released.
-</ul>
-
-
diff --git a/swigweb/images/Dave2.jpg b/swigweb/images/Dave2.jpg
deleted file mode 100644
index 8800386..0000000
--- a/swigweb/images/Dave2.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/Dave3.jpg b/swigweb/images/Dave3.jpg
deleted file mode 100644
index 514ca55..0000000
--- a/swigweb/images/Dave3.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/arty.jpg b/swigweb/images/arty.jpg
deleted file mode 100644
index 07f3554..0000000
--- a/swigweb/images/arty.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/bleed.png b/swigweb/images/bleed.png
deleted file mode 100644
index bf2a015..0000000
--- a/swigweb/images/bleed.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/bugs.png b/swigweb/images/bugs.png
deleted file mode 100644
index de6c0fb..0000000
--- a/swigweb/images/bugs.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/burngifs.png b/swigweb/images/burngifs.png
deleted file mode 100644
index cbd6167..0000000
--- a/swigweb/images/burngifs.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/coderuns.png b/swigweb/images/coderuns.png
deleted file mode 100644
index 74a4d84..0000000
--- a/swigweb/images/coderuns.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/codeworks.png b/swigweb/images/codeworks.png
deleted file mode 100644
index c29e9ab..0000000
--- a/swigweb/images/codeworks.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/compat.png b/swigweb/images/compat.png
deleted file mode 100644
index 4c3d1fd..0000000
--- a/swigweb/images/compat.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/copyright.png b/swigweb/images/copyright.png
deleted file mode 100644
index 7743f1c..0000000
--- a/swigweb/images/copyright.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/cure.png b/swigweb/images/cure.png
deleted file mode 100644
index 8b8f0a5..0000000
--- a/swigweb/images/cure.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/cvs.png b/swigweb/images/cvs.png
deleted file mode 100644
index 312b212..0000000
--- a/swigweb/images/cvs.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/doc.png b/swigweb/images/doc.png
deleted file mode 100644
index a327315..0000000
--- a/swigweb/images/doc.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/download.png b/swigweb/images/download.png
deleted file mode 100644
index a772b4b..0000000
--- a/swigweb/images/download.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/exec.png b/swigweb/images/exec.png
deleted file mode 100644
index ffe16db..0000000
--- a/swigweb/images/exec.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/faq.png b/swigweb/images/faq.png
deleted file mode 100644
index 1152b1f..0000000
--- a/swigweb/images/faq.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/fulton3.jpg b/swigweb/images/fulton3.jpg
deleted file mode 100644
index ab90738..0000000
--- a/swigweb/images/fulton3.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/guilty.png b/swigweb/images/guilty.png
deleted file mode 100644
index 4da1e5b..0000000
--- a/swigweb/images/guilty.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/history.png b/swigweb/images/history.png
deleted file mode 100644
index 499f612..0000000
--- a/swigweb/images/history.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/isl.png b/swigweb/images/isl.png
deleted file mode 100644
index f8fb825..0000000
--- a/swigweb/images/isl.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/lenz.jpg b/swigweb/images/lenz.jpg
deleted file mode 100644
index bb1195b..0000000
--- a/swigweb/images/lenz.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/links.png b/swigweb/images/links.png
deleted file mode 100644
index 865bc69..0000000
--- a/swigweb/images/links.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/luigi.jpg b/swigweb/images/luigi.jpg
deleted file mode 100644
index eb9d343..0000000
--- a/swigweb/images/luigi.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/lyle.jpg b/swigweb/images/lyle.jpg
deleted file mode 100644
index fcd4be9..0000000
--- a/swigweb/images/lyle.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/mail.png b/swigweb/images/mail.png
deleted file mode 100644
index 99b7b99..0000000
--- a/swigweb/images/mail.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/marcelo.jpg b/swigweb/images/marcelo.jpg
deleted file mode 100644
index bb5c36b..0000000
--- a/swigweb/images/marcelo.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/mkoeppe.jpg b/swigweb/images/mkoeppe.jpg
deleted file mode 100644
index 0562432..0000000
--- a/swigweb/images/mkoeppe.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/projects.png b/swigweb/images/projects.png
deleted file mode 100644
index f2aa7a9..0000000
--- a/swigweb/images/projects.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/propaganda.png b/swigweb/images/propaganda.png
deleted file mode 100644
index d53129d..0000000
--- a/swigweb/images/propaganda.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/rants.png b/swigweb/images/rants.png
deleted file mode 100644
index e6ebcc4..0000000
--- a/swigweb/images/rants.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/raves.png b/swigweb/images/raves.png
deleted file mode 100644
index 5ba6461..0000000
--- a/swigweb/images/raves.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/sam.jpg b/swigweb/images/sam.jpg
deleted file mode 100644
index 9044567..0000000
--- a/swigweb/images/sam.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/screen.png b/swigweb/images/screen.png
deleted file mode 100644
index 06c7a72..0000000
--- a/swigweb/images/screen.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/screenshot.png b/swigweb/images/screenshot.png
deleted file mode 100644
index a3ee9c5..0000000
--- a/swigweb/images/screenshot.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/screenshot2.png b/swigweb/images/screenshot2.png
deleted file mode 100644
index 9aaf67d..0000000
--- a/swigweb/images/screenshot2.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/subversion.png b/swigweb/images/subversion.png
deleted file mode 100644
index 4f242cd..0000000
--- a/swigweb/images/subversion.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig10.png b/swigweb/images/swig10.png
deleted file mode 100644
index 326cb2e..0000000
--- a/swigweb/images/swig10.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig11.png b/swigweb/images/swig11.png
deleted file mode 100644
index b898d36..0000000
--- a/swigweb/images/swig11.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig12.png b/swigweb/images/swig12.png
deleted file mode 100644
index 1b97b74..0000000
--- a/swigweb/images/swig12.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig13.png b/swigweb/images/swig13.png
deleted file mode 100644
index ed49098..0000000
--- a/swigweb/images/swig13.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig15.png b/swigweb/images/swig15.png
deleted file mode 100644
index a36a425..0000000
--- a/swigweb/images/swig15.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig16.png b/swigweb/images/swig16.png
deleted file mode 100644
index 73f3adc..0000000
--- a/swigweb/images/swig16.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig17.png b/swigweb/images/swig17.png
deleted file mode 100644
index e0385bf..0000000
--- a/swigweb/images/swig17.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig7.png b/swigweb/images/swig7.png
deleted file mode 100644
index 71a97bb..0000000
--- a/swigweb/images/swig7.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swig8.png b/swigweb/images/swig8.png
deleted file mode 100644
index a9e5021..0000000
--- a/swigweb/images/swig8.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swigfiles.png b/swigweb/images/swigfiles.png
deleted file mode 100644
index 20baa5e..0000000
--- a/swigweb/images/swigfiles.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/swigorg.png b/swigweb/images/swigorg.png
deleted file mode 100644
index 59b7933..0000000
--- a/swigweb/images/swigorg.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/tutorial.png b/swigweb/images/tutorial.png
deleted file mode 100644
index 68c9155..0000000
--- a/swigweb/images/tutorial.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/y2k.png b/swigweb/images/y2k.png
deleted file mode 100644
index 1ac1522..0000000
--- a/swigweb/images/y2k.png
+++ /dev/null
Binary files differ
diff --git a/swigweb/images/yoshiki.jpg b/swigweb/images/yoshiki.jpg
deleted file mode 100644
index 8f958a5..0000000
--- a/swigweb/images/yoshiki.jpg
+++ /dev/null
Binary files differ
diff --git a/swigweb/index.ht b/swigweb/index.ht
deleted file mode 100644
index da14bf0..0000000
--- a/swigweb/index.ht
+++ /dev/null
@@ -1,219 +0,0 @@
-Simplified Wrapper and Interface Generator
-
-<h2>Welcome to SWIG</h2>
-
-[ <a href="http://swig-jp.dyndns.org">Japanese</a> ]
-
-<p>
-SWIG is a software development tool that connects programs written in
-C and C++ with a variety of high-level programming
-languages. SWIG is used with different types of languages including common scripting languages such as
-Perl, PHP, Python, Tcl, Ruby and PHP. The list of
-<a href="compat.html#SupportedLanguages">supported languages</a> also includes
-non-scripting languages such as C#, Common Lisp (CLISP, Allegro CL, UFFI), Java, Modula-3 and OCAML. Also several
-interpreted and compiled Scheme implementations (Guile, MzScheme, Chicken)
-are supported. SWIG is most
-commonly used to create high-level interpreted or compiled programming
-environments, user interfaces, and as a tool for testing and prototyping C/C++
-software. SWIG can also export its parse tree in the form of XML and
-Lisp s-expressions. SWIG may be freely used, distributed, and modified for commercial
-and non-commercial use.
-
-<ul>
-<li> <a href="survey.html">Download</a> the latest version.
-<li> <a href="doc.html">Documentation, papers, and presentations</a>
-<li> <a href="compare.html">Features</a>.
-<li> <a href="mail.html">Mailing Lists</a>
-<li> <a href="bugs.html">Bug tracking</a>
-<li> <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SwigWiki!</a>
-</ul>
-
-<h3>News</h3>
-
-
-<p>
-<b>2005/06/11</b>
-SWIG-1.3.25 has been released. This largely contains bug fixes and enhancements to the C# module and the runtime type system.
-
-<p>
-<b>2005/03/25</b>
-Greg Stein gives a <a href=http://www.sauria.com/~twl/conferences/pycon2005/20050325/Python%20at%20Google.notes>keynote speech</a> about Google's use of Python and SWIG at the PyCon 2005 conference.
-
-<p>
-<b>2004/12/14</b>
-SWIG-1.3.24 has been released. This is mainly a bug fix release.
-
-<p>
-<b>2004/11/11</b>
-SWIG-1.3.23 has been released. This release contains additional C++ support in the areas of templates and
-namespaces. Java and C# are added to the list of languages that can create wrappers taking advantage of
-C++ default arguments. Many other minor bug fixes and enhancements are also included.
-
-<p>
-<b>2004/09/04</b>
-SWIG-1.3.22 has been released. This release continues the ongoing improvements and bug fixes in SWIG.
-The major areas of improvement are in exception handling, enums and the STL. New languages with this
-release are Allegro CL and Modula-3. The documentation has been revamped and it is now
-available in the following formats: single html page, multiple html pages and a pdf
-document.
-
-<p>
-<b>2004/01/11</b>
-SWIG-1.3.21 has been released. This is a minor bug fix release.
-
-<p>
-<b>2003/12/17</b>
-SWIG-1.3.20 has been released. This release includes a large number of enhancements including
-improved C++ support, directors, contracts, and more.
-
-<p>
-<b>2003/12/17</b>
-An article by Phil Tomson about SWIG and Ruby appears in the January 2004 issue of <a href="http://www.cuj.com">C/C++ Users Journal.</a>
-
-<p>
-<b>2003/10/27</b>
-The Code Generation Network undertakes an
-<a href="http://www.codegeneration.net/tiki-read_article.php?articleId=33">interview</a> talking about SWIG.
-
-<p>
-<b>2003/03/28</b>
-SWIG-1.3.19 has been
-released. This release fixes a small number of critical bugs in 1.3.18.
-
-<p>
-<b>2003/03/23</b>
-SWIG-1.3.18 has been
-released. This release includes a number of new language modules (C# and Chicken), new features, an improved
-build environment, and a lot of minor bug fixes.
-
-<p>
-<b>2002/11/27</b>
-An article about SWIG appears in <a href="http://www.cmagazine.jp/contents/200212.html">C Magazine</a> (Japanese).
-
-<p>
-<b>2002/11/27</b>
-Bernard Desgraupes has created a Macintosh version of SWIG-1.3.17. Download <a href="http://webperso.easyconnect.fr/bdesgraupes/Downloads/MacSwig_Carbon_1.3.17.hqx">here</a>.
-
-<p>
-<b>2002/11/22</b>
-SWIG-1.3.17 has been
-released. This is mostly a bug-fix release for 1.3.16.
-
-<p>
-<b>2002/10/14</b>
-SWIG-1.3.16 has been
-released. This is mostly a bug-fix release for 1.3.15.
-
-<p>
-<b>2002/10/01</b>
-Mitchell Charity has created <a href="http://www.vendian.org/mncharity/dir3/inline/swig/">Inline::SWIG</a> for Perl. Check it out.
-
-<p>
-<b>2002/09/10</b>
-SWIG-1.3.15 has been
-released. This is mostly a bug-fix release for 1.3.14 that resolves a number
-of issues with template and namespace support. Improvements to exception handling and overloading are also included.
-
-<p>
-<b>2002/08/12</b>
-SWIG-1.3.14 has been
-released. SWIG development continues to break new ground--this release features
-full support for overloaded methods and functions, C++ smart pointers, and more. It also
-includes new language modules for Ocaml and XML as well as a variety of enhancements to
-existing modules.
-
-
-<p>
-<b>2002/07/19</b>
-Shibukawa Yoshiki is working on a Japanese translation of the SWIG documentation. Check out
-<a href="http://swig-jp.dyndns.org/">swig-jp.dyndns.org</a>.
-
-<p>
-<b>2002/06/17</b>
-SWIG-1.3.13
-has been released. This is a more stable version of SWIG-1.3.12. If you downloaded
-SWIG-1.3.12, you should upgrade.
-
-<p>
-<b>2002/06/02</b>
-<a href="Doc1.3/index.html">Updated documentation</a> for SWIG-1.3.12 is online.
-
-<p>
-<b>2002/06/02</b>
-SWIG-1.3.12
-has been released. This is the most capable SWIG release ever! New
-features include support for C++ namespaces, enhanced support for C++
-templates, new library files, updated documentation, and a huge number of minor enhancements.
-See the <a href="survey.html">download</a> page for release notes
-and versions for Windows and Macintosh.
-
-<p>
-<b>2002/04/03</b> Robert Tolbert has contributed PDF and postscript versions of the SWIG-1.3.11 documentation. Check it out.
-
-<p>
-<b>2002/02/01</b> SWIG-1.3.11 has been released. This is a bug-fix release for SWIG-1.3.10. The release also
-includes substantial improvements to the Java and PHP modules.
-See the <a href="survey.html">download</a> page for release notes and versions for Windows and Macintosh.
-
-<p>
-<b>2001/12/10</b> SWIG-1.3.10 has been
-released. This release features substantial changes to typemaps, exception
-handling, and SWIG's internals. New features also include support for C++ operator
-overloading and an experimental PHP module. Since this is an unstable
-release, first time users might want to consider using SWIG-1.3.9 or
-SWIG1.1p5 instead.
-See the <a href="survey.html">download</a> page for release notes and versions for Windows and Macintosh.
-
-
-<P>
-<b>2001/12/10</b> The <a href="Doc1.3">development documentation</a> for SWIG-1.3 has been extensively updated. Not yet finished, but includes coverage of most
-new SWIG features including the redesigned typemap system and
-improved exception handling.
-
-<p>
-<b>2001/10/31</b> Announcing <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">SwigWiki</a>.
-Problems with SWIG? Look here for more information and to contribute.
-
-<p>
-<b>2001/09/28</b> <a href="Doc1.3">Development documentation</a> for SWIG-1.3 is now online. This is a work in progress, but many new SWIG features
-are described.
-
-<p>
-<b>2001/09/23</b> SWIG-1.3.9 has been
-released. This is a bug-fix release for 1.3.7 (described below).
-See the <a href="survey.html">download</a> page for release notes and versions for Windows and Macintosh. Note: SWIG-1.3.8 had a major parsing problem that
-snuck in at the last moment--don't use that version.
-
-<p>
-<b>2001/09/03</b> SWIG-1.3.7 has been
-released. This is one of the most substantial enhancements to SWIG ever released. Includes a more
-powerful parser, support for C++ templates, simplified wrapping of overloaded methods and more!
-This release also includes some updated documentation on the new features. See the <a href="survey.html">download</a> page for release notes and versions for Windows and Macintosh.
-
-
-<p>
-<b>2001/08/30</b> A precompiled executable of SWIG-1.3.6 for Windows (swigwin-1.3.6) is now available.
-
-
-<p>
-<b>2001/07/16</b> A Macintosh port of SWIG-1.3.6 (macswig-1.3.6)
-has been contributed by Luigi Ballabio.
-
-<p>
-<b>2001/07/10</b> SWIG-1.3.6 has been released. This release includes substantial changes
-to the language modules and greatly improved support for Guile, Java, and
-Ruby. Please see the <a href="survey.html">download</a> page for further details.
-
-<p>
-<b>2000/10/14</b> A Macintosh port of SWIG1.3a5 (macswig1.3a5) has been contributed by Luigi Ballabio.
-
-
-<p>
-<b>2000/09/22</b> SWIG1.3a5
-has been released. This release has too many changes to list here,
-but it fixes a lot of bugs in SWIG1.3a3 and SWIG1.3a4, includes new language modules
-for Ruby and Mzscheme, and has some new examples. Note: this is a somewhat
-unstable release and may not be suitable for first time users.
-Download SWIG-1.1 instead.
-
-
diff --git a/swigweb/link.txt b/swigweb/link.txt
deleted file mode 100644
index 1759506..0000000
--- a/swigweb/link.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-#index.ht#:(3/1/00) SWIG1.3a2 has been released! Download now from <a href="http://download.sourceforge.net/swig/swig1.3a2.tar.gz">SourceForge</a>. Note: this is an unstable release and is not recommended for first-time users. Download <a href="ftp://www.swig.org/pub/swig1.1p5.tar.gz">SWIG1.1p5</a> instead.
-doc.ht:<a href="ftp://ftp.swig.org/pub">FTP</a> site.
-doc.html: <a href="ftp://ftp.swig.org/pub">FTP</a> site.
-download.ht:<li> <a href="ftp://ftp.swig.org/pub">ftp.swig.org/pub</a> (Master site).
-download.ht:<a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">SWIG 1.1p5</a>
-download.ht:<li> <a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">swig1.1p5.tar.gz</a>. The full distribution including documentation and examples.
-download.ht:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_pdf.tar.gz">swigdoc1.1_pdf.tar.gz</a>. PDF documentation (included in the full distribution).
-download.ht:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_ps.tar.gz">swigdoc1.1_ps.tar.gz</a>. Postscript documentation.
-download.ht:<li> <a href="ftp://ftp.swig.org/pub/MacSWIG1.1p2.sea.hqx">MacSWIG1.1p2.sea.hqx</a>. SWIG for the Power Macintosh (experimental).
-download.html: <li> <a href="ftp://ftp.swig.org/pub">ftp.swig.org/pub</a> (Master site).
-download.html: <a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">SWIG 1.1p5</a>
-download.html: <li> <a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">swig1.1p5.tar.gz</a>. The full distribution including documentation and examples.
-download.html: <li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_pdf.tar.gz">swigdoc1.1_pdf.tar.gz</a>. PDF documentation (included in the full distribution).
-download.html: <li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_ps.tar.gz">swigdoc1.1_ps.tar.gz</a>. Postscript documentation.
-download.html: <li> <a href="ftp://ftp.swig.org/pub/MacSWIG1.1p2.sea.hqx">MacSWIG1.1p2.sea.hqx</a>. SWIG for the Power Macintosh (experimental).
-download.ht~:<li> <a href="ftp://ftp.swig.org/pub">ftp.swig.org/pub</a> (Master site).
-download.ht~:<a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">SWIG 1.1p5</a>
-download.ht~:<li> <a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">swig1.1p5.tar.gz</a>. The full distribution including documentation and examples.
-download.ht~:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_pdf.tar.gz">swigdoc1.1_pdf.tar.gz</a>. PDF documentation (included in the full distribution).
-download.ht~:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_ps.tar.gz">swigdoc1.1_ps.tar.gz</a>. Postscript documentation.
-download.ht~:<li> <a href="ftp://ftp.swig.org/pub/MacSWIG1.1p2.sea.hqx">MacSWIG1.1p2.sea.hqx</a>. SWIG for the Power Macintosh (experimental).
-feedback.htm:<input type=hidden name="recipient" value="swig@swig.org">
-guestbook.cgi:$guestbookurl = "http://swig.org/guestbk.htm";
-guestbook.cgi:$cgiurl = "http://swig.org/cgi-bin/guestbook.cgi";
-index.ht~:(3/1/00) SWIG1.3a2 has been released! Download now from <a href="http://download.sourceforge.net/swig/swig1.3a2.tar.gz">SourceForge</a>. Note: this is an unstable release and is not recommended for first-time users. Download <a href="ftp://www.swig.org/pub/swig1.1p5.tar.gz">SWIG1.1p5</a> instead.
-index1.html:<b><a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">Download</a> SWIG1.1p5 now!</b>
-index1.html:<!-- host --> www.swig.org is generously hosted by <a href="http://www.pns.cc">Professional Net Service</a>.
-index2.html:<!-- host --> www.swig.org is generously hosted by <a href="http://www.pns.cc">Professional Net Service</a>.
-search.cgi:$baseurl = 'http://swig.org/';
-search.cgi:$title = "swig.org";
-search.cgi:$title_url = 'http://swig.org/';
-search.cgi:$search_url = 'http://swig.org/search.htm';
-source.html:<li> <a href="ftp://ftp.swig.org/pub">ftp.swig.org/pub</a> (Master site).
-source.html:<a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">SWIG 1.1p5</a>
-source.html:<li> <a href="ftp://ftp.swig.org/pub/swig1.1p5.tar.gz">swig1.1p5.tar.gz</a>. The full distribution including documentation and examples.
-source.html:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_pdf.tar.gz">swigdoc1.1_pdf.tar.gz</a>. PDF documentation (included in the full distribution).
-source.html:<li> <a href="ftp://ftp.swig.org/pub/swigdoc1.1_ps.tar.gz">swigdoc1.1_ps.tar.gz</a>. Postscript documentation.
-source.html:<li> <a href="ftp://ftp.swig.org/pub/MacSWIG1.1p2.sea.hqx">MacSWIG1.1p2.sea.hqx</a>. SWIG for the Power Macintosh (experimental).
-swig.ht:<!-- host --> www.swig.org is generously hosted by <a href="http://www.pns.cc">Professional Net Service</a>.
-swig.html: <!-- host --> www.swig.org is generously hosted by <a href="http://www.pns.cc">Professional Net Service</a>.
diff --git a/swigweb/links.ht b/swigweb/links.ht
deleted file mode 100644
index 503b5ba..0000000
--- a/swigweb/links.ht
+++ /dev/null
@@ -1,106 +0,0 @@
-SWIG Related Links
-
-<p>
-<img src="images/links.png" alt="Links">
-
-<H3> Projects </H3>
-
-Lots of people <a href="projects.html">use SWIG</a>.
-
-
-<H3> Language related links </h3>
-
-<blockquote>
-
-The <a href="http://www.scriptics.com"> Tcl/Tk </a> homepage at Scriptics<br>
-The <a href ="http://www.python.org"> Python </a> homepage. <br>
-<a href="http://www.perl.org"> The Perl Institute</a> <br>
-<a href="http://republic.perl.com"> The Programming Republic of Perl</a>. <br>
-<a href="http://www.perl.com/CPAN/CPAN.html"> CPAN (Comprehensive Perl Archive Network)</a> <br>
-<a href="http://starship.python.net"> Starship Python</a> <br>
-
-<a href="http://www.neosoft.com/tcl/default.html"> Tcl/Tk Contributed Sources Archive </a> <br>
-<a href="http://www.sco.com/Technology/tcl/Tcl.html"> Tcl/Tk Information </a> <br>
-<a href="http://www.gnu.org/software/guile/guile.html">Guile</a> homepage. <br>
-<a href="http://www.cs.rice.edu/CS/PLT/packages/mzscheme/">MzScheme</a> homepage<br>
-<a href="http://www.ruby-lang.org/">Ruby</a> homepage. <br>
-<a href="http://java.sun.com/">Java</a> homepage at Sun. <br>
-<a href="http://www.php.net/">PHP</a> homepage. <br>
-<a href="http://www.call-with-current-continuation.org/chicken.html">CHICKEN</a> homepage. <br>
-<a href="http://www.schemers.org/"> schemers.org </a> - a collection of resources for the Scheme programming language <br>
-</blockquote>
-
-<h3> Code generators and other interesting packages</h3>
-
-<blockquote>
-The <a href="ftp://ftp.parc.xerox.com/pub/ilu/ilu.html"> ILU </a> homepage (Xerox PARC) <br>
-<a href="http://www.fpx.de/fp/Software/tclobj"> TclObj </a> <br>
-<a href="http://www.amath.washington.edu/~lf/software/tcl++">Modular Tcl</a><br>
-<a href="http://lnc.usc.edu/~holt/matwrap/">Matwrap</a>. A wrapper
-generator for matrix languages. <br>
-<a href="http://www.riverbankcomputing.co.uk/sip">SIP</a>. A wrapper generator
-for integrating C++ libraries with Python. <br>
-<a href="http://cxx.sourceforge.net">CXX</a>. A C++ friendly extension API for Python.<br>
-<a href="http://pyfortran.sourceforge.net">pyfort</a>. A wrapper generator for interfacing Fortran with Python.<br>
-<a href="http://www.acl.lanl.gov/siloon">SILOON</a>. A wrapper generation tool
-with some ambitious goals for C++.<br>
-<a href="http://www9.informatik.uni-erlangen.de/eng/research/rendering/vision/itcl/">Itcl++</a>.
-A wrapper generator for interfacing C++ with [incr Tcl].<br>
-
-<a href="http://www.hlla.is.tsukuba.ac.jp/~chiba/openc++.html">OpenC++</a>. A very cool compiler project that lets you crawl inside C++ parse trees and more. <br>
-<a href="http://www.stack.nl/~dimitri/doxygen">Doxygen</a>. Generate documentation and more for C/C++ programs.<br>
-<a href="http://www.cs.cmu.edu/~chrislee/Software/g-wrap/">G-Wrap</a>. A wrapper generator for interfacing C and Scheme (including Guile).<br>
-
-<a href="http://cens.ioc.ee/projects/f2py2e">f2py</a>. An interface generator for binding Fortran and Python.<br>
-
-<a href="http://www.boost.org/libs/python/doc/index.html">Boost Python Library</a>. A very interesting approach to
-C++ wrapper generation that uses template metaprogramming. <br>
-
-<a href="http://www.deaven.net/~deaven/Software/cxxwrap/">cxxwrap</a>. Java JNI wrapper code generator for C++.<br>
-<a href="http://www.excelsior-usa.com/xfunction.html">xFunction</a>. Java native code access library.<br>
-<a href="http://www.gnu.org/software/gcc/java/index.html">GCJ</a>. Gnu Compiler for Java - Part of GCC 3.0 and later. C++ and Java can be easily mixed together - Java objects are C++ objects and all Java classes are C++ classes using CNI, the alternative to JNI.<br>
-<a href="http://inline.perl.org">Inline</a>. Perl programmers will definitely want to take a look at
-this module--especially if you're making simple C/C++ extensions.<br>
-<a href="http://www.kd-dev.com/~eic/">EiC</a>. Embeddable, extensible and pointer-safe C interpreter with an interface to compiled C code.<br>
-<a href="http://root.cern.ch/root/Cint.html">CINT</a>. C/C++ interpreter with an interface to compiled C/C++ code.<br>
-
-<a href="http://public.kitware.com/Cable">CABLE</a>. A wrapper
-generator for C++ that uses GCC-XML to provide Tcl wrappers for almost
-all C++ features. There are plans to support more languages so be
-sure to check it out.
-<br>
-
-<a href="http://www.scipy.org/site_content/weave">Weave</a>. A tool for inlining C/C++ code into Python scripts. Very cool.<br>
-
-<a href="http://www.tecgraf.puc-rio.br/~celes/tolua">Tolua</a>. Connect C/C++ programs to the Lua progamming language.<br>
-
-<a href="http://www.cs.fsu.edu/~engelen/soap.html">gSOAP</a>. A compiler for deploying C/C++ programs as SOAP web services. <br>
-
-<a href="http://www.softintegration.com">Ch</a>. An embeddable C/C++ interpreter (commercial). <br>
-
-<a href="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/">Pyrex</a>. A language for writing Python extension modules.<br>
-
-<a href="http://elmer.sourceforge.net">Elmer</a>. Glue code generator so that Python modules can run in C and Tcl programs.<br>
-
-<a href="http://www.sourceforge.net/projects/swigxmltocom">SwigXmlToCom</a>. Tool that uses SWIG to generate COM wrappers.<br>
-
-</blockquote>
-
-<h3> Other interesting links</h3>
-
-<blockquote>
-
-John Ousterhout's <a href="http://home.pacbell.net/ouster/scripting.html"> paper </a> on scripting languages
-(appeared in IEEE Computer). <br>
-<A HREF="http://SAL.KachinaTech.COM/"> SAL - Scientific Applications on Linux</a>. <br>
-<a href="http://www.usenix.org">USENIX</a> <br>
-<a href="http://www.mathtools.net">Mathtools.net</a> A technical computing portal for all scientific and engineering needs. Contains useful links to technical computing programmers, covering C/C++, Java, Excel, MATLAB, Fortran and others.<br>
-</blockquote>
-
-<b>I am always on the lookout for projects that are either related to SWIG
-or which provide alternative solutions to the problem of wrapping C/C++ code.
-Please drop me a line if there are other projects that
-should be linked here. -- Dave</b>
-
-
-
diff --git a/swigweb/mail.ht b/swigweb/mail.ht
deleted file mode 100644
index 848b0f8..0000000
--- a/swigweb/mail.ht
+++ /dev/null
@@ -1,90 +0,0 @@
-SWIG Mailing Lists
-
-<p><img src="images/mail.png" alt="Mail">
-
-<p>
-
-There are a number of mailing lists available. Please use them for any queries related to the use or development of SWIG.
-
-<p>
-<b>Important</b>. The mailing lists are set with a very high level of spam rejection, meaning occasionally some SWIG user's email postings will be discarded. Emails classified as spam are quietly discarded, so please check the archives if you are unsure as to whether or not your email was successfully posted. Note that only plain text emails should be sent, that is html, rtf etc formatted emails will be quietly discarded. The mailing lists are also subscriber only lists, so you must subscribe to the relevant list in order to post to that list.
-
-<p>
-To subscribe to any of the mailing lists or view the archives, use the links on the left column.
-<br>
-<br>
-
-<table BORDER="1" summary="Maling lists">
-<tr>
-<td><font size="+1">List</font></td>
-<td><font size="+1">Purpose</font></td>
-</tr>
-
-<tr>
-<td>
-<a href="http://www.cs.uchicago.edu/mailman/listinfo/swig">swig</a>
-</td>
-<td>
-General discussion and queries about SWIG.
-</td>
-</tr>
-
-<tr>
-<td>
-<a href="http://www.cs.uchicago.edu/mailman/listinfo/swig-dev">swig-dev</a>
-</td>
-<td>
-SWIG Development discussion list. This mailing list used to contain the CVS commits, but these are now on the swig-cvs mailing list.
-</td>
-</tr>
-
-<tr>
-<td>
-<a href="http://lists.sourceforge.net/lists/listinfo/swig-cvs">swig-cvs</a>
-</td>
-<td>
-SWIG CVS list. CVS commits are mailed to this list.
-</td>
-</tr>
-
-</table>
-
-<h2>Searching the mailing lists</h2>
-<p>
-The mailing lists can be searched in various different ways.
-</p>
-
-<p>
-<a href="http://www.gmane.org">Gmane</a> archives many mailing lists including the swig mailing list.
-You can use Gmane to <a href="http://dir.gmane.org/gmane.comp.programming.swig">search the swig mailing list</a> archives
-or just browse the list online as if the list was a newsgroup.
-Note that only the swig mailing list can be queried as the swig-dev mailing list is not currently archived by Gmane.
-</p>
-
-<p>
-Google can be used to search the site that hosts the swig and swig-dev mailing list archives.
-</p>
-
-<!-- SiteSearch Google -->
-<FORM method=GET action="http://www.google.com/search">
-<input type=hidden name=ie value=UTF-8>
-<input type=hidden name=oe value=UTF-8>
-<TABLE bgcolor="#FFFFFF"><tr><td>
-<A HREF="http://www.google.com/">
-<IMG SRC="http://www.google.com/logos/Logo_40wht.gif"
-border="0" ALT="Google"></A>
-</td>
-<td>
-<INPUT TYPE=text name=q size=31 maxlength=255 value="">
-<INPUT type=submit name=btnG VALUE="Google Search">
-<font size=-1>
-<input type=hidden name=domains value="mailman.cs.uchicago.edu"><br><input type=radio name=sitesearch value=""> the web <input type=radio name=sitesearch value="mailman.cs.uchicago.edu" checked> mailman.cs.uchicago.edu (swig and swig-dev mailing lists) <br>
-</font>
-</td></tr></TABLE>
-</FORM>
-<!-- SiteSearch Google -->
-
-<p>
-The Sourceforge <a href=http://sourceforge.net/mailarchive/forum.php?forum=swig-cvs>swig-cvs mailing list archive</a> has a facility to search the swig-cvs list archives.
-</p>
-
diff --git a/swigweb/makeweb.py b/swigweb/makeweb.py
deleted file mode 100755
index 70f167b..0000000
--- a/swigweb/makeweb.py
+++ /dev/null
@@ -1,105 +0,0 @@
-#!/usr/local/bin/python
-# Make the SWIG web-pages
-#
-# Okay. Yet another bogus rewrite of Barry's work
-
-import string
-import glob
-import os
-import time
-import stat
-
-def makepage(filename):
- name, suffix = os.path.splitext(filename)
- f = open("default.html")
- page = f.read()
- f.close()
-
- # Read in the body file
- f = open(filename)
- body = f.readlines()
- f.close()
- title = body[0]
- body = string.join(body[1:])
- page = string.replace(page,"$title",title)
- page = string.replace(page,"$body",body)
-
- # Read in the corner file
- try:
- f = open(name+".corner")
- corner = f.read()
- f.close()
- except IOError:
- try:
- f = open("default.corner")
- corner = f.read()
- f.close()
- except:
- corner = ""
-
- page = string.replace(page,"$corner",corner)
-
- # Read in the top file
- try:
- f = open(name+".top")
- top = f.read()
- f.close()
- except IOError:
- try:
- f = open("default.top")
- top = f.read()
- f.close()
- except:
- top = ""
-
- page = string.replace(page,"$top",top)
-
- # Read in the side file
- try:
- f = open(name+".side")
- side = f.read()
- f.close()
- except IOError:
- try:
- f = open("default.side")
- side = f.read()
- f.close()
- except:
- side = ""
-
- page = string.replace(page,"$side",side)
-
- # Read in the footer file
- try:
- f = open(name+".footer")
- footer = f.read()
- f.close()
- except IOError:
- try:
- f = open("default.footer")
- footer = f.read()
- f.close()
- except:
- footer = ""
-
- page = string.replace(page,"$footer",footer)
-
- mtime = os.stat(filename)[stat.ST_MTIME]
- mstr = time.ctime(mtime)
-
- page = string.replace(page,"$mtime",mstr);
-
- # Write out the page
- f = open(name+".html","w")
- f.write(page)
- f.close()
- print "Wrote ", name+".html"
-
-files = glob.glob("*.ht")
-
-for f in files:
- makepage(f)
-
-
-
-
diff --git a/swigweb/myths.ht b/swigweb/myths.ht
deleted file mode 100644
index f34b6c5..0000000
--- a/swigweb/myths.ht
+++ /dev/null
@@ -1,220 +0,0 @@
-SWIG Myths
-
-<h2>SWIG Myths</h2>
-
-<p>
-Here are some common misconceptions about SWIG that have occasionally
-appeared on other web pages and in articles--especially those that
-describe older SWIG versions.
-
-<h4><font color="#ff0000">Myth: SWIG only really works with ANSI C</font></h4>
-
-<h4>Fact:</h4>
-
-SWIG <em>does</em> provide wrapping support for all of ANSI C. However, SWIG has
-also included C++ support since its initial release in 1996. To be fair, early
-SWIG releases had limitations, but C++ support has continually improved with
-each SWIG release.
-
-<p>
-C++ support in current SWIG releases is quite advanced--providing support for nearly
-every C++ feature including templates, namespaces, operators, overloaded methods,
-and more. The only major C++ feature not supported is nested classes---and we're
-working on that. See the <a href="compare.html">Features</a> page for more information.
-
-<h4><font color="#ff0000">Myth: SWIG wraps C++ into this unusable
-low-level "C-tran" interface.</font></h4>
-
-<h4>Fact:</h4>
-
-When wrapping C++, SWIG <em>does</em> generate a set of low-level procedural
-wrappers. However, these are only used as building blocks for
-creating a more advanced high-level wrappers (in fact, users rarely
-interact with this layer directly). In nearly all target languages,
-SWIG wraps C++ classes into a nice object-oriented interface that
-mirrors the underlying C++ code. In Python, C++ classes
-are wrapped as Python classes, in Perl, C++ classes are wrapped as
-Perl classes, and so forth. The existence of procedural wrappers is
-only an artifact of SWIG's layered approach to wrapper code generation.
-
-<h4><font color="#ff0000">Myth: SWIG doesn't support overloaded methods/functions</font></h4>
-
-<h4>Fact:</h4>
-
-SWIG provides full support for C++ overloaded methods and functions.
-For example, if you have declarations like this:
-
-<blockquote>
-<pre>
-class Foo {
-public:
- Foo();
- Foo(const Foo &);
- void spam(int x);
- void spam(double x);
- void spam(char *x, int n);
-};
-</pre>
-</blockquote>
-
-They can be used in a completely natural way from most SWIG language modules. For example,
-in Python:
-
-<blockquote>
-<pre>
->>> f = Foo()
->>> f.spam(3)
->>> f.spam(3.5)
->>> f.spam("hello",5)
->>> g = Foo(f) # Make a copy
-</pre>
-</blockquote>
-
-Or in Tcl:
-
-<blockquote>
-<pre>
-% Foo f
-% f spam 3
-% f spam 3.5
-% f spam "hello" 5
-% Foo g f
-</pre>
-</blockquote>
-
-The SWIG implementation of overloading utilizes type categories and a
-type precedence scheme that results in the generation of dynamic
-dispatch functions. The order in which declarations appear does not matter nor
-does SWIG rely on unreliable mechanisms like trial execution (i.e., trying methods
-one by one until one happens to execute successfully). Overloading support in SWIG
-is more advanced than that.
-
-<P>
-Due to the dynamic nature of scripting languages, it is not possible to
-fully disambiguate overloaded methods to the same degree as in C++.
-For example, you might have declarations like this:
-
-<blockquote>
-<pre>
-int foo(int);
-long foo(long);
-</pre>
-</blockquote>
-
-In this case, SWIG provides a number of directives to either rename or ignore
-one of the declarations. For example:
-
-<blockquote>
-<pre>
-%ignore foo(long);
-</pre>
-</blockquote>
-
-or
-
-<blockquote>
-<pre>
-%rename(foo_long) foo(long);
-</pre>
-</blockquote>
-
-<h4><font color="#ff0000">Myth: SWIG doesn't support basic idiomatic C++ constructs like templates and smart pointers</font></h4>
-
-<h4>Fact:</h4>
-
-SWIG fully supports templates. However, to wrap a template class, you have to
-tell SWIG about a particular instantiation. This is easy, just make sure SWIG
-knows about the template definition and include a special directive like this:
-
-<blockquote>
-<pre>
-%template(deque_int) std::deque<int>;
-</pre>
-</blockquote>
-
-In this case, "deque_int" becomes the target language name for the wrapped object.
-You would use it just like a normal class in the extension module:
-
-<blockquote>
-<pre>
->>> d = deque_int(100)
->>> d.size()
-100
->>>
-</pre>
-</blockquote>
-
-On the subject of smart-pointers, those are supported too. For example, suppose
-you had some code like this:
-
-<blockquote>
-<pre>
-class Foo {
-public:
- int x;
- int spam(int x);
-};
-
-template<class T> class SmartPtr {
-public:
- ...
- T *operator->();
- ...
-};
-
-typedef SmartPtr<Foo> FooPtr;
-
-FooPtr make_Foo();
-</pre>
-</blockquote>
-
-To wrap this with SWIG, just tell it about a template instantiation. For example:
-
-<blockquote>
-<pre>
-%template(FooPtr) SmartPtr<Foo>;
-</pre>
-</blockquote>
-
-Now, in the target language, the wrapper object works just like you would expect:
-
-<blockquote>
-<pre>
->>> f = make_Foo()
->>> f.x = 3
->>> f.spam(42)
-</pre>
-</blockquote>
-
-
-<h4><font color="#ff0000">Myth: SWIG is just too confusing to use</font></h4>
-
-<h4>Fact:</h4>
-
-Most users find SWIG to be relatively easy to use. However, confusion can arise
-from the following:
-
-<ul>
-<li><p>C programming. To effectively use SWIG, you should have a good grasp of
-basic C programming concepts like pointers, arrays, memory management, data structures,
-functions, parameter passing semantics, and so forth. SWIG tries to make it easy for
-C programmers to build extension modules, but it does not try to make C programming
-easy.
-
-<li><p>C++. This language is so large and complicated that certain parts of SWIG
-may not make any sense unless you are also familiar with the underlying C++ concepts.
-
-<li><p>Dynamic linking and shared libraries. To build extension modules, you usually
-have to create DLLs. If you've never done this before, there is a small
-learning curve associated with finding the right compiler and linker options.
-
-<li><p>Customization features. SWIG provides a large number of customization features and
-options that can be used to control almost all parts of the wrapper generation
-process. These are provided to better support power users and to provide the
-flexibility needed to solve difficult real-world wrapping problems. However,
-none of this is needed to get started.
-
-</ul>
-
-
-
diff --git a/swigweb/nsf.ht b/swigweb/nsf.ht
deleted file mode 100644
index 0b41be6..0000000
--- a/swigweb/nsf.ht
+++ /dev/null
@@ -1,61 +0,0 @@
-SWIG and Typesystems
-
-<h2>SWIG and Typesystems</h2>
-
-<p>
-For the past seven years, a considerable amount of effort has gone
-into the development of SWIG and its support for various programming
-languages. Currently, more than a <a href="guilty.html">dozen developers</a> work on the system
-and there are thousands of users. However, almost all of SWIG's development
-has been relatively ad-hoc---primarily driven by feature requests from
-users. As SWIG's original author, coordinating all of this chaos has
-always been a bit of challenge. In fact, it's been rather difficult to even
-describe what SWIG "is" and "how it works" without using terms like
-"magic" and, well, "more magic." Needless to say, this isn't the most
-academic way to look it ;-).
-
-<p>
-A little over a year ago, I became interested in the relationship
-between SWIG and work in the area of type systems. In order
-to support advanced C++ features like namespaces and templates, a
-significant amount of very difficult development work focused on the
-SWIG type system. Moreover, this work resulted in a lot of old SWIG
-features being folded into type system extensions. Because of this
-work, I have now come to view SWIG as being mostly driven as an
-extension of the C++ type system rather than an extension of a C++
-parser. This difference is subtle, but it is the only way to really
-understand how SWIG works at a fundamental level.
-
-<p>
-To the best of my knowledge, no one working on automatic C/C++ wrapper
-generators has really approached the wrapping problem from the
-standpoint of type systems. Instead, everyone seems to focus on the problem
-of <em>parsing</em> C++, which, although important, is not enough to
-really understand what is going on.
-
-<p>
-Starting in the summer of 2003, the NSF will be funding a
-<a href="http://www.fastlane.nsf.gov/servlet/showaward?award=0237835">research
-project</a> at the University of Chicago to explore the relationship
-between type-systems and wrapper generation in more detail. A lot of
-this work will involve SWIG and the semantics of its underlying type
-system. Moreover, this work will be exploring some exciting new
-features such as software contracts and improved mixed-language
-debugging support. We're also going to try and make connections
-between SWIG and related work in the area of programming languages.
-
-<p>
-What does this mean for the future of SWIG? Well, my hope is that
-this work will make the system more capable, more reliable, and more
-useful than ever. I think everyone will be pleasantly surprised with
-some of the changes.
-
-<p>
-As always, I'd like to acknowledge everyone who has contributed to SWIG
-over the years---thank you for your support!
-
-<p>
-Cheers,
-<p>
-Dave Beazley <br>
-March 23, 2003
diff --git a/swigweb/papers/Perl98/readme b/swigweb/papers/Perl98/readme
deleted file mode 100755
index d22d8f7..0000000
--- a/swigweb/papers/Perl98/readme
+++ /dev/null
@@ -1,24 +0,0 @@
-Perl Extension Building with SWIG
-
-Authors : David Beazley
- David Fletcher
- Dominique Dumont
-
-Contact : Dave Beazley
- beazley@cs.utah.edu
- (801) 359-5705
-
-Session : Perl Internals and Linking to C
- Thursday, August 20, 1:30 pm.
-
-
-The presentation consists of a paper about SWIG
-and its use with Perl. Three files are available :
-
-swigperl.html - HTML Version of the paper
-swigperl.ps - Postscript version (2 column)
-swigperl.pdf - PDF Version of the postscript paper
-
-The HTML version contains links to the postscript and PDF
-versions.
-
diff --git a/swigweb/papers/Perl98/swigperl.htm b/swigweb/papers/Perl98/swigperl.htm
deleted file mode 100755
index 03c9ce8..0000000
--- a/swigweb/papers/Perl98/swigperl.htm
+++ /dev/null
@@ -1,2198 +0,0 @@
-<html>
-<title> Perl Extension Building with SWIG </title>
-<body bgcolor="#ffffff">
-<h1> Perl Extension Building with SWIG</h1>
-
-(Presented at the O'Reilly Perl Conference 2.0, August 17-20, 1998, San Jose, California.)
-<p>
-
-<b> David M. Beazley </b> <br>
-<em> Dept. of Computer Science <br>
-University of Chicago <br>
-Chicago, IL 60637 <br>
-</em>
-
-<p>
-<b> David Fletcher </b> <br>
-<em>Fusion MicroMedia, Corp. <br>
-Longmont, CO 80501 <br>
-</em>
-
-<p>
-<b>Dominique Dumont</b> <br>
-<em> Hewlett Packard <br>
-Lab TID <br>
-5 Ave Raymond Chanas <br>
-38053 Grenoble cedex <br>
-France <br> </em>
-
-<p>
-[ <a href="swigperl.pdf">PDF </a> ]
-
-<h2> Abstract </h2>
-
-<em>
-SWIG (Simplified Wrapper and Interface Generator) is a freely available
-tool that integrates Perl, Python, Tcl, and other scripting languages
-with programs written in C, C++, and Objective-C. This paper
-provides an introduction to SWIG and shows how it can be used to
-construct Perl extension modules. In addition, a number of applications
-in which SWIG has been utilized are described. While SWIG is similar
-to other Perl extension building tools such as xsubpp and h2xs, SWIG
-has a number of unique features that help simplify the task of creating
-Perl extension modules. Many of these features are described as well as
-limitations and future directions.
-This paper is
-primarily intended for developers who are interested in combining Perl
-with applications written in C or C++ as well as current SWIG users
-who are interested in learning more about some of SWIG's advanced features.
-</em>
-
-<h2> 1 Introduction </h2>
-
-One of Perl's greatest strengths is its ability to simplify hard
-programming tasks as well as being able to solve the odd and varied
-computing problems that occur on a day-to-day basis. While it would
-be nice to use Perl (or other high-level languages) for everything,
-this is simply not practical for many applications. In fact,
-performance critical tasks, low-level systems programming, and
-complex data structures are likely to be implemented
-in a compiled language such as C or C++ (and may be easier to manage
-in such languages). Furthermore, developers often need to work with a
-wide variety of existing applications and ``legacy'' systems that
-are written in such languages.
-
-<p>
-The integration of Perl and code written in compiled languages has a
-number of practical benefits. First, it allows existing C/C++
-applications to be incorporated into a high-level interpreted
-environment. This environment provides greater flexibility and often
-simplifies development since debugging and testing can be performed
-using Perl scripts. Second, Perl can serve as a powerful user
-interface. In other words, rather than writing a user interface
-from scratch, it is possible to use a Perl interpreter instead.
-This also allows other for other possibilities such as graphical
-user interface development with Perl/Tk. Finally, Perl
-provides developers with a mechanism for assembling and controlling
-software components. Rather than creating a huge monolithic package,
-C/C++ programs can be packaged as collections of Perl extension
-modules. As a result, programs become more modular and easier to
-maintain. Furthermore, it is even possible to combine entirely
-different programs together within a shared Perl interpreter.
-
-
-<p>
-This paper provides an introduction and overview of SWIG, a tool
-designed to integrate C code with a variety of scripting
-languages including Perl, Python, and Tcl. Currently, SWIG can
-construct Perl extension modules on Unix and Windows-NT systems. It also
-supports the ActiveState Perl for Windows and Perl4. SWIG has been
-freely available since February, 1996 and has been
-previously described in <em>Advanced Perl Programming</em>, <em>The
-Perl Journal</em>, and <em>Dr. Dobb's Journal</em>[1,2,3].
-In addition, SWIG is packaged with a 300 page user manual describing its
-use [4]. The goal of this paper is not to repeat all of this information, but to provide an overview of
-SWIG, demonstrate the use of some of its more advanced features, and describe
-some of the ways that it is currently being used. The authors include the developer
-of SWIG and two of SWIG's foremost Perl experts who have made substantial
-contributions to SWIG's development.
-
-<h2> 2 Perl Extension Building </h2>
-
-To interface Perl with code written in C or C++, it is
-necessary to write wrappers that serve as a glue layer between
-the Perl interpreter and the underlying C code. These wrappers
-are responsible for converting data between Perl and C, reporting
-errors, and other tasks. Perl is packaged with several tools
-for creating these wrappers. One such tool is <tt>xsubpp</tt>, a
-compiler that takes interface definitions written in a special
-language known as XS and converts them into wrappers. For example,
-suppose that you had the following C function:
-
-<blockquote><pre>
-int fact(int n);
-</pre></blockquote>
-
-To wrap this function into a Perl module with <tt>xsubpp</tt>, you would write
-the following XS file:
-
-<blockquote><pre>
-/* file : example.xs */
-extern int fact(int n);
-MODULE = Example PACKAGE = Example
-int
-fact(n)
- int n
-</pre></blockquote>
-
-When processed with <tt>xsubpp</tt>, the following wrapper file is produced
-
-<blockquote><pre>
-#include "EXTERN.h"
-#include "perl.h"
-#include "XSUB.h"
-extern int fact(int n);
-
-XS(XS_Example_fact)
-{
- dXSARGS;
- if (items != 1)
- croak("Usage: Example::fact(n)");
- {
- int n = (int)SvIV(ST(0));
- int RETVAL;
- RETVAL = fact(n);
- ST(0) = sv_newmortal();
- sv_setiv(ST(0), (IV)RETVAL);
- }
- XSRETURN(1);
-}
-
-XS(boot_Example)
-{
- dXSARGS;
- char* file = __FILE__;
- XS_VERSION_BOOTCHECK ;
- newXS("Example::fact",
- XS_Example_fact, file);
- ST(0) = &sv_yes;
- XSRETURN(1);
-}
-</pre></blockquote>
-
-To use the module, the wrapper code must be compiled and linked into a
-shared library that can be dynamically loaded into the Perl interpreter.
-The easiest way to do this is with the MakeMaker utility by writing a
-script as follows:
-
-<blockquote><pre>
-# file : Makefile.PL
-use ExtUtils::MakeMaker;
-WriteMakefile(
- 'NAME' => 'Example',
- 'OBJECT' => 'example.o fact.o'
-);
-</pre></blockquote>
-
-this script is then used to create a Makefile and module as follows:
-
-<blockquote><pre>
-unix > perl Makefile.PL
-unix > make
-unix > make install
-</pre></blockquote>
-
-Finally, in addition to creating the C component of the extension module,
-it is necessary to write a <tt>.pm</tt> file that is used to load
-and initialize the module. For example,
-
-<blockquote><pre>
-# file : Example.pm
-package Example;
-require Exporter;
-require DynaLoader;
-@ISA = qw(Exporter DynaLoader);
-bootstrap Example;
-1;
-</pre></blockquote>
-
-At this point, you should have a working Perl extension module. In
-principle, building a Perl extension requires an XS specification for
-every C function that is to be accessed. To simplify the process of
-creating these specifications, Perl includes <tt>h2xs</tt>, a tool that
-converts C header files to XS descriptions. While useful, <tt>h2xs</tt>
-is somewhat limited in its ability to handle global variables,
-structures, classes, and more advanced C/C++ features. As a result,
-<tt>h2xs</tt> can be somewhat difficult to use with more complex
-applications.
-
-<h2> 3 SWIG Overview </h2>
-
-In a nutshell, SWIG is a specialized compiler that transforms ANSI
-C/C++ declarations into scripting language extension wrappers.
-While
-somewhat similar to <tt>h2xs</tt>, SWIG has a number of
-notable differences. First, SWIG is much less internals oriented than
-XS. In other words, SWIG interfaces can usually be constructed
-without any knowledge of Perl's internal operation. Second, SWIG is designed to
-be extensible and general purpose. Currently, wrappers can be
-generated for Perl, Python, Tcl, and Guile. In addition, experimental
-modules for MATLAB and Java have been developed. Finally, SWIG
-supports a larger subset of C and C++ including structures,
-classes, global variables, and inheritance. This section provides a tour of SWIG and describes many
-of its interesting features.
-
-<h3> 3.1 A Small Taste</h3>
-
-As a first example, suppose that you wanted to build a Perl
-interface to Thomas Boutell's gd graphics library [footnote:
-The gd library is a freely available graphics library for
-producing GIF images and can be obtained at <tt>
-<a href="http://www.boutell.com/gd/gd.html">
-http://www.boutell.com/gd/gd.html</a></tt>. A Perl module to gd,
-developed by Lincoln Stein, is also available on CPAN so
-interested readers are encouraged to compare the results of
-using SWIG against an existing Perl extension.]
-
-<p>
-Since gd is a C library,
-images are normally created by writing C code such as
-follows:
-
-<blockquote><pre>
-#include "gd.h"
-int main() {
- gdImagePtr im;
- FILE *out;
- int blk,wht;
-
- /* Create an image */
- im=gdImageCreate(200,200);
-
- /* Allocate some colors */
- blk=gdImageColorAllocate(im,0,0,0);
- wht=gdImageColorAllocate(im,255,255,255);
-
- /* Draw a line */
- gdImageLine(im,20,50,180,140,wht);
-
- /* Output the image */
- out=fopen("test.gif","wb");
- gdImageGif(im,out);
- fclose(out);
-
- /* Clean up */
- gdImageDestroy(im);
-}
-</pre></blockquote>
-
-By building a Perl interface to gd, our goal is to write similar code
-in Perl. Thus, the functionality of the gd library must be exposed to
-the Perl interpreter. To do this, a SWIG interface
-file can be written as follows:
-
-<blockquote><pre>
-// File : gd.i
-%module gd
-%{
-#include "gd.h"
-%}
-
-typedef gdImage *gdImagePtr;
-
-gdImagePtr gdImageCreate(int sx, int sy);
-void gdImageDestroy(gdImagePtr im);
-void gdImageLine(gdImagePtr im,
- int x1, int y1,
- int x2, int y2,
- int color);
-int gdImageColorAllocate(gdImagePtr im,
- int r, int g, int b);
-void gdImageGif(gdImagePtr im, FILE *out);
-
-// File I/O functions (explained shortly)
-FILE *fopen(char *name, char *mode);
-void fclose(FILE *);
-</pre></blockquote>
-
-In this file, the ANSI C prototypes for every function that we would
-like to access from Perl are listed.
-In addition, a number of SWIG
-directives (which are always preceded by a ``%'') appear. The <tt>
-%module</tt> directive specifies the name of the extension module. The
-<tt>%{, %}</tt> block is used to insert literal code into the output
-wrapper file [footnote : This syntax is derived from lex and yacc]. In
-this case, we simply include the ``<tt>gd.h</tt>'' header file.
-Finally, a few file
-I/O functions also appear. While not part of gd, these functions
-are needed to manufacture file handles used by several gd functions.
-
-<p>
-To run SWIG, the following command is executed:
-
-<blockquote><pre>
-unix > swig -perl5 gd.i
-Generating wrappers for Perl 5
-</pre></blockquote>
-
-
-This produces two files, <tt>gd_wrap.c</tt> and
-<tt>gd.pm</tt>. The first file contains C wrapper
-functions that appear similar to the output that
-would have been generated by <tt>xsubpp</tt>.
-The
-<tt>.pm</tt> file contains supporting Perl code needed to
-load and use the module.
-
-<p>
-To build the module,
-the wrapper file is compiled and linked into a shared library.
-This process varies on every machine (consult the man pages), but the following
-steps are performed on Linux:
-
-<blockquote><pre>
-unix > gcc -fpic -c gd_wrap.c \
- -Dbool=char \
- -I/usr/lib/perl5/i586-linux/5.004/CORE
-unix > gcc -shared gd_wrap.o -lgd -o gd.so
-</pre></blockquote>
-
-At this point, the module is ready to use. For example,
-the earlier C program can be directly translated into the
-following Perl script:
-
-<blockquote><pre>
-#!/usr/bin/perl
-use gd;
-
-# Create an image
-$im = gd::gdImageCreate(200,200);
-
-# Allocate some colors
-$blk=gd::gdImageColorAllocate($im,0,0,0);
-$wht=gd::gdImageColorAllocate($im,255,
- 255,255);
-
-# Draw a line
-gd::gdImageLine($im,20,50,180,140,$wht);
-
-# Output the image
-$out=gd::fopen("test.gif","wb");
-gd::gdImageGif($im,$out);
-gd::fclose($out);
-
-# Clean up
-gd::gdImageDestroy($im);
-</pre></blockquote>
-
-<h3> 3.2 Input Files</h3>
-
-In the gd example, SWIG was given a special interface file
-containing a list of the C declarations to be included
-in the Perl module. When working with a large C library, interface
-files can often be constructed by copying an
-existing header file and modifying it slightly. However, in some
-cases, it is possible to include a header file as follows:
-
-<blockquote><pre>
-%module
-%{
-#include "gd.h"
-%}
-
-// Grab the declarations from gd.h
-%include "gd.h"
-
-// Some file I/O functions
-FILE *fopen(char *name, char *mode);
-void fclose(FILE *);
-</pre></blockquote>
-
-The <tt>%include</tt> directive tells SWIG to include a file and
-parse all of the declarations it contains. In this case, the
-interface would now wrap every function in the gd library
-as opposed to the half-dozen functions listed in the first example.
-
-<p>
-SWIG also includes a C preprocessor that can be used for macro
-expansion and conditional compilation. If a new application is
-being written with SWIG in mind, header files can be written as
-follows:
-
-<blockquote><pre>
-#ifdef SWIG
-%module gd
-%{
-#include "gd.h"
-%}
-#endif
-
-/* C declarations */
-...
-</pre></blockquote>
-
-With this approach, the file can serve as both a valid C header
-file and as an interface specification. The <tt>SWIG</tt> symbol
-is only defined when SWIG is parsing so special directives can be
-easily hidden from the C compiler as needed.
-
-<p>
-Finally, for the truly lazy, SWIG can sometimes be run directly on
-C header and source files. For example,
-
-<blockquote><pre>
-% swig -perl5 -module gd gd.h
-% swig -perl5 -module example example.c
-</pre></blockquote>
-
-Most users, however, use a mix of dedicated interface files
-and header files.
-
-<h3> 3.3 Data Model</h3>
-
-The most critical part of interfacing Perl to C programs is
-the management of data. Since Perl and C utilize a different set of
-internal datatypes, wrapper generators are responsible for producing
-code that marshals data and objects between languages. For fundamental types
-such as <tt>int</tt> and <tt>double</tt> the conversion process is
-straightforward. However, pointers, arrays, structures, and objects
-complicate the process. Furthermore, since most C/C++ programs
-make extensive use of these datatypes, it is important for wrapper generators
-to support as many of these datatypes as possible.
-
-<h4> 3.3.1 Pointers</h4>
-
-SWIG maps C pointers and C++ references into Perl blessed references. These references
-contain both the value of the pointer itself, plus a type-signature.
-In the gd example, pointers were used to manage both images
-and files. If one were to print out the value a pointer, it would
-appear as follows:
-
-<blockquote><pre>
-gdImagePtr=SCALAR(0x80b9914)
-</pre></blockquote>
-
-SWIG uses the type-signature to perform run-time checking of all pointer values. These checks emulate
-many of the checks that would have been performed by a C compiler.
-When an invalid Perl datatype
-or pointer of invalid type is used, a run-time error is generated. For example,
-
-<blockquote><pre>
-% perl
-use gd;
-$f = gd::fopen("test.gif","w");
-gd::gdImageLine($f,20,50,180,140,0);
-Type error in argument 1 of gdImageLine.
-Expected gdImagePtr. at - line 3.
-</pre></blockquote>
-
-Type-checking is based on the name of each datatype. However,
-the type-checker also keeps track of C++ inheritance hierarchies and
-<tt>typedef</tt> definitions. Thus, an acceptable pointer type includes any
-alternate names that might have been created with a <tt>typedef</tt>
-declaration as well as any derived datatypes in C++.
-
-<p>
-When pointers are manipulated in Perl, they are opaque values. That
-is, pointers can be created and passed around to other C functions,
-but they can not be dereferenced directly. Thus, in the example, it
-is difficult (or impractical) for a user to directly manipulate the internal
-representation of an image from the Perl interpreter. Furthermore,
-SWIG, by default, handles all pointers in a uniform manner. Thus,
-datatypes such as <tt>FILE *</tt> are represented as blessed references
-even though such types may appear remarkably similar to other Perl
-datatypes such as file handles.
-
-<h4> 3.3.2 Arrays</h4>
-
-SWIG maps all arrays into pointers where the ``value'' of an array
-is simply a pointer to the first element in the array. This is
-the same model used by C compilers and like C, SWIG performs no
-bounds or size checking. Thus, a function such as
-
-<blockquote><pre>
-void foo(double a[4][4]);
-</pre></blockquote>
-
-would accept <em>any</em> object of type <tt>double *</tt>. It is
-up to the user to ensure that the pointer is valid and that it
-points to memory that has been properly allocated.
-
-<h4> 3.3.3 Structures and Objects</h4>
-
-Finally, all structures and objects are represented as
-pointers. This includes cases where objects are manipulated
-by value. For example, the functions
-
-<blockquote><pre>
-double dot_product(Vector a, Vector b);
-Vector cross_product(Vector a, Vector b);
-</pre></blockquote>
-
-
-are transformed by SWIG into the following wrappers [footnote: When
-C++ is used, SWIG uses the default copy constructor instead of
-<tt>malloc</tt>]:
-
-<blockquote><pre>
-double
-wrap_dot_product(Vector *a, Vector *b) {
- return dot_product(*a,*b);
-}
-Vector *
-wrap_cross_product(Vector *a, Vector *b) {
- Vector *r;
- r = (Vector *) malloc(sizeof(Vector));
- *r = cross_product(*a,*b);
- return r;
-}
-</pre></blockquote>
-
-The representation of objects by reference avoids
-the problem of marshaling objects between a C and Perl representation--a
-process that would be extremely difficult for
-very complicated C datatypes. It also provides better performance
-since manipulating references is more efficient than copying object
-data back and forth between languages. Finally, the use of references
-closely matches the way in which most C/C++ programs already handle
-objects.
-
-<p>
-The downside to this approach is that objects are opaque in Perl.
-This prevents users from examining their contents directly. In
-addition, SWIG wrappers occasionally need to perform implicit memory
-allocations as shown above. It is up the user to free the resources
-used by such functions (or learn to live with a memory leak). Of
-course, this naturally brings us to the next topic.
-
-<h4> 3.3.4 Memory Management</h4>
-
-SWIG maintains a strict separation between the management of Perl and C
-objects. While Perl uses reference counting to keep track of its
-own objects, this scheme is not extended to C/C++
-extensions created with SWIG. Thus, when Perl destroys a blessed
-reference containing the value of a C pointer, only the pointer
-value disappears, not the underlying C data that it points to.
-
-<p>
-From a user standpoint, SWIG generated C/C++ extensions follow the
-same memory management rules as the underlying application.
-Thus, if a program relies on <tt>malloc</tt> and <tt>free</tt> to allocate
-and deallocate objects, these will also be used from the Perl
-interpreter. Likewise, a C++ extension typically requires
-explicit invocation of constructors and destructors. Furthermore, for
-functions that implicitly allocate memory as in the previous section,
-it is up to the user to explicitly destroy the result using <tt>
-free</tt> or a C++ destructor. While such a scheme may seem problematic,
-it is no less problematic than memory management in C (which may or
-may not be a good thing depending on your point of view). Even if
-it were possible to have Perl automatically manage C/C++ objects, this
-would be an inherently dangerous affair--especially since Perl has no
-way to know how an underlying C application really operates. Furthermore, it
-would be a fatal error for Perl to deallocate objects that were still
-in use.
-Therefore, SWIG leaves memory management largely up the user.
-
-<h4> 3.3.5 Pointers, Arrays, and Perl</h4>
-
-A common confusion among some novice users is the difference between
-C datatypes and similar Perl datatypes.
-In particular, Perl references are not the
-same as a C pointers and Perl arrays are not the same as C arrays. Differences
-also apply to other datatypes such as files (this is the reason that
-the simple example included prototypes for <tt>fopen</tt> and <tt>fclose</tt>).
-The primary reason for
-these differences is that objects in Perl have a different internal
-representation than objects in C. For example, a Perl array is
-represented as a collection of references to Perl objects which may be of mixed
-types. The internal representation of this array is entirely
-different than what would be used for a normal C array. Therefore, it
-is impossible to take a Perl array and pass it in unmodified form to
-an arbitrary C function.
-
-<p>
-The difference between Perl and C datatypes often arises with
-C functions such as the following:
-
-<blockquote><pre>
-/* Plot some points */
-void
-plotpts(gdImagePtr im, int x[], int y[],
- int npts, int c)
-{
- for (int i = 0; i < npts; i++) {
- gdImageSetPixel(im,x[i],y[i],c);
- }
-}
-</pre></blockquote>
-
-
-Ideally, a user might want to pass Perl arrays as arguments
-as follows:
-
-<blockquote><pre>
-@a = (10,20,30,40);
-@b = (50,70,60,200);
-gd::plotpts($im,\@a,\@b,4,1); # Error!
-</pre></blockquote>
-
-
-However, this script generates a type error instead of acting
-as one might expect. While such behavior may seem restrictive
-or bizarre, SWIG has been deliberately designed to operate
-in this manner. In fact, there are even benefits to this approach.
-If Perl arrays were to be used as C arrays, a
-copy would be made, verified for type-correctness, and deallocated every
-time an array was passed to a C function. For large arrays, this would
-introduce a substantial performance overhead. Space requirements are
-also a concern for some C programs. For example, a numerical application
-might manipulate arrays with millions of elements. Converting such
-arrays to and from a Perl representation would clearly introduce substantial memory
-and performance overhead. In contrast, manipulating pointers to such arrays
-is easy and efficient.
-
-<p>
-It should also be noted that SWIG provides a variety of customization options
-that can be used to change its behavior. In fact, one can even make SWIG map
-Perl arrays into C arrays if desired. Therefore, most restrictions
-can be eliminated with a little extra work. Some of these customization techniques are
-described shortly.
-
-<h3> 3.4 Helper Functions </h3>
-
-Sometimes the Perl interface constructed by SWIG is lacking in
-functionality or is difficult to use. For example, in the previous
-section, a function operating on C arrays was presented. To construct
-C arrays from Perl, it is necessary to add some additional
-functions to the SWIG interface. This can be done using the
-<tt>%inline</tt> directive as follows:
-
-<blockquote><pre>
-// Add some helper functions for C arrays
-%inline %{
-int *int_array(int size) {
- return (int *) malloc(sizeof(int)*size);
-}
-void int_destroy(int *a) {
- free(a);
-}
-void int_set(int *a, int i, int val) {
- a[i] = val;
-}
-int int_get(int *a, int i) {
- return a[i];
-}
-%}
-</pre></blockquote>
-
-When SWIG builds the scripting interface, these functions
-become part of the extension module and can be used as follows:
-
-<blockquote><pre>
-# Convert a Perl array into a C int array
-sub create_array {
- $len = scalar(@_);
- $ia = gd::int_array($len);
- for ($i = 0; $i < $len; $i++) {
- val = shift;
- gd::int_set($ia,$i,$val);
- }
- return $ia;
-}
-
-@a = (10,20,30,40);
-@b = (50,70,60,200);
-$ia = create_array(@a); # Create C arrays
-$ib = create_array(@b);
-gd::plotpts($im,$ia,$ib,4,1);
-...
-gd::int_destroy($ia);
-gd::int_destroy($ib);
-</pre></blockquote>
-
-<h3> 3.5 Classes and Structures</h3>
-
-While SWIG represents all objects as opaque pointers, the
-contents of an object can be examined and modified through
-the use of accessor functions as follows:
-
-<blockquote><pre>
-/* Extract data from an object */
-double Point_x_get(Point *p) {
- return p->x;
-}
-/* Invoke a C++ member function */
-int Foo_bar(Foo *f) {
- return f->bar();
-}
-</pre></blockquote>
-
-From a Perl script, a user simply passes an object pointer
-to accessor functions to extract internal information
-or invoke member functions.
-
-<p>
-While it is possible to write accessor functions
-manually, SWIG automatically creates them when it is
-given structure and class definitions. For example, in the gd library, the
-following structure is used to contain image information:
-
-<blockquote><pre>
-typedef struct gdImageStruct {
- unsigned char ** pixels;
- int sx;
- int sy;
- int colorsTotal;
-...
-} gdImage;
-</pre></blockquote>
-
-If this structure definition were placed in the SWIG
-interface file, accessor functions would automatically be
-created. These could then be used to extract information
-about images as follows:
-
-<blockquote><pre>
-#!/usr/bin/perl
-use gd;
-$im = gd::gdImageCreate(400,300);
-# Print out the image width
-print gd::gdImage_sx_get($im), "\n";
-</pre></blockquote>
-
-Accessor functions are also created for C++ classes and Objective-C
-interfaces. For example, the class definition
-
-<blockquote><pre>
-class List {
-public:
- List();
- ~List();
- void insert(Object *);
- Object *get(int i);
- int length();
- ...
-};
-</pre></blockquote>
-
-is translated into the following accessor functions:
-
-<blockquote><pre>
-List *new_List() {
- return new List;
-}
-void delete_List(List *l) {
- delete l;
-}
-void List_insert(List *l, Object *o) {
- l->insert(o);
-}
-...
-</pre></blockquote>
-
-<h3> 3.6 Shadow Classes and Perl Objects</h3>
-
-As an optional feature, the accessor functions created by SWIG can be
-used to write Perl wrapper classes (this is enabled by running SWIG
-with the <tt>-shadow</tt> option). While all the gory details can be
-found in the SWIG Users Manual, the general idea is that the accessor
-functions can be encapsulated in
-a Perl class that mimics the behavior of the underlying object. For example,
-
-<blockquote><pre>
-
-package List;
-@ISA = qw( example );
-sub new {
- my $self = shift;
- my @args = @_;
- $self = new_List(@args);
- return undef if (!defined($self));
- bless $self, "List";
- my %retval;
- tie %retval, "List", $self;
- return bless \%retval,"List";
-}
-sub DESTROY {
- delete_List(@_);
-}
-sub insert {
- return $result = List_insert(@_);
-}
-...
-</pre></blockquote>
-This class provides a wrapper around the underlying object and
-is said to ``shadow'' the original object.
-Shadow classes allow C and C++ objects to be used from Perl
-in a natural manner. For example,
-
-<blockquote><pre>
-$l = new List;
-$l->insert($o);
-...
-$l->DESTROY();
-</pre></blockquote>
-
-For C structures, access to various attributes are provided through
-tied hash tables. For the gd library, members of the
-image data structure could be accessed as follows:
-
-<blockquote><pre>
-$im = gd::gdImageCreate(400,400);
-$width = $im->{sx};
-$height = $im->{sy};
-...
-</pre></blockquote>
-
-The other significant aspect of shadow classes is that they allow Perl
-to perform a limited form of automatic memory management for C/C++
-objects. If an object is created from Perl using a shadow class, the
-<tt>DESTROY</tt> method of that class automatically invokes the C++
-destructor when the object is destroyed. As a result, C/C++ objects
-wrapped by shadow classes can be managed using the same reference counting
-scheme utilized by other Perl datatypes.
-
-<h3> 3.7 Class Extension</h3>
-
-When building object-oriented Perl interfaces, it is sometimes useful
-to modify or extend objects with new capabilities. For example,
-the gd library defines the following data structure for defining points:
-
-<blockquote><pre>
-typedef struct {
- int x,y;
-} gdPoint;
-</pre></blockquote>
-
-
-To make this structure more useful, we can add constructors, destructors,
-and various methods to it (regardless of whether it is implemented in C or
-C++). To do this, the SWIG <tt>%addmethods</tt> directive can be used as follows:
-
-<blockquote><pre>
-/* Add some methods to points */
-%addmethods gdPoint {
-/* Create a point or an array of points */
-gdPoint(int npts = 1) {
- return (gdPoint *)
- malloc(sizeof(gdPoint)*npts);
-}
-/* Destroy a point */
-~gdPoint() {
- free(self);
-}
-/* Array indexing */
-gdPoint *get(int i) {
- return self+i;
-}
-/* A debugging function */
-void output() {
- printf("(%d,%d)\n",self->x,self->y);
-}
-};
-</pre></blockquote>
-
-Now, in the Perl interface <tt>gdPoint</tt> will appear just like a
-class with constructors, destructors, and methods. For example,
-
-<blockquote><pre>
-# Create a point
-$pt = new gdPoint;
-$pt->{x} = 20;
-$pt->{y} = 50;
-$pt->output();
-
-# Create an array of points
-$pts = new gdPoint(10);
-for ($i = 0; $i < 10; $i++) {
- $p = $pts->get($i);
- $p->{x} = $i;
- $p->{y} = 10*$i;
-}
-
-# Pass the points to a function
-gd::gdImagePolygon($im,$pts,10,1);
-...
-</pre></blockquote>
-
-The class extension mechanism is also a powerful
-way to repackage existing functionality. For example, the
-<tt>gdImage</tt> structure and various functions in the gd library
-could be combined into a Perl class as follows:
-
-<blockquote><pre>
-%addmethods gdImage {
-gdImage(int w, int h) {
- return gdImageCreate(w,h);
-}
-~gdImage() {
- gdImageDestroy(self);
-}
-int
-colorAllocate(int r, int g, int b) {
- return gdImageColorAllocate(self,r,g,b);
-}
-void
-line(int x1,int y1,int x2,int y2,int c) {
- gdImageLine(self,x1,y1,x2,y2,c);
-}
-...
-};
-</pre></blockquote>
-
-Users can now write scripts as follows:
-
-<blockquote><pre>
-#!/usr/bin/perl
-use gd;
-$im = new gdImage(400,400);
-$black = $im->colorAllocate(0,0,0);
-$white = $im->colorAllocate(255,255,255);
-$im->line(20,50,180,140,$white);
-...
-</pre></blockquote>
-
-With these simple modifications, our interface is already
-looking remarkably similar to that used in the GD module
-on CPAN. However, more improvements will be described shortly.
-
-<h3> 3.8 Access Control and Naming</h3>
-
-In certain instances, it may be useful to restrict access to
-certain variables and class members. Hiding objects is easy--simply
-remove them from the interface file. Providing read-only access can
-be accomplished using the <tt>%readonly</tt> and
-<tt>%readwrite</tt> directives. For example,
-
-<blockquote><pre>
-// Create read-only variables
-%readonly
-int foo; // Read-only
-double bar; // Read-only
-%readwrite
-
-// Create read-only class members
-class List {
-...
-%readonly
- int length; // Read-only member
-%readwrite
-...
-}
-</pre></blockquote>
-
-
-When read-only mode is used, attempts to modify a value from
-Perl result in a run-time error.
-
-<p>
-Another common problem is changing the name of various C declarations.
-For example, a C function name may conflict with an existing Perl keyword or subroutine. To
-fix this problem, the <tt>%name</tt> directive can be used. For example,
-
-<blockquote><pre>
-%name(cpack) void pack(Object *);
-</pre></blockquote>
-
-
-creates a new command ``cpack.'' If name conflicts occur repeatedly,
-the <tt>%rename</tt> directive can be used to change all future occurrences
-of a particular identifier as follows:
-
-<blockquote><pre>
-%rename pack cpack;
-</pre></blockquote>
-
-The renaming operations can also be applied to C/C++ class and structure
-names as needed. For example,
-
-<blockquote><pre>
-%name(Image) class gdImage {
-...
-}
-</pre></blockquote>
-
-<h3> 3.9 Exception Handling </h3>
-
-To catch errors, SWIG allows users to create user-defined exception
-handlers using the <tt>%except</tt> directive. These handlers are
-responsible for catching and converting C/C++ runtime errors into Perl
-errors. As an example, the following error handler can be used to
-catch errors in the standard C library:
-
-<blockquote><pre>
-%except(perl5) {
- errno = 0;
- $function
- if (errno) {
- die(strerror(errno));
- }
-}
-</pre></blockquote>
-
-When defined, the exception handling code is placed into all of the
-wrapper functions. In the process, the <tt>
-$function</tt> token is replaced by the actual C function call. For the
-example shown, the exception handler resets the <tt>errno</tt> variable
-and calls the C function. If the value of <tt>errno</tt> is modified to
-a non-zero value, an error message is extracted from the C library
-and reported back to Perl.
-
-<p>
-While catching
-errors in the C library has been illustrated, exception handlers
-can also be written to catch C++ exceptions or to use any
-special purpose error handling code that might be present in an
-application.
-
-<h3> 3.10 Typemaps</h3>
-
-Typemaps are one of SWIG's most powerful features and the primary
-means of customization. Simply stated, a
-typemap is a small bit of C code that can be given to SWIG to modify
-the way that it processes specific datatypes.
-For instance, Perl arrays can be converted into C arrays, Perl
-references can be substituted for pointers, and so forth. This
-section briefly introduces typemaps and their use. However, typemaps
-are a complicated topic so it is impossible to cover all of the details
-here and interested readers are strongly advised to consult the SWIG documentation.
-
-<h4> 3.10.1 Example: Output Values</h4>
-
-As a first typemap example, consider a function that returns values through its
-parameters as follows:
-
-<blockquote><pre>
-void
-imagesize(gdImagePtr im, int *w, int *h) {
- *w = gdImageSX(im);
- *h = gdImageSY(im);
-}
-</pre></blockquote>
-
-As is, this function would be difficult to use because the
-user must write helper functions to manufacture, dereference,
-and destroy integer pointers. These functions might be used as follows:
-
-<blockquote><pre>
-$wptr = new_integer(); # Create an 'int *'
-$hptr = new_integer();
-imagesize($im, $wptr, $hptr);
-$w = integer_value($wptr); # Dereference
-$h = integer_value($hptr);
-delete_integer($wptr); # Clean up
-delete_integer($hptr);
-</pre></blockquote>
-
-A more elegant solution is to use the SWIG typemap library
-in the interface file as follows:
-
-<blockquote><pre>
-%include typemaps.i
-void imagesize(gdImagePtr im, int *OUTPUT,
- int *OUTPUT);
-</pre></blockquote>
-
-
-Now, in the Perl script, it is possible to do this:
-
-<blockquote><pre>
-($w,$h) = imagesize($im);
-</pre></blockquote>
-
-In a similar spirit, it is also possible to use
-Perl references. For example:
-
-<blockquote><pre>
-%include typemaps.i
-void
-imagesize(gdImagePtr im, int *REFERENCE,
- int *REFERENCE);
-</pre></blockquote>
-
-
-Now in Perl:
-
-<blockquote><pre>
-# Return values in $w and $h
-imagesize($im,\$w,\$h);
-</pre></blockquote>
-
-To implement this behavior, the file <tt>typemaps.i</tt> defines
-a collection of typemap ``rules'' that are attached to specific
-datatypes such as <tt>int *OUTPUT</tt> and <tt>int *REFERENCE</tt>.
-The creation of these rules is now discussed.
-
-<h4> 3.10.2 Creating New Typemaps</h4>
-
-All wrapper functions perform a common sequence of internal ``operations.''
-For example, arguments must be converted from Perl into a
-C representation, a function's return value must be converted back into
-Perl, argument values might be checked, and so forth. SWIG gives each of
-these operations a unique name such as ``in'' for input parameter processing,
-``out'' for returning values, ``check'' for checking values, and so forth.
-Typemaps allow a user to re-implement these operations for specific datatypes
-by supplying small fragments of C code that SWIG inserts into the resulting wrapper code.
-
-<p>
-To illustrate, consider the gd example. In the original interface file,
-two functions were included to open and close files. These were required
-because SWIG normally maps all pointers (including files) into blessed
-references. Since a blessed reference is not the same as a Perl file handle,
-it is not possible to pass Perl files to functions expecting a <tt>FILE *</tt>.
-However, this is easily changed with a typemap as follows:
-
-<blockquote><pre>
-%typemap(perl5,in) FILE * {
- $target = IoIFP(sv_2io($source));
-}
-</pre></blockquote>
-
-This declaration tells SWIG that whenever a <tt>FILE *</tt>
-appears as a function parameter, it should be converted using the
-supplied C code. When generating wrappers, the typemap code is
-inserted into all wrapper functions where a <tt>FILE *</tt> is involved.
-In the process the
-<tt>$source</tt> and <tt>$target</tt> tokens are replaced by the names of
-C local variables corresponding to the Perl and C representations of
-an object respectively. As a result, this typemap allows Perl files
-to be used in a natural manner. For example,
-
-<blockquote><pre>
-open(OUT,">test.gif") || die "error!\n";
-
-# Much better than before
-gd::gdImageGif($im,*OUT);
-</pre></blockquote>
-
-Certain operations, such as output values, are implemented using
-a combination of typemaps as follows:
-
-<blockquote><pre>
-%typemap(perl5,ignore)
-int *OUTPUT(int temp) {
- $target = &temp;
-}
-%typemap(perl5,argout) int *OUTPUT {
- if (argvi >= items) {
- EXTEND(sp,1);
- }
- $target = sv_newmortal();
- sv_setiv($target,(IV) *($source));
- argvi++;
-}
-</pre></blockquote>
-
-In this case, the ``ignore'' typemap tells SWIG that a parameter is
-going to be ignored and that the Perl interpreter will not be
-supplying a value. Since the underlying C function still needs a
-value, the typemap sets the value of the parameter to point
-to a temporary variable <tt>temp</tt>. The ``argout'' typemap is used to
-return a value held in one of the function arguments. In this case,
-the typemap extends the Perl stack (if needed), and creates a new
-return value. The <tt>argvi</tt> variable is a SWIG-specific variable
-containing the number of values returned to the Perl interpreter (so
-it is incremented for each return value).
-
-<p>
-The C code supplied in each typemap is placed in a private scope that
-is not visible to any other typemaps or other parts of a wrapper function.
-This allows different typemaps to be used simultaneously--even if they
-define variables with the same names. This also allows the same typemap
-to be used more once in the same wrapper function. For example, the previous
-section used the <tt>int *OUTPUT</tt> typemap twice in the same function
-without any adverse side-effects.
-
-<h4> 3.10.3 Typemap Libraries</h4>
-
-Writing new typemaps is a somewhat magical art that requires knowledge of
-Perl's internal operation, SWIG, and the underlying application.
-Books such as <em>Advanced Perl Programming</em> and the man pages on
-extending and embedding the Perl interpreter will prove to be quite useful.
-However, since writing typemaps from scratch is difficult, SWIG provides a
-way for typemaps to be placed in a library and utilized without
-knowing their internal implementation details. To illustrate,
-suppose that you wanted to write some generic typemaps for checking the
-value of various input parameters. This could be done as follows:
-
-<blockquote><pre>
-// check.i
-// typemaps for checking argument values
-%typemap(perl5,check) Number POSITIVE {
- if ($target <= 0)
- croak("Expected a positive value");
-}
-
-%typemap(perl5,check) Pointer *NONNULL {
- if ($target == NULL)
- croak("Received a NULL pointer!");
-}
-...
-</pre></blockquote>
-
-To use these typemaps, a user could include the file <tt>check.i</tt>
-and use the <tt>%apply</tt> directive. The <tt>%apply</tt> directive simply
-takes existing typemaps and makes them work with new datatypes. For
-example:
-
-<blockquote><pre>
-%include check.i
-
-// Force 'double px' to be positive
-%apply Number Positive { double px };
-
-// Force these pointers to be NON-NULL
-%apply Pointer NONNULL { FILE *,
- Vector *,
- Matrix *,
- gdImage * };
-
-// Now some functions
-double log(double px); // 'px' positive
-double dot_product(Vector *, Vector *);
-...
-</pre></blockquote>
-
-In this case, the typemaps we defined for checking
-different values have been applied to a variety of
-new datatypes. This has been done without having to
-examine the implementation of those typemaps or having
-to look at any Perl internals. Currently, SWIG includes
-a number of libraries that operate in this manner.
-
-<h3> 3.11 Other SWIG Features</h3>
-
-SWIG has a number of other features that have not been discussed.
-In addition to producing wrapper code, SWIG also produces
-simple documentation files. These describe the contents of a
-module. In addition, C comments can be used to provide descriptive
-text in the documentation file. SWIG is also packaged with a
-library of useful modules that include typemaps and interfaces to
-common libraries. These libraries can simplify the construction
-of scripting interfaces.
-
-<h3> 3.12 Putting it All Together</h3>
-
-In the first part of this section, a minimal interface to the
-gd library was presented. Now, let's take a look at a more
-substantial version of that interface.
-
-<blockquote><pre>
-// gd.i
-%module gd
-%{
-#include "gd.h"
-%}
-
-// Make FILE * work
-%typemap(perl5,in) FILE * {
- $target = IoIFP(sv_2io($source));
-}
-
-// Grab the gd.h header file
-%include "gd.h"
-
-// Extend the interface a little bit
-%addmethods gdImage {
-gdImage(int w, int h) {
- return gdImageCreate(w,h);
-}
-~gdImage() {
- gdImageDestroy(self);
-}
-... etc ...
-};
-
-%addmethods gdPoint {
-... etc ...
-}
-
-// Wrap the fonts (readonly variables)
-%readonly
-%include "gdfontt.h"
-%include "gdfonts.h"
-%include "gdfontmb.h"
-%include "gdfontl.h"
-%include "gdfontg.h"
-%readwrite
-</pre></blockquote>
-
-Finally, here is a simple script that uses the module. Aside from
-a few minor differences, the script is remarkably similar to the first
-example given in the standard GD module documentation.
-
-<blockquote><pre>
-use gd;
-
-$im = new gdImage(100,100);
-$white= $im->colorAllocate(255,255,255);
-$black= $im->colorAllocate(0,0,0);
-$red= $im->colorAllocate(255,0,0);
-$blue= $im->colorAllocate(0,0,255);
-$im->transparentcolor($white);
-$im->interlaced(1);
-$im->rectangle(0,0,99,99,$white);
-$im->arc(50,50,95,75,0,360,$blue);
-$im->fill(50,50,$red);
-open(IMG, ">test.gif");
-$im->gif(*IMG);
-close(IMG);
-</pre></blockquote>
-
-<h2> 4 Interface Building Strategies</h2>
-
-SWIG simplifies the construction of Perl extensions because it hides
-Perl-specific implementation details and allows programmers to
-incorporate C/C++ applications into a Perl environment using familiar
-ANSI C/C++ syntax rules. In addition, SWIG interfaces are generally
-specified in a less formal manner than that found in XS or component
-architectures such as CORBA and COM. As a result, many users are
-surprised to find out how rapidly they can create Perl interfaces
-to their C/C++ applications. However, it is a misperception to think
-that SWIG can magically take an arbitrary C/C++ header file and
-instantly turn it into a useful Perl module. This section describes
-some of the issues and solution strategies for effectively using SWIG.
-
-<h3> 4.1 Wrapping an Existing Program </h3>
-
-Building a Perl interface to an existing application generally involves
-the following steps :
-
-<ol>
-<li> Locate header files and other sources of C declarations.
-<li> Copy header files to interface files.
-<li> Edit the interface file and add SWIG directives.
-<li> Remove or rewrite the application's <tt>main()</tt> function if necessary.
-<li> Run SWIG, compile, and link into a Perl extension module.
-</ol>
-
-While it is theoretically possible to run SWIG directly on a C header
-file, this rarely results in the best scripting interface. First, a
-raw header file may contain problematic declarations that SWIG doesn't
-understand. Second, it is usually unnecessary to wrap every function and
-variable in a large library. More often than not, there are internal
-functions that make little sense to use from Perl. By copying header
-files to a separate interface file, it is possible to eliminate these
-functions and clean things up with a little editing [footnote: An
-alternative approach to copying header files is to modify the header
-files using conditional compilation to add SWIG directives or to
-remove unnecessary functions]. Finally, the underlying application
-may require a few slight modifications. For example, Perl supplies
-its own <tt>main()</tt> function so if an application also contains <tt>
-main()</tt>, it will have to be removed, rewritten, or not linked into the
-extension module.
-
-<h3> 4.2 Evolutionary Interface Building</h3>
-
-After a Perl interface is first built, its use will
-expose any problems and limitations. These problems include functions
-that are awkward to use, poor integration with Perl datatypes, missing
-functionality, and so forth. To fix these problems,
-interface files can be enhanced with helper functions,
-typemaps, exception handlers, and other declarations. Since
-interfaces are easily regenerated, making such changes is a relatively
-straightforward process. However, as a result, SWIG interfaces tend
-to be built in an evolutionary and iterative manner rather than being
-formally specified in advance.
-
-<h3> 4.3 Traps and Pitfalls</h3>
-
-Finally, there are a number of subtle problems that sometimes arise
-when transforming a C/C++ program into a Perl extension module. One
-of these problems is the issue of implicit execution order
-dependencies and reentrant functions. From the Perl interpreter, users will be
-able to execute functions at any time and in any order. However, in
-many C programs, execution is precisely defined. For
-example, a precise sequence of function calls might be performed to
-properly initialize program data. Likewise, it may only be valid to
-call certain functions once during a single execution. From Perl,
-it is easy for a user to violate these constraints--resulting in
-a potential program crash or incorrect behavior. To fix these
-problems, applications can sometimes be modified by introducing additional
-state variables. For example, to prevent repeated execution, a function
-can be modified as follows:
-
-<blockquote><pre>
-void foo() {
- static int called = 0;
- if (called) return;
- ...
- called = 1;
-}
-</pre></blockquote>
-
-
-It is also possible to catch such behavior using exception handlers. For example,
-
-<blockquote><pre>
-%except(perl5) {
- static int called = 0;
- if (called)
- croak("Already executed!\n");
- $function
- called = 1;
-}
-// List all non-reentrant functions
-void foo();
-...
-// Clear the exception handler
-%except(perl5);
-</pre></blockquote>
-
-Another common problem is that of improper memory management. As previously mentioned,
-SWIG extensions use the same memory management techniques as C. Therefore, careless use
-may result in memory leaks, dangling pointers, and so forth.
-A somewhat more obscure memory related problem is caused when a C program
-overwrites Perl data. This can be caused by a function such as the following:
-
-<blockquote><pre>
-void geterror(char *msg) {
- strcpy(msg,strerror(errno));
-}
-</pre></blockquote>
-
-This function copies a string into memory pointed to by <tt>msg</tt>. However, in the
-wrapper function, the value of <tt>msg</tt> is really a pointer to data buried deep
-inside a Perl scalar value. When the function overwrites the value, it corrupts
-the value of the Perl scalar value and can cause the Perl interpreter to crash
-with a memory addressing error or obscure run-time error. Again, this sort of problem
-can usually be fixed with the use of typemaps. For example, it is possible to turn the
-<tt>msg</tt> parameter into an output value as follows :
-
-<blockquote><pre>
-// Use a temporary array for the result
-%typemap(perl5,ignore)
-char *msg (char temp[512]) {
- $target = temp;
-}
-// Copy the output into a new Perl scalar
-%typemap(perl5,argout) char *msg {
- if (argvi >= items) {
- EXTEND(sp,1);
- }
- $target = sv_newmortal();
- sv_setpv($target,$source);
- argvi++;
-}
-</pre></blockquote>
-
-<h2> 5 Applications </h2>
-
-SWIG is currently being used in an increasing variety of applications.
-This section describes some of the ways in which has been used. A number
-of advanced SWIG/Perl interfacing techniques such as typemaps and
-callback functions are also described.
-
-<h3> 5.1 Electronic CAD</h3>
-
-SWIG plays a pivotal role in the development process of Badger, an
-electronic computer-aided design system, being developed by Fusion
-MicroMedia, used in the design of integrated circuits and other
-electronic components. Badger is a fully object-oriented, modular,
-and highly extensible system, running under various flavors of the
-UNIX operating system as well as
-Windows-NT.
-
-<p>
-The core components in Badger are constructed in C++ and are
-delivered as a set of shared (dynamically loaded) libraries. The
-libraries are <em>not</em> directly linked into an executable program.
-Instead, each library comes with an extension language (EL)
-interface that is generated by SWIG, allowing the library to be used
-within a Perl program [footnote: For now, Perl is the only supported
-extension language. Tcl and Java will be supported in the future].
-The combination of a powerful EL and well-tuned, application-specific
-software results in a system that is potent, flexible, and easy to
-use.
-
-<p>
-For the most part, SWIG is used in a ``normal'' fashion: a description
-of the classes contained within a library is presented to SWIG, and it
-generates an EL interface that allows the code within that library to
-be accessed from an EL. There are two interesting facets to the use
-of SWIG within Badger: the use of ``smart references,'' and the use
-of callbacks from C++ to the EL,
-
-<h4> 5.1.1 Smart References</h4>
-
-Suppose a Perl program calls a function defined by Badger (and wrapped
-with SWIG) in order to create and return some object. Any Perl
-variable used to refer to that object really holds a <em>handle</em> to
-the object, implemented as a blessed reference containing the object's type and
-its memory address. Although the implementation is a bit more
-involved, the handle, in effect, acts like a pointer in C. Now,
-suppose another function within Badger is called that causes the
-original object to be destroyed. Severe problems will occur if the
-Perl variable is supplied to another Badger function, because the
-variable refers to a non-existent object. The reason for the
-difficulty is that the extension language expects to have control over
-the lifetime of the object, but the external system (Badger) cannot
-meet this expectation.
-
-<p>
-It is possible to design Badger so that the extension language
-has complete control over the lifetime of all the objects within the
-system. Unfortunately, this approach results in a system that is too
-closely tied to the implementation of a particular language, and adding
-a new extension language to the mix is difficult. An alternate
-solution that is simple to implement and is portable, is to
-introduce ``smart references'' (also called proxies) into the
-design [5, pg. 207]. In effect, a smart reference is an object that has the same
-set of operations as a ``real'' object, but the smart reference's
-implementation consists solely of a single pointer to a ``real''
-object of the appropriate type.
-
-<p>
-The extension language interfaces within Badger have been crafted so
-that the extension language manipulates smart references and that the lifetime
-of a smart reference is completely under the control of the
-extension language. Under most circumstances, the extension language
-performs an operation on the smart reference, and the smart reference
-then attempts to transfer the operation to the real object. If the
-real object has been destroyed then the smart reference will have been
-invalidated (it points to <tt>nil</tt>). In this case, the operation
-is aborted and, if possible, an exception is raised in the extension
-language. Badger contains the necessary machinery to invalidate any
-smart references that point to an object being destroyed.
-
-<p>
-Modern C++ compilers, with their support for templates, run-time type
-identification, and so forth, provide the means to automatically
-construct smart reference classes. For a variety of reasons, we are
-not able to always utilize modern compilers. Hence, we have created
-the implementations of the smart references manually, which is a
-tedious process. Fortunately, this task can be mostly automated by
-creating our own code generator as part of SWIG. This is a simple
-matter, as SWIG is a modular software system.
-
-<h4> 5.1.2 Callbacks</h4>
-
-The extension language interface produced by SWIG allows functions
-defined in the external system to be called from within an extension
-language. Unfortunately, the interface produced by SWIG does not
-support the calling of extension language functions within C,
-C++, or Objective-C. The ability to invoke functions bidirectionally
-is needed by Badger, so support for callbacks from C++ to Perl has been
-developed [footnote: For now, callbacks only work with Perl. Support
- for callbacks with Tcl and Java will be added later]. The basic
-approach is this:
-
-<ul>
-<li> Define a function.
-<li> Register the function.
-<li> Perform some operation that causes the registered function to be
- invoked.
-</ul>
-
-To make this work, Badger provides an abstract base class in
-C++ called <tt>Trigger</tt>, so called because a function associated
-with objects of this class is invoked when an event of some kind
-occurs. Badger also provides the machinery to associate <tt>Trigger</tt>
-objects with an event name and with one or more objects internal to
-the system. When an internal object ``receives'' an event, it
-examines the set of registered functions looking for a match. If a
-match is found then the <tt>Trigger</tt> object is invoked, and the name of the
-event and the object that received the event are supplied as
-arguments.
-
-<p>
-Badger provides a number of classes derived from <tt>Trigger</tt> that
-specialize its behavior for certain extension languages, for C++, or
-for an object request broker. For example, the <tt>Perl5Trigger</tt>
-class is derived from <tt>Trigger</tt> and it specializes its base class by
-storing a pointer to a Perl function reference (an <tt>SV*</tt>), and
-by providing the machinery needed to invoke that Perl function.
-
-<p>
-For example, consider the following Perl fragment:
-
-<blockquote><pre>
-sub MyFcn {
- my $EventName = shift;
- my $Object = shift;
- # ... rest of function here.
-}
-my $Object = BadgerFunction(....);
-my $Name = "Can't find file";
-Badger::RegisterByObject($Name,
- $Object, \&MyFcn);
-$Object->ReadFile("A bogus file name");
-</pre></blockquote>
-
-The <tt>MyFcn()</tt> Perl function is the callback (trigger) function,
-and it is registered with <tt>$Object</tt> using the
-event name called ``<tt>Can't find file</tt>''. Now, suppose that the
-<tt>$Object->ReadFile()</tt> operation fails. Internally, Badger will
-note the failure, determine the appropriate event name, attempt to
-find a Trigger object associated with that event, and if found, will
-``invoke the Trigger'' by calling the appropriate member function.
-For the example above, this means that the <tt>MyFcn()</tt> function
-will be called with <tt>$Object</tt> and ``<tt>Can't find file</tt>''
-supplied as arguments. The function may require more information such
-as the file name (that could not be opened), and it might find this
-information by ``pulling'' data from the external library using the
-functions wrapped by SWIG.
-
-<p>
-The <tt>RegisterByObject()</tt> function is responsible for creating
-an object of the <tt>Perl5Trigger</tt> class, and for creating the association
-between the <tt>Perl5Trigger</tt>, the event name, and the object receiving the
-event. There is a bit of typemap trickery involved when intercepting
-the arguments from Perl:
-
-<blockquote><pre>
-%typemap(perl5,in) SV* pFcn {
- if (!SvROK($source))
- croak("Expected a reference.\n");
- $target = SvRV($source);
-}
-void
-RegisterByObject(const char* pcEventName,
- Ref* pRef, SV* pFcn);
-</pre></blockquote>
-
-The final portion of the system left to describe is the implementation
-of the <tt>Perl5Trigger::Invoke()</tt> member function, which is
-responsible for calling the Perl function from the C++ side of the
-world. The implementation of this, taken nearly verbatim from the
-Advanced Perl Programming book [1, pg. 353], looks like
-this:
-
-<blockquote><pre>
-bool
-Perl5Trigger::
-Invoke(const char* pcEventName,
- void* pObject,
- const char* pcTypeName) {
- dSP;
- ENTER;
- SAVETMPS;
- PUSHMARK(sp);
- SV* pSV = sv_newmortal();
- sv_setpv(pSV, (char*) pcEventName);
- XPUSHs(pSV);
- pSV = sv_newmortal();
- sv_setref_pv(pSV, (char*) pcTypeName,
- pObject);
- XPUSHs(pSV);
- pSV = sv_newmortal();
- sv_setpv(pSV, (char*) pcTypeName);
- XPUSHs(pSV);
- PUTBACK;
- int n = perl_call_sv(this->pPerl5Fcn,
- G_SCALAR);
- SPAGAIN;
- if (n == 1)
- n = POPi;
- PUTBACK;
- FREETMPS;
- LEAVE;
- return n == 0 ? false : true;
-}
-</pre></blockquote>
-
-<h4> 5.1.3 Benefits And Limitations</h4>
-
-The benefits that SWIG provides to Badger are enormous:
-
-<ul>
-<li> Not counting custom code (e.g., language-specific
- callbacks), an extension language interface can be developed in a
- day, compared with weeks for a hand-crafted approach.
-
-<li> SWIG supports the use of multiple extension languages with ease.
-
-<li> The resulting solution is flexible, and the results can be
- tailored to meet the needs of complex applications (e.g.,
- callbacks, smart references, and so on).
-</ul>
-
-SWIG does have limitations, but so far, none of these limitations has
-proven to be a real impediment. It also appears that most of these
-limitations will be eradicated, once SWIG has its own extension
-language interface (see Section 7).
-
-
-<h3> 5.2 TCAP and SCCP from HP OpenCall</h3>
-
-One of the well known pitfalls of systematic library testing is
-the creation of a huge number of small C programs--each designed to perform
-a single test. More often than not, these C programs have a lot of
-common code that is copied from one test case to the
-other. Testing is further complicated by the tedious process of
-editing, compiling, and executing each of these programs.
-
-<p>
-To solve this problem, SWIG can be used to incorporate libraries
-into Perl extension modules where test cases can be implemented as Perl scripts.
-As a result, the compile-execute cycle is no longer a problem and
-Perl scripts can be used to implement common parts of various test cases.
-
-<p>
-This section describes the integration of Perl with an API that is
-part of a HP OpenCall telecom product developed at HP Grenoble. The
-API provides access to the TCAP and SCCP layers of the SS7 protocol
-and consists of about 20 function and 60 structure declarations.
-Furthermore, most function parameters are pointers to deeply nested
-structures such as follows:
-
-<blockquote><pre>
-typedef enum {
- ...
-} tc_address_nature;
-
-typedef struct {
- ...
- tc_address_nature nature;
- ...
-} tc_global_title;
-
-typedef struct tc_address_struct {
- ...
- tc_global_title gt;
- ...
-} tc_address;
-</pre></blockquote>
-
-From a Perl users' point of view, the functionality offered
-by the SWIG generated module must be not be very different from the underlying C API.
-Otherwise, test writers may be confused by the Perl API and testing
-will be unnecessarily complicated. Fortunately, SWIG addresses this problem
-because Perl interfaces
-are specified using C syntax and the resulting interface closely
-resembles the original API.
-
-<h4> 5.2.1 Creating the SWIG Interface</h3>
-
-To wrap the C API, there were three choices: copy
-and modify the header files into a SWIG interface file, feed the
-header files directly to SWIG, or write an interface file that includes
-some parts of the header files. The first choice
-requires the duplication of C definitions--a task that is
-difficult to manage as the API evolves (since it is hard to maintain
-consistency between the interface file and header files).
-The second choice may work if the header files are written in a very
-clean way. However, it can break down if header files are too complicated.
-Therefore, a mix of header files and interfaces was utilized.
-
-<p>
-As part of the interface building process, header files were to
-be included directly into interface files. This is easily done
-using the <tt>%include</tt> directive, but a number of problematic
-nested structure declarations had to be fixed. For example,
-
-<blockquote><pre>
-struct tcStat {
- ...
- union {
- ...
- struct stat_p_abort {
- int value;
- tc_p_abort_cause p_abort;
- } abort;
- ...
- } p;
-} tc_stat;
-</pre></blockquote>
-
-To make this structure more manageable in SWIG, it can be split into
-smaller pieces and rewritten as follows:
-
-<blockquote><pre>
-typedef struct {
- int value;
- tc_p_abort_cause p_abort;
-} tc_stat_abort;
-
-struct TcStat {
- ...
- tc_stat_abort abort;
- ...
-};
-</pre></blockquote>
-Such changes have no impact on user code, but they simplify the
-use of SWIG.
-<p>
-In addition to splitting, a number of structures in the
-header files were to be hidden from the SWIG compiler. While
-this could be done using a simple <tt>#ifndef SWIG</tt> in the code,
-this could potentially result in a huge customer problem if they also defined
-a <tt>SWIG</tt> macro in their compilation process. Therefore,
-conditional compilation was implemented using some clever C
-comments that were parsed by vpp (See the Text::Vpp module) during
-the build of the SWIG interface. For example,
-
-<blockquote><pre>
-/*
-HP reserved comment
-@if not $_hp_reserved_t
-*/
-typedef struct {
- int length;
- unsigned char datas[MAX_ABORT_LEN];
-} tc_u_abort;
-/*
-@endif
- */
-</pre></blockquote>
-
-<h4> 5.2.2 Shadow Classes</h4>
-
-By default, SWIG converts structure definitions into accessor functions
-such as
-
-<blockquote><pre>
-tc_global_title *
-tc_address_gt_get(tc_address *);
-
-tc_address_nature
-tc_global_title_nature_set(
- tc_global_title *t,
- tc_address_nature val);
-</pre></blockquote>
-
-Unfortunately, using such functions is somewhat unfriendly
-from Perl. For example, to set a single value, it would be
-necessary to write the following:
-
-<blockquote><pre>
-$param = new_tc_address();
-tc_global_title_nature_set(
- tc_address_gt_get($param),
- $value);
-</pre></blockquote>
-
-Fortunately, shadow classes solve this problem by providing object-oriented
-access to the underlying C structures. As a result, it is possible
-to rewrite the above Perl code as follows:
-
-<blockquote><pre>
-$parm = new tc_address;
-$param->{gt}{nature} = $value;
-</pre></blockquote>
-
-Needless to say, this approach is much easier for users to grasp.
-
-<h4> 5.2.3 Customization With Typemaps</h4>
-
-To improve the Perl interface, a number of typemaps were defined
-for various parts of the interface.
-One use of typemaps was in structures such as the following:
-
-<blockquote><pre>
-typedef struct {
- ...
- tc_u_abort abort_reason;
- ...
-} tc_dialog_portion;
-</pre></blockquote>
-
-Since <tt>tc_u_abort</tt> is defined by the structure shown earlier,
-SWIG normally tries to manipulate it through pointers. However, a typemap
-can be defined to change this behavior. In particular, it was
-decided that testers should be able to set and get this value using
-BCD encoded strings such as follows:
-
-<blockquote><pre>
-my $dialog = new tc_dialog_portion;
-$dialog->{abort_reason} = '0f456A';
-
-# Or
-print "User abort reason is \
-$dialog->{abort_reason} \n";
-</pre></blockquote>
-
-To do this, a typemap for converting BCD Perl strings into an
-appropriate byte sequence were developed. In addition, the typemap
-performs a few sanity checks to prevent invalid values.
-
-<blockquote><pre>
-%typemap (perl5,in) tc_u_abort *
-($basetype temp)
-{
- int i;
- STRLEN len;
- short tmp;
- char *str;
- $target = &temp;
-
- /* convert scalar to char* */
- str = SvPV($source,len);
- /* check if even # of char */
- if ( (len % 2) != 0 ) {
- croak("Uneven # of char");
- }
- /* set length field */
- $target->length=(len/2);
- if ((len/2)>(sizeof($basetype)-1))
- {
- croak("Too many bytes in value\n");
- }
- for (i=0;i<$target->length;i++)
- {
- if (sscanf(str,"%2hx", &tmp) != 1 )
- croak("sscanf failed on %s, \
- is it hexa ?\n",str);
- $target->datas[i] = tmp;
- str+=2;
- }
-}
-</pre></blockquote>
-
-To return the byte buffer back to Perl as a string, a somewhat simpler typemap
-is used:
-
-<blockquote><pre>
-%typemap (perl5,out) tc_u_abort *
-{
- int i;
- $target=newSVpvf("%x",$source->datas[0]);
-
- for (i=1; i< $source->length; i++) {
- sv_catpvf($target,"%x",
- $source->datas[i]);
- }
- argvi ++;
-}
-</pre></blockquote>
-
-SWIG typemaps were also used to fix a few other functions. For example,
-some functions required an address parameter encoded as a two-element array.
-By default, SWIG wraps this parameter as a pointer, but this
-leaves the Perl writer with the painful tasks of creating and
-filling a C array with sensible values using the SWIG pointer library or
-helper functions. Fortunately, with typemaps, it was possible to
-create and set this parameter using Perl hashes as follows:
-
-<blockquote><pre>
-# $address is an ordinary perl hash
-# $address will be used as an array
-$address->{pc} = 10;
-$address->{ssn}= 12;
-...
-SCCP_oamcmd($cnxId, $time, undef, $address,
- $command, $cmd_parms);
-</pre></blockquote>
-
-The typemap implementing this behavior is as follows:
-
-<blockquote><pre>
-%typemap (perl5,in) SccpOamAddress* {
- HV* passedHash;
- SV** valuePP;
- SccpOamAddress tempAddress;
- if (!SvOK($source)) {
- /* we were passed undef */
- tempAddress[0] = 0;
- tempAddress[1] = 0;
- } else {
- if (!SvROK($source))
- croak("Not a reference\n");
- if (SvTYPE(SvRV($source)) != SVt_PVHV)
- croak("Not a hash reference\n");
-
- passedHash = (HV*) SvRV($source);
- valuePP=hv_fetch(passedHash,"ssn",3,0);
-
- if (*valuePP == NULL)
- croak("Missing 'ssn' key\n");
- tempAddress[1] = SvIV(*valuePP);
- valuePP=hv_fetch(passedHash,"pc",2,0);
- if (*valuePP == NULL)
- croak("Missing 'pc' key\n");
- tempAddress[0] = SvIV(*valuePP);
- }
- $target = &tempAddress;
-}
-
-/* SccpOamAddress is returned as
- {'ssn'=>ssn_value, 'pc'=>pc_value} */
-%typemap (perl5,out) SccpOamAddress* {
- HV* passedHash;
- SV* theSsn;
- SV* thePc;
-
- thePc = newSViv((*$source)[0]);
- theSsn = newSViv((*$source)[1]);
- passedHash = newHV();
- hv_store(passedHash,"ssn",3,theSsn,0);
- hv_store(passedHash,"pc",2,thePc,0);
- $target = newRV_noinc((SV*) passedHash);
- argvi ++;
-}
-</pre></blockquote>
-
-<h4> 5.2.4 Statistics</h4>
-
-Table 1 shows the amount of code associated with .i files and
-header files as well as the amount of code generated by SWIG (.C and .pm
-files). While it was necessary to write a few .i files, the size of
-these files is small in comparsion to the generated output files.
-
-<p>
-<center>
-<table border cellspacing=0 cellpadding=5>
-<caption align=bottom> Table 1: TCAP and SCPP Modules</caption>
-<tr>
-<th> Module </th>
-<th> .i files </th>
-<th> .h files </th>
-<th> .C files </th>
-<th> .pm files </th>
-</tr>
-<tr>
-<th> TCAP </th>
-<td> 434 </td>
-<td> 977 </td>
-<td> 16098 </td>
-<td> 3561 </td>
-</tr>
-<tr>
-<th> SCPP </th>
-<td> 364 </td>
-<td> 494 </td>
-<td> 13060 </td>
-<td> 2246 </td>
-</tr>
-</table>
-</center>
-
-<h4> 5.2.5 Results </h4>
-
-Overall, SWIG saved time when providing Perl access to the TCAP and SCCP
-libraries. While it took some time and hard work to write the typemaps,
-the SWIG approach has several advantages compared to XS or the
-pure C approach:
-
-<ul>
-
-<li> The interface files are quite short so if they are well documented, a new
- SWIG user should not have any major problems maintaining them.
-<li> A new version of the API is wrapped with a 'make' command, so there is no need to edit
- any file. In most cases the interface files can remain unmodified, provided
- there are no weird constructs introduced in the new version of the API.
-<li> New comments added in the header files will be automatically added in the
- documentation files generated by SWIG.
-<li> If necessary, new helper functions may be added in the .i files without
- impacting other parts of the code or typemaps. This allows a new user to do it
- without reading the whole SWIG manual.
-<li> Typemaps that deal with basic types or simple structures are reusable
- and can be used with other APIs.
-</ul>
-
-For those who are considering SWIG's advanced features, the learning
-curve is a little steep at first, but the rewards are great because
-SWIG advanced features will enable you to provide an improved
-interface to the Perl user.
-
-
-
-
-
-
-
-<h2> 6 Limitations</h2>
-
-Currently, SWIG is being used by hundreds of users in conjunction
-with a variety of applications. However, the current implementation
-of SWIG has a number of limitations. Some of these limitations are
-due to the fact that SWIG is not a full C/C++ parser. In particular,
-the following features are not currently supported:
-
-<ul>
-<li> Variable length arguments (...)
-<li> Pointers to functions.
-<li> Templates.
-<li> Overloaded functions and operators.
-<li> C++ Namespaces.
-<li> Nested class definitions.
-</ul>
-
-When these features appear in a SWIG input file, a syntax error or
-warning message is generated. To eliminate these warnings,
-problematic declarations can either be removed from the interface,
-hidden with conditional compilation, or wrapped using helper
-functions and other SWIG directives.
-
-<p>
-A closely related problem is that certain C/C++ programs are not easily
-scripted. For example, programs that make extensive use of
-advanced C++ features such as templates, smart pointers, and overloaded
-operators can be extremely troublesome to incorporate
-into Perl. This is especially the case for C++ programs that override
-the standard behavior of pointers and deferencing operations---operations
-that are used extensively by SWIG generated wrapper code.
-
-<p>
-In addition, SWIG does not provide quite as much flexibility as <tt>xsubpp</tt> and
-other Perl specific extension building tools. In order to be general purpose,
-SWIG hides many of the internal implementation details of each scripting
-language. As a result, it can be difficult to accomplish certain tasks. For
-example, one such situation is the handling of functions where arguments
-are implicitly related to each other as follows:
-
-<blockquote><pre>
-void foo(char *str, int len) {
- // str = string data
- // len = length of string data
- ...
-}
-</pre></blockquote>
-
-Ideally, it might be desirable to pass a single Perl string to such a function
-and have it expanded into a data and length component. Unfortunately, SWIG
-has no way to know that the arguments are related to each other in this manner.
-Furthermore, the current typemap mechanism only applies to single arguments
-so it can not be used to combine arguments in this manner. XS, on the other hand, is more
-closely tied to the Perl interpreter and consequently provides more
-power in the way that arguments can be converted and passed to C functions.
-
-<p>
-Finally, SWIG is still somewhat immature with respect to its overall
-integration with Perl. For example, SWIG does not fully support
-Perl's package and module naming system. In other words, SWIG can create
-a module ``Foo'', but can't create a module ``Foo::Bar.'' Likewise,
-SWIG does not currently utilize MakeMaker and other utilities
-(although users have successfully used SWIG with such tools). In
-addition, some users have reported occasional problems when SWIG
-modules are used with the Perl debugger and other tools.
-
-<h2> 7 Future Directions </h2>
-
-Future development of SWIG is focused on three primary areas. First, improved
-parsing and support for more advanced C++ are being added. These additions
-include support for overloaded functions and C++ namespaces. Limited support for wrapping
-C++ templates may also be added. Second, SWIG's code generation abilities
-are being improved. Additions include more flexible typemaps and better
-access to scripting-language specific features. Finally, an extension API
-is being added to the SWIG compiler. This API will allow various
-parts of the SWIG compiler such as the preprocessor, parser, and code generators
-to be accessed through a scripting language interface. In fact, this
-interface will even allow new parsers and code generators to be implemented
-entirely in Perl.
-
-<h2> 8 Acknowledgments</h2>
-
-SWIG would not be possible without the feedback and contributions of its users.
-While it is impossible to acknowledge everyone individually, a number of
-people have been instrumental in promoting and improving SWIG's Perl support.
-In particular, Gary Holt provided many of the ideas used in the shadow
-class mechanism. We would also like to thank John Buckman, Scott Bolte,
-and Sriram Srinivasan, for their support of SWIG. We also thank the University
-of Utah and Los Alamos National Laboratory for their continued support.
-
-<h2> 9 Availability </h2>
-
-SWIG is freely available on CPAN at <br>
-
-<p>
-<a href="http://www.perl.com/CPAN/authors/Dave_Beazley">
-<tt>www.perl.com/CPAN/authors/Dave_Beazley</tt>.</a><br>
-
-<p>
-Additional information is also available on the SWIG homepage at
-<a href="http://www.swig.org"><tt>www.swig.org</tt></a>. An
-active mailing list of several hundred subscribers is also available.
-
-<h2> Bibliography </h2>
-
-[1] Sriram Srinivasan. <em> Advanced Perl Programming</em>. O'Reilly
-and Associates, 1997.
-
-<p>
-[2] Scott Bolte. SWIG. <em> The Perl Journal</em>, 2(4):26-31, Winter 1997.
-
-<p>
-[3] D.M. Beazley. SWIG and Automated C/C++ Scripting Extensions.
-<em> Dr. Dobb's Journal</em>, (282):30-36, Feb 1998.
-
-<p>
-[4] D.M. Beazley, SWIG Users Manual. Technical Report UUCS-98-012,
-University of Utah, 1998.
-
-<p>
-[5] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, <em>Design Patterns</em>.
-Addison-Wesley, 1995.
-
-</body>
-</html>
diff --git a/swigweb/papers/Perl98/swigperl.pdf b/swigweb/papers/Perl98/swigperl.pdf
deleted file mode 100755
index 685df8b..0000000
--- a/swigweb/papers/Perl98/swigperl.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Py96/python96.html b/swigweb/papers/Py96/python96.html
deleted file mode 100755
index 8bd9e03..0000000
--- a/swigweb/papers/Py96/python96.html
+++ /dev/null
@@ -1,572 +0,0 @@
-<html>
-<title>
-Using SWIG to Control, Prototype, and Debug C Programs with Python
-</title>
-<body BGCOLOR="ffffff">
-<h1> Using SWIG to Control, Prototype, and Debug C Programs with Python </h1>
-<b>
-(Submitted to the 4th International Python Conference) <br> <br>
-David M. Beazley <br>
-Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 <br>
-<a href="http://www.cs.utah.edu/~beazley"> beazley@cs.utah.edu </a> <br>
-</b>
-<h2> Abstract </h2>
-<em>
-I discuss early results in using SWIG to interact with C and C++ programs
-using Python. Examples of using SWIG are provided along with a
-discussion of the benefits and limitations of this approach. This
-paper describes work in progress with the hope of getting feedback and
-ideas from the Python community.
-</em> <br> <br>
-
-Note : SWIG is freely available at <a href="http://www.cs.utah.edu/~beazley/SWIG"> http://www.cs.utah.edu/~beazley/SWIG </a>
-
-<h2> Introduction </h2>
-
-SWIG (Simplified Wrapper and Interface Generator) is a code
-development
-tool designed to make it easy for scientists and engineers to add scripting
-language interfaces to programs and libraries written in C and C++.
-The first version of SWIG was developed in July 1995
-for use with
-very large scale scientific applications running on the Connection
-Machine 5 and Cray T3D at Los Alamos National Laboratory.
-Since that time, the system has been extended to support several
-interface languages including Python, Tcl, Perl4, Perl5, and Guile [1].
-
-In this paper, I will describe how SWIG can be used to interact with
-C and C++ code from Python. I'll also discuss some
-applications and limitations of this approach. It is important to
-emphasize that SWIG was primarily designed for scientists and engineers
-who would like to have a nice interface, but who would rather
-work on more interesting problems than figuring out how to build
-a user interface or using a complicated interface generation tool.
-
-<h2> Introducing SWIG </h2>
-
-The idea behind SWIG is really quite simple---most interface
-languages such as Python provide some mechanism for making
-calls to functions written in C or C++. However, this almost
-always requires the user to write special "wrapper" functions
-that provide the glue between the scripting language and the
-C functions. As an example, if you wanted to add the
-<tt> getenv() </tt> function to Python, you would need to write
-the following wrapper code [4] :
-
-<blockquote>
-<tt>
-<pre>
-static PyObject *wrap_getenv(PyObject *self, PyObject *args) {
- char * result;
- char * arg0;
- if(!PyArg_ParseTuple(args, "s",&arg0))
- return NULL;
- result = getenv(arg0);
- return Py_BuildValue("s", result);
-}
-
-</pre> </tt>
-</blockquote>
-While writing a single wrapper function isn't too difficult,
-it quickly becomes tedious and error prone as the number
-of functions increases.
-SWIG automates this process by generating
-wrapper code from a list ANSI C function and variable declarations.
-As a result, adding scripting languages to C applications can become
-an almost trivial exercise. <br> <br>
-
-The core of the SWIG consists of a YACC parser and a collection
-of general purpose utility functions. The output of the parser
-is sent to two different modules--a language module for writing
-wrapper functions and a documentation module for producing a simple
-reference guide. Each of the target languages and documentation methods
-is implemented as C++ class that can be plugged in to the system.
-Currently, Python, Tcl, Perl4, Perl5, and Guile are supported as
-target languages while documentation can be produced in ASCII, HTML,
-and LaTeX. Different target languages can be implemented as a new
-C++ class that is linked with a general purpose SWIG library file.
-
-<h2> Previous work </h2>
-
-Most Python users are probably aware that automatic wrapper generation is
-not a new idea. In particular, packages such as ILU are capable
-of providing bindings between C, C++, and Python using specifications
-given in IDL (Interface Definition Language) [3]. SWIG is not really meant to compete with this
-approach, but is designed to be a no-nonsense, easy to use tool
-that scientists and engineers can use to build interesting interfaces
-without having to worry about grungy programming details or learning
-a complicated interface specification language.
-With that said, SWIG is certainly not designed to turn Python into
-a C or C++ clone (I'm not sure that turning Python into interpreted
-C/C++ compiler would be a good idea anyways). However, SWIG can allow
-Python to interface with a surprisingly wide variety of C functions.
-
-</body>
-</html>
-
-<h2> A SWIG example </h2>
-
-While it is not my intent to provide a tutorial, I hope to
-illustrate how SWIG works by building a module from part of the
-UNIX socket library.
-While there is probably no need to do this in practice (since Python
-already has a socket module), it illustrates most of SWIG's capabilities
-on a moderately complex example and provides a basis for
-comparison between an existing module and one created by SWIG. <br> <br>
-
-As input, SWIG takes an input file referred to as an "interface file."
-The file starts with a preamble containing the name of the
-module and a code block where special header files, additional C
-code, and other things can be added. After that, ANSI C function
-and variable declarations are listed in any order. Since SWIG
-uses C syntax, it's usually fairly easy to build an interface
-from scratch or simply by copying an existing header file.
-The following SWIG interface file will be used for our socket example :
-
-<blockquote>
-<tt>
-<pre>
-// socket.i
-// SWIG Interface file to play with some sockets
-%init sock // Name of our module
-%{
-#include <sys/types.h>
-#include <sys/socket.h>
-#include <netinet/in.h>
-#include <arpa/inet.h>
-#include <netdb.h>
-
-/* Set some values in the sockaddr_in structure */
-struct sockaddr *new_sockaddr_in(short family, unsigned long hostid, int port) {
- struct sockaddr_in *addr;
- addr = (struct sockaddr_in *) malloc(sizeof(struct sockaddr_in));
- bzero((char *) addr, sizeof(struct sockaddr_in));
- addr->sin_family = family;
- addr->sin_addr.s_addr = hostid;
- addr->sin_port = htons(port);
- return (struct sockaddr *) addr;
-}
-/* Get host address, but return as a string instead of hostent */
-char *my_gethostbyname(char *hostname) {
- struct hostent *h;
- h = gethostbyname(hostname);
- if (h) return h->h_name;
- else return "";
-}
-%}
-
-// Add these constants
-enum {AF_UNIX, AF_INET, SOCK_STREAM, SOCK_DGRAM, SOCK_RAW,
- IPPROTO_UDP, IPPROTO_TCP, INADDR_ANY};
-
-#define SIZEOF_SOCKADDR sizeof(struct sockaddr)
-
-// Wrap these functions
-int socket(int family, int type, int protocol);
-int bind(int sockfd, struct sockaddr *myaddr, int addrlen);
-int connect(int sockfd, struct sockaddr *servaddr, int addrlen);
-int listen(int sockfd, int backlog);
-int accept(int sockfd, struct sockaddr *peer, %val int *addrlen);
-int close(int fd);
-struct sockaddr *new_sockaddr_in(short family, unsigned long, int port);
-%name gethostbyname { char *my_gethostbyname(char *); }
-unsigned long inet_addr(const char *ip);
-
-%include unixio.i
-</pre>
-</tt>
-</blockquote>
-
-There are several things to notice about this file
-
-<ul>
-<li> The module name is specified with the <tt> %init </tt> directive.
-<li> Header files and supporting C code is placed in <tt> %{,%} </tt>.
-<li> Special support functions may be necessary. For example, <tt>
-new_sockaddr_in() </tt> creates a new <tt> struct sockaddr_in </tt> type
-and sets some of its values.
-<li> Constants are created with <tt> enum </tt> or <tt> #define. </tt>
-<li> Functions can take most C basic datatypes as well as pointers
-to complex types.
-<li> Functions can be renamed with the <tt> %name </tt> directive.
-<li> The <tt> %val </tt> directive forces a function argument to be called by
-value.
-
-<li> The <tt> %include </tt> directive can be used to include other
-SWIG interface files. In this case, the file <tt> unixio.i </tt>
-might look like the following :
-
-<blockquote>
-<tt>
-<pre>
-// File : unixio.i
-// Some file I/O and memory functions
-%{
-%}
-int read(int fd, void *buffer, int n);
-int write(int fd, void *buffer, int n);
-typedef unsigned int size_t;
-void *malloc(size_t nbytes);
-</pre>
-</tt>
-</blockquote>
-<li> Since interface files can include other interface files, it can be very
-easy to build up libraries and collections of useful functions.
-<li> <tt> typedef </tt> can be used to provide mapping between datatypes.
-<li> C and C++ comments are allowed and like C, SWIG ignores whitespace.
-</ul>
-
-The key thing to notice about SWIG interface files is that they support
-real C functions, constants, and datatypes including C pointers. As
-a general rule these files are also independent of the target scripting
-language--the primary reason why it's easy to support different
-languages.
-
-<h2> Building a Python module </h2>
-
-Building a Python module with SWIG is a simple process that proceeds as
-follows (assuming you're running Solaris 2.x) :
-
-<blockquote>
-<tt>
-<pre>
-unix > wrap -python socket.i
-unix > gcc -c socket_wrap.c -I/usr/local/include/Py
-unix > ld -G socket_wrap.o -lsocket -lnsl -o sockmodule.so
-</pre>
-</tt>
-</blockquote>
-
-The <tt> wrap </tt> command takes the interface file and produces a C file
-called <tt> socket_wrap.c </tt>. This file is then compiled and built into
-a shared object file.
-
-<h2> A sample Python script </h2>
-
-Our new socket module can be used normally within a Python script.
-For example, we could write a simple server process to echo all
-data received back to a client :
-
-<blockquote>
-<tt>
-<pre>
-# Echo server program using SWIG module
-from sock import *
-PORT = 5000
-sockfd = socket(AF_INET, SOCK_STREAM, 0)
-if sockfd < 0:
- raise IOError, 'server : unable to open stream socket'
-addr = new_sockaddr_in(AF_INET,INADDR_ANY,PORT)
-if (bind(sockfd, addr, SIZEOF_SOCKADDR)) < 0 :
- raise IOError, 'server : unable to bind local address'
-listen(sockfd,5)
-client_addr = new_sockaddr_in(AF_INET, 0, 0)
-newsockfd = accept(sockfd, client_addr, SIZEOF_SOCKADDR)
-buffer = malloc(1024)
-while 1:
- nbytes = read(newsockfd, buffer, 1024)
- if nbytes > 0 :
- write(newsockfd,buffer,nbytes)
- else : break
-close(newsockfd)
-close(sockfd)
-</pre>
-</tt>
-</blockquote>
-
-In our Python module, we are manipulating a socket, in almost
-exactly the same way as would be done in a C program. We'll take
-a look at a client written using the Python socket library shortly.
-
-<h2> Pointers and run-time type checking </h2>
-
-SWIG imports C pointers as ASCII strings containing both the
-address and pointer type. Thus, a typical SWIG pointer might look
-like the following : <br> <br>
-
-<center>
-<tt> _fd2a0_struct_sockaddr_p </tt> <br> <br>
-</center>
-
-Some may view the idea of importing C pointers into Python as unsafe or even
-truly insane. However, handling pointers seems to be needed in order
-for SWIG to handle most interesting types of C code. To provide some safety,
-the wrapper functions generated by SWIG perform pointer-type checking
-(since importing C pointers into
-Python has in effect, bypassed type-checking in the C compiler).
-When incompatible pointer types are used, this is what happens :
-
-<blockquote>
-<tt>
-<pre>
-unix > python
-Python 1.3 (Apr 12 1996) [GCC 2.5.8]
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> from sock import *
->>> sockfd = socket(AF_INET, SOCK_STREAM,0);
->>> buffer = malloc(8192);
->>> bind(sockfd,buffer,SIZEOF_SOCKADDR);
-Traceback (innermost last):
- File "<stdin>", line 1, in ?
-TypeError: Type error in argument 2 of bind. Expected _struct_sockaddr_p.
->>>
-</pre>
-</tt>
-</blockquote>
-
-
-SWIG's run-time type checking provides a certain degree of safety from
-using invalid parameters and making simple mistakes. Of course, any system
-supporting pointers can be abused, but SWIG's implementation has proven
-to be quite reliable under normal use.
-
-<h2> Comparison with a real Python module </h2>
-
-As a point of comparison, we can now write a client script using the
-Python socket module (this example courtesy of the Python library
-reference manual) [5].
-
-<blockquote>
-<tt>
-<pre>
-# Echo client program
-from socket import *
-HOST = 'tjaze.lanl.gov'
-PORT = 5000
-s = socket(AF_INET, SOCK_STREAM)
-s.connect(HOST,PORT)
-s.send('Hello world')
-data = s.recv(1024)
-s.close()
-print 'Received', `data`
-</pre>
-</tt>
-</blockquote>
-
-As one might expect, the two scripts look fairly similar. However
-there are certain obvious differences. First, the SWIG generated
-module is clearly a quick and dirty approach. We must explicitly
-check for errors and create a few C data structures. Furthermore,
-while Python functions such as <tt> socket() </tt> can take optional
-arguments, SWIG generated functions can not (since the underlying
-C function can't). Of course, the apparent ugliness
-of the SWIG module compared to the Python equivalent is not the
-point here.
-The real idea to emphasize is that SWIG
-can take a set of real C functions with moderate complexity and
-produce a fully functional Python module in a very short period of
-time. In this case, about 10 minutes worth of effort.
-(I'm
-guessing that the Python socket module required more time than that).
-With a bit of work, the SWIG generated module could probably be
-used to build a more user-friendly version that hid many of the details.
-
-<h2> Controlling C programs </h2>
-
-Of course, the real goal of SWIG is not to produce quirky
-replacements for modules in the Python library. Instead, it
-better suited as a mechanism for
-controlling a variety of C programs. <br> <br>
-
-In the SPaSM molecular dynamics code used at Los Alamos National
-Laboratory, SWIG
-is used to build an interface out of about 200 C functions [2].
-This happens at compile time so most users don't
-notice that it has occurred. However, as a result, it is now
-extremely easy for the physicists using the code to
-extend it with new functions.
-Whenever new functionality is added, the new
-functions are put into a SWIG interface file and the functions
-become available when the code is recompiled (a process
-which usually only involves the new C functions and SWIG generated
-wrapper file). Of course, when running under Python, it is possible
-to build extensions and dynamically load them as needed. <br> <br>
-
-Another point, not to be overlooked, is the fact that SWIG makes it
-very easy for a user to combine bits and pieces of completely different
-software packages without waiting for someone to write a special
-purpose module. For example, SWIG can be used to import the C API
-of Matlab 4.2 into Python. This combined with a simulation module
-can allow a scientist to perform both simulation and data analysis in
-interactively or from a script. One could even build a Tkinter interface to control
-the entire system. The ease of using SWIG makes it possible for
-scientists to build applications out of components that
-might not have been considered earlier.
-
-<h2> Prototyping and Debugging </h2>
-
-When debugging new modules or libraries, it would be nice to be able
-to test out the functions without having to repeatedly recompile the
-module with the rest of a large application. With SWIG, it is often
-possible to prototype and debug modules independently. SWIG can be
-used to build Python wrappers around the functions and scripts
-can be used for testing. In many cases, it is possible to create
-the C data structures and other information that would have been generated
-by the larger application all from within a Python script. Since
-SWIG requires no changes to the C code, integrating the new C code into
-the large package is usually pretty easy. <br> <br>
-
-A related benefit of the SWIG approach is that it is now possible
-to easily experiment with large software libraries and packages.
-Peter-Pike Sloan at the
-University of Utah, used SWIG to wrap the entire contents of the Open-GL
-library (including more than 560 constants and 340 C functions).
-This ``interpreted'' Open-GL could then be used interactively to
-determine various image parameters and to draw simple figures.
-Is this case, it proved to be a remarkably effective way of
-figuring out the effects of different parameters and functions without
-having to recompile after every modification.
-
-<h2> Living dangerously with datatypes </h2>
-
-One of the reasons SWIG is easy to use for prototyping and control
-applications is its extremely forgiving treatment of datatypes.
-<tt> typedef </tt> can be used to map datatypes, but whenever
-SWIG encounters an unknown datatype, it simply assumes that it's
-some sort of complex datatype. As a result, it's possible to
-wrap some fairly complex C code with almost no effort. For example,
-one could create a module allowing Python to create a Tcl interpreter
-and execute Tcl commands as follows :
-
-<blockquote>
-<tt>
-<pre>
-// tcl.i
-// Wrap Tcl's C interface
-%init tcl
-%{
-#include <tcl.h>
-%}
-
-Tcl_Interp *Tcl_CreateInterp(void);
-void Tcl_DeleteInterp(Tcl_Interp *interp);
-int Tcl_Eval(Tcl_Interp *interp, char *script);
-int Tcl_EvalFile(Tcl_Interp *interp, char *file);
-</pre>
-</tt>
-</blockquote>
-
-SWIG has no idea what <tt> Tcl_Interp </tt> is, but it doesn't
-really care as long as it's used as a pointer. When used in a
-Python script, this module would work as follows :
-<blockquote>
-<tt>
-<pre>
-unix > python
-Python 1.3 (Mar 26 1996) [GCC 2.7.0]
-Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
->>> import tcl
->>> interp = tcl.Tcl_CreateInterp();
->>> tcl.Tcl_Eval(interp,"for {set i 0} {$i < 5} {incr i 1} {puts $i}");
-0
-1
-2
-3
-4
-0
->>>
-</pre>
-</tt>
-</blockquote>
-
-<h2> Limitations </h2>
-
-This approach represents a balance of flexibility and ease of use.
-I have always felt that the tool shouldn't be more complicated than
-the original problem. Therefore, SWIG certainly won't do everything.
-Some of SWIG's limitations include it's limited understanding of
-complex datatypes. Often the user must write special functions
-to extract information from structures even though passing complex
-datatypes around by reference works remarkably well in practice.
-SWIG's support for C++ is also quite limited. At the moment SWIG
-can be used to pass pointers to C++ objects around, but actually
-transforming a C++ object into some sort of Python object is far
-beyond the capabilities of the current implementation. Finally, SWIG
-lacks an exception model which may be of concern to some users.
-
-<h2> Limitations in the Python implementation </h2>
-
-SWIG's support for Python is in many ways, limited by the fact that
-SWIG was originally developed for use with other languages. For example,
-representing C pointers as a character string can be seen as a carry-over
-from an earlier Tcl implementation. With a little work, I believe
-that one could create a Python "pointer" datatype while still retaining
-type-checking and other features. <br> <br>
-
-Another limitation in the current Python implementation is the apparent lack
-of variable linking support. Many applications, particularly scientific ones,
-have global variables that a user may want to access. SWIG currently
-creates Python functions for accessing these variables, but other
-scripting languages provide a more natural mechanism.
-For example, in Perl, it is
-possible to attach "set" and "get" functions to a Perl object. These
-are evaluated whenever that variable is accessed in a script.
-For all practical purposes this special variable looks like any other Perl
-variable, but is really linked to an C global variable (of course,
-maybe there is a reason why Perl calls these "magic" variables). <br> <br>
-
-If an equivalent variable linking mechanism is available in Python, I
-couldn't find it [4].
-If not, it might be possible to create a new kind of Python datatype
-that supports variable linking, but which interacts seamlessly
-with existing Python integer, floating point, and character string types.
-
-<h2> Summary and future work </h2>
-
-This paper has described work in progress with the SWIG system and
-its support for Python. I believe that this approach shows great
-promise for future work--especially within the scientific and
-engineering community. Most of the people introduced to SWIG and
-Python have
-found both systems extremely easy and straightforward to use.
-I am currently
-quite interested in improving SWIG's interface to Python and exploring
-its use with numerical Python in order to build interesting
-and flexible scientific applications [6].
-
-<h2> Acknowledgments </h2>
-
-This project would not have been possible without the support of a number
-of people. Peter Lomdahl, Shujia Zhou, Brad Holian, Tim Germann, and Niels
-Jensen at Los Alamos National Laboratory were the first users and were
-instrumental in testing out the first designs. Patrick Tullmann,
-John Schmidt,Peter-Pike Sloan, and Kurtis Bleeker at the University of Utah have also
-been instrumental in testing out some of the newer versions and
-providing feedback.
-John Buckman has suggested many interesting
-improvements and is currently working on porting SWIG to non-Unix
-platforms including NT, OS/2 and Macintosh.
-Finally
-I'd like to thank Chris Johnson and the members of the Scientific
-Computing and Imaging group at the University of Utah for their continued
-support. Some of this work was performed under the auspices of the
-Department of Energy.
-
-<h2> References </h2>
-
-[1] D.M. Beazley. <em> SWIG : An Easy to Use Tool for Integrating
-Scripting Languages with C and C++ </em>. Proceedings of the 4th
-USENIX Tcl/Tk Workshop (1996) (to appear). <br> <br>
-
-[2] D.M. Beazley and P.S. Lomdahl <em> Message-Passing Multi-Cell
-Molecular Dynamics on the Connection Machine 5 </em>, Parallel
-Computing 20 (1994), p. 173-195. <br> <br>
-
-[3] Bill Janssen and Mike Spreitzer, <em> ILU : Inter-Language
-Unification via Object Modules</em>, OOPSLA 94 Workshop on
-Multi-Language Object Models.
-<br> <br>
-
-[4] Guido van Rossum, <em> Extending and Embedding the Python Interpreter,
-</em> October 1995. <br> <br>
-
-[5] Guido van Rossum, <em> Python Library Reference </em>, October
-1995. <br> <br>
-
-[6] Paul F. Dubois, Konrad Hinsen, and James Hugunin, <em> Numerical
-Python, </em> Computers in Physics, (1996) (to appear)
-
-</body>
-</html>
diff --git a/swigweb/papers/Py97/.~beazley.html b/swigweb/papers/Py97/.~beazley.html
deleted file mode 100755
index c81c1ba..0000000
--- a/swigweb/papers/Py97/.~beazley.html
+++ /dev/null
@@ -1,762 +0,0 @@
-<html>
-<title> Feeding a Large-scale Physics Application to Python </title>
-<body bgcolor="#ffffff">
-
-<h1> Feeding a Large-scale Physics Application to Python </h1>
-
-David M. Beazley <br>
-Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 <br>
-<tt> beazley@cs.utah.edu </tt> <br>
-<p>
-Peter S. Lomdahl <br>
-Theoretical Division <br>
-Los Alamos National Laboratory <br>
-Los Alamos, New Mexico 87545 <br>
-<tt> pxl@lanl.gov </tt> <br>
-
-
-
-<h2> Abstract </h2>
-
-<em>
-We describe our experiences using Python with the SPaSM molecular
-dynamics code at Los Alamos National Laboratory. Originally developed
-as a large monolithic application for massively parallel processing
-systems, we have used Python to transform our application into a
-flexible, highly modular, and extremely powerful system for performing
-simulation, data analysis, and visualization. In addition, we
-describe how Python has solved a number of important problems related
-to the development, debugging, deployment, and maintenance of
-scientific software. </em>
-
-<h2> Background </h2>
-
-For the past 5 years, we have been developing a large-scale physics
-code for performing molecular-dynamics simulations of
-materials. This code, SPaSM (Scalable Parallel Short-range
-Molecular-dynamics), was originally developed for the Connection
-Machine 5 massively parallel supercomputing system and later moved to
-a number of other machines including the Cray T3D, multiprocessor Sun
-and SGI systems, and Unix workstations [1,2]. Our goal has
-been to investigate material properties such as fracture, crack
-propagation, dislocation generation, friction, and ductile-brittle transitions [3].
-The SPaSM code
-helps us investigate these problems by performing atomistic
-simulations--that is, we simulate the dynamics of every atom in a
-material and hope to make sense of what happens. Of course, the
-underlying physics is not so important for this discussion.
-
-<p>
-While the development of SPaSM is an ongoing effort, we
-have been hampered by a number of serious problems.
-First, typical
-simulations generate tens to hundreds of gigabytes of data that must
-be analyzed. This task is not easily performed on a user's
-workstation, nor is it economically feasible to buy everyone their own
-personal desktop supercomputer. A second problem is that of
-interactivity and control. We are constantly making changes to
-investigate new physical models, different materials, and so forth.
-This would usually require changes to the underlying C
-code--a process that was tedious and not very user friendly. We
-wanted a more flexible mechanism.
-Finally, there were many difficulties associated with the
-development and maintenance of our software. While we are only a small
-group, it was not uncommon for different users to have their
-own private copies of the software that had been modified in some manner.
-This, in turn, led to a maintenance nightmare that made it almost impossible
-to update the software or apply bug-fixes in a consistent manner.
-
-<p>
-To address these problems, we started investigating the use of scripting
-languages. In 1995, we wrote a special purpose parallel-scripting language,
-but replaced it with Python a year later (although the interface
-generation tool for that scripting language lives on as SWIG). In this
-paper, we hope to describe some of our experiences with Python and how
-it has helped us solve practical scientific computing problems. In particular,
-we describe the organization of our system, module building process,
-interesting tools that Python has helped us develop, and why we think this
-approach is particularly well-suited for scientific computing research.
-
-<h2> Why Python? </h2>
-
-Although our code originally used a custom scripting language, we decided
-to switch to Python for a number of reasons :
-
-<p>
-<ul>
-<li> Features. Python had a rich set of datatypes, support for
-object oriented programming, namespaces, exceptions, dynamic loading,
-and a large number of useful modules.
-<li> Syntax. Our system is controlled through
-text-based commands and scripts. We felt that Python had a nice
-syntax that does not require users to
-type weird symbols ($,%,@, etc...) or use syntax that is radically
-different than C.
-<li> A small core. The modular structure of Python makes it easy for us
-to remove or add modules as needed. Given the difficult task of running
-on parallel machines and supercomputers, we felt that this structure
-would make it easier for us to port Python to a variety of special-purpose
-machines (since we could just remove problematic modules).
-<li> Availability of documentation. Users could go to the bookstore
-to find out more about Python.
-<li> Support and stability. Python appeared to be highly stable and
-well supported through newsgroups, special interest groups, and the PSA.
-<li> Freely available. We have been able to
-use and modify Python as needed for our application. This would have
-been impossible without access to the Python source.
-</ul>
-
-<p>
-Another factor, not to be overlooked, is the increasing acceptance of
-Python elsewhere in the computational science community. Efforts at
-Lawrence Livermore National Laboratory and elsewhere were
-attractive--in particular, we saw Python as being a potential vehicle
-for sharing modules and utilizing third-party tools [4,9,10].
-
-<h2> System Organization </h2>
-
-Our goal was to build a highly modular system that could perform
-simulation, data analysis, and visualization--often performing
-all of these tasks simultaneously. Unfortunately, there is a tendency
-to do this by building a tightly integrated
-monolithic package (perhaps using a well-structured C++ class
-hierarchy for example). In our view, this is too
-formal and restrictive. We wanted to support modules that might only
-be loosely related to each other. For example, there is no need for a
-graphics library to depend on the same structures as a simulation code
-or to even be written in the same language for that matter. Likewise,
-we wanted to exploit third-party modules where no assumptions
-could be made about their internal structure.
-
-<p>
-The major components of our system take the form of C libraries. When
-Python is used, the libraries are compiled into shared libraries and
-dynamically loaded into Python as extension modules. The
-functionality of each library is exposed as a collection of Python
-"commands." Because of this, the C and Python programming
-environments are closely related. In many cases, it is possible to
-implement the same code in both C or Python. For example :
-
-<blockquote>
-<tt><pre>
-/* A simple function written in C */
-#include "SPaSM.h"
-void run(int nsteps, double Dt, int freq) {
- int i;
- char filename[64];
- for (i = 0; i < nsteps; i++) {
- integrate_adv_coord(Dt);
- boundary_periodic();
- redistribute();
- force_eam();
- integrate_adv_velocity(Dt);
- if ((i % freq) == 0) {
- sprintf(filename,"Dat%d",i);
- output_particles(filename);
- }
- }
-}</pre>
-</tt>
-</blockquote>
-
-Now, in Python :
-
-<blockquote><tt><pre>
-# A function written in Python
-from SPaSM import *
-def run(nsteps, Dt, freq):
- for i in xrange(0, nsteps):
- integrate_adv_coord(Dt)
- boundary_periodic()
- redistribute()
- force_eam()
- integrate_adv_velocity(Dt)
- if (i % freq) == 0) :
- output_particles('Dat'+str(i))
-</pre>
-</tt>
-</blockquote>
-
-While C libraries provide much of the underlying functionality, the real power
-of the system comes in the form of modules and scripts written entirely in Python.
-Users write scripts to set up and control simulations. Several major
-components such as the visualization and data-analysis system make heavy
-use of Python. We also utilize a variety of modules in the Python
-library and have dynamically loadable versions of Tkinter and the
-Python Imaging Library [11].
-
-<h2> Embedding Python and Hiding System Dependencies </h2>
-
-One of the biggest implementation problems we have encountered is the
-fact that the SPaSM code is a parallel application that relies heavily
-upon the proper implementation of low-level system services such as
-I/O and process management. Currently, it is possible to run the code
-in two different configurations--one that uses message passing via the
-MPI library and another using Solaris threads. Using Python with
-both versions of code requires a degree of care--in particular, we
-have found it to be necessary to provide Python with enhanced I/O
-support to run properly in parallel. This work has been described
-elsewhere [5,6].
-
-<p>
-Handling two operational modes introduces a number of problems related
-to code maintenance and installation. Traditionally, we would
-recompile the entire system and all of its modules for each
-configuration (placing the files in an architecture dependent
-subdirectory). Users would have to decide which system they wanted to
-use and compile all of their modules by linking against the
-appropriate libraries and setting the right compile-time options.
-Changing configurations would typically require a complete recompile.
-
-<p>
-With dynamic loading and shared libraries however, we have been able
-to devise a different approach to this problem. Rather
-than recompiling everything for each configuration, we use an
-implementation independent layer of system wrappers. These wrappers
-provide a generic implementation of message passing, parallel I/O, and
-thread management. All of the core modules are then compiled
-using these generic wrappers. This makes the modules independent
-of the underlying operational mode---to use MPI or threads, we simply
-need to supply a different implementation of the system wrapper libraries.
-This is easily accomplished by building two different versions of
-Python that are linked against the appropriate system libraries.
-To run in a particular mode, we now just run the appropriate
-version of Python (i.e. 'python' or 'pythonmpi'). The neat
-part about this approach is that all of the modules work with both
-operational modes without any recompilation or reconfiguration. If a
-user is using threads, but wants to switch to MPI, they simply run
-a different version of Python--no recompilation of modules is necessary.
-
-<p>
-A full discussion of writing system-wrappers can be found elsewhere.
-In particular, a discussion of writing parallel I/O wrappers for
-Python can be found in [5]. An earlier discussion of the technique we
-have used for writing message passing and I/O wrappers can also be
-found in [7].
-
-<h2> Module Building with SWIG </h2>
-
-To build modules, we have been using SWIG [8].
-Each module is described by a SWIG interface file containing the ANSI
-C declarations of functions, structures, and variables in that module.
-For example :
-
-<blockquote><pre>
-// SWIG interface file
-%module SPaSM
-%{
-#include "SPaSM.h"
-%}
-void integrate_adv_coord(double Dt);
-void boundary_periodic();
-void redistribute();
-void force_eam();
-void integrate_adv_velocity(double Dt);
-int output_particles(char *filename);
-</pre></blockquote>
-
-SWIG provides a logical mapping of the underlying C implementation into
-Python. During compilation, interface files are automatically
-converted into wrapper code and compiled into Python modules. This
-process is entirely transparent--changes made to the interface
-are automatically propagated to Python whenever a module is recompiled.
-Given the constantly evolving nature of research applications, this makes
-it easy to extend and maintain the system.
-
-<h3> Separation of Implementation and Interface </h3>
-
-An important aspect of SWIG is that it is requires no modifications to
-existing C code which allows us to maintain a strict
-separation between the implementation of C modules and their
-Python interface. We believe that this results in code that
-is more organized and generally reusable. There is no particular
-reason why a C module should depend on Python (one might
-want to use it as a stand-alone package or in a different application).
-Despite using Python extensively, the SPaSM code can still be
-compiled with no Python interface (of course, you lose all of
-the benefits gained by having Python).
-We feel that most physics codes tend
-to have a rather long life-span. Maintaining a separation of
-implementation and interface helps insure that our physics code will
-be usable in the future--even if there are drastic changes in the
-interface along the way.
-
-<h3> Providing Access to Data Structures </h3>
-
-For the purposes of debugging and data exploration, we have
-used SWIG to provide wrappers around C data structures. For example,
-a collection of C structures such as the following
-
-<blockquote><pre>
-typedef struct {
- double x,y,z;
-} Vector;
-
-typedef struct {
- int type;
- Vector r;
- Vector v;
- Vector f;
-} Particle;
-</pre></blockquote>
-
-can be turned into Python wrapper classes. In addition, SWIG can extend structures with member functions as follows :
-
-<blockquote> <pre>
-// SWIG interface for vector and particle structures
-%include datatypes.h
-
-// Extend data structures with a few useful methods
-%addmethods Vector {
- char *__str__() {
- static char a[1024];
- sprintf(a,"[ %0.10f, %0.10f, %0.10f ]", self->x, self->y, self->z);
- return a;
- }
-}
-%addmethods Particle {
- Particle *__getitem__(int index) {
- return self+index;
- }
- char *__str__() {
- // print out a particle
- ...
- }
-}
-</pre>
-</blockquote>
-
-When the Python interface is built, C structures now appear like
-Python objects. By providing Python-specific methods (such as
-<tt>__getitem__</tt>) we can even provide array access.
-For example, the following Python code would print out
-all of the coordinates of stored particles :
-
-<blockquote>
-<pre>
-# Print out all coordinates to a file
-f = open("part.data","w")
-p = SPaSM_first_particle() # Get first particle pointer
-for i in xrange(0,SPaSM_count_particles()):
- f.write("%f, %f, %f\n" % (p[i].r.x, p[i].r.y, p[i].r.z))
-f.close()
-</pre>
-</blockquote>
-
-While only a simple example, having direct access to underlying data has
-proven to be quite valuable since we view the internal representation
-of data, check values, and perform diagnostics.
-
-<h3> Improving the Reliability of Modules </h3>
-
-When instrumenting our original physics application to use scripting,
-we found that many parts of the code were not written in an entirely
-"reliable" manner. In particular, the code had never been operated in
-an event-driven manner. Functions often made assumptions about
-initializations and rarely checked the validity of input parameters.
-To address these issues, most sections of code were gradually changed
-to provide some kind of validation of input values and error recovery.
-The SWIG compiler has also been extended to provide some of these
-capabilities as well.
-<p>
-One of Python's most powerful features is its exception handling mechanism.
-Exceptions are easily raised and handled in Python scripts as follows :
-
-<blockquote><pre>
-# A Python function that throws an exception
-def allocate(nbytes):
- ptr = SPaSM_malloc(nbytes)
- if ptr == "NULL": raise MemoryError,"Out of memory!"
-
-# A Python function that catches an exception
-def foo():
- try:
- allocate(NBYTES)
- except:
- return # Bailing out
-
-</blockquote></pre>
-
-We have borrowed this idea and implemented a similar exception handling
-mechanism for our C code. This is accomplished using functions in the
-<tt><setjmp.h></tt> library and defining a few C macros for "<tt>Try</tt>", "<tt>Except</tt>",
-"<tt>Throw</tt>", etc... Using these macros, many of our library functions now look like the following :
-
-<blockquote><pre>
-/* A C function that throws an exception */
-void *SPaSM_malloc(size_t nbytes) {
- void *ptr = (void *) malloc(nbytes);
- if (!ptr) Throw("SPaSM_malloc : Out of memory!");
- return ptr;
-}
-</pre></blockquote>
-
-Like Python, we allow C functions to
-catch exceptions and provide their own recovery as follows :
-
-<blockquote> <pre>
-/* A C function catching an exception */
-int foo() {
- void *p;
- Try {
- p = SPaSM_malloc(NBYTES);
- } Except {
- printf("Unable to allocate memory. Returning!\n");
- return -1;
- }
-}
-</pre></blockquote>
-
-In the case of a stand-alone C application, exceptions can
-be caught and handled internally. Should an uncaught exception
-occur, the code prints an error message and terminates. However,
-when Python is used, we can
-generate Python exceptions using a SWIG user-defined
-exception handler such as the following :
-
-<blockquote> <pre>
-%module SPaSM
-// A SWIG user defined exception handler
-%except(python) {
- Try {
- $function
- } Except {
- PyErr_SetString(PyExc_RuntimeError,SPaSM_error_msg());
- }
-}
-// C declarations
-...
-</pre></blockquote>
-
-The handler code gets placed into all of the Python
-"wrapper" functions and is responsible for translating C exceptions
-into Python exceptions. Doing this makes our physics code operate
-in a more seamless manner and gives it a precisely defined error recovery
-procedure (i.e. internal errors always result Python exceptions). For example :
-
-<blockquote><pre>
->>> SPaSM_malloc(1000000000)
-RuntimeError: SPaSM_malloc(1000000000). Out of memory!
-(Line 52 in memory.c)
->>>
-</pre></blockquote>
-
-We have found error recovery to be critical. Without it, simulations may
-continue to run, only to generate wrong answers or a mysterious
-system crash.
-
-<h2> More Than Scripting </h2>
-
-When we originally started using scripting languages, we thought
-they would mainly be a convenient mechanism for gluing C libraries
-together and controlling them in an interactive manner. However,
-we have come to realize that scripting languages are
-much more powerful than this. Now, we find ourselves
-implementing significant functionality entirely in Python--bypassing
-C altogether. The most surprising (well, not really that surprising)
-fact is that Python makes it possible to build very powerful tools with
-only a small amount of extra programming. In this section, we present
-a brief overview of some of the tools we have developed--most of
-which have been implemented largely in Python.
-
-<h3> Object-Oriented Visualization and Data Analysis </h3>
-
-Our original goal was to add a powerful data analysis and
-visualization component to our application. To this end, we developed
-a lightweight high-performance graphics library implemented in C.
-This library supports both 2D and 3D plotting and produces output in
-the form of GIF images. To make plots, a user writes simple C
-functions such as the following :
-
-<blockquote><pre>
-void plot_spheres(Plot3D *p3, DataFunction func, double min, double max,
- double radius) {
- Particle *p = Particles;
- int i, npart, color;
- npart = SPaSM_count_particles();
- for (i = 0; i < npart; i++, p++) {
- /* Compute color value */
- value = (*func)(p);
- color = (value-min)/(max-min)*255;
- /* Plot it */
- Plot3D_sphere(p3,p->r.x,p->r.y,p->r.z,radius,color);
- }
-}
-</pre></blockquote>
-When executed, this function produces a raw image such as the following
-showing stacking-faults generated by a passing shock wave in an fcc crystal
-of 10 million atoms :
-<p>
-<center>
-<img src="bigshockraw.gif">
-</center>
-<p>
-While simple, we often want our images to contain more information
-including titles, axis labels, colorbars, time-stamps, and bounding
-boxes. To do this, we have built an object-oriented visualization
-framework in Python. Python classes provide methods for graph annotation
-and common graph operations. If a user wants to make a new kind of plot,
-they simply inherit from an appropriate base class and provide a function
-to plot the desired data. For example, a "Sphere" plot using the above C
-function would look like this :
-
-<blockquote><pre>
-class Spheres(Image3D):
- def __init__(self, func, min, max, radius=0.5):
- Image3D.__init__(self, ...
- self.func = func
- self.min = min
- self.max = max
- self.radius = radius
- def draw(self):
- self.newplot()
- plot_spheres(self.p3,self.func,self.min,self.max,self.radius)
-</pre></blockquote>
-
-To use the new image, one simply creates an object of that type and
-manipulates it. For example :
-
-<blockquote><pre>
->>> s = Spheres(PE,-8,-3.5) # Create a new image
->>> s.rotd(45) # Rotate it down
->>> s.zoom(200) # Zoom in
->>> s.show() # generate Image and display it
->>> ...
-</pre></blockquote>
-
-<center>
-<img src="bigshock.gif">
-</center>
-
-<p>
-Thus, with a simple C function and a simple Python class, we get a lot
-of functionality for free, including methods for image manipulation,
-graph annotation, and display. In the current system, there are about
-a dozen different types of images for 2D and 3D plotting. It is also
-possible to perform filtering, apply clipping planes, and other
-advanced operations. Most of this is supported by about 2000 lines of
-Python code and a relatively small C library containing performance
-critical operations.
-
-<h3> Web-Based Simulation Monitoring </h3>
-
-One feature of many physics codes is that they tend to run for a long
-time. In our case, a simulation may run for tens to hundreds of
-hours. During the course of a simulation, it is desirable to check on
-its status and see how it is progressing. Given the strong Internet
-support already bundled with Python, we decided to write a simple
-physics web-server that could be used for this purpose. Unlike a
-more traditional server, our server is used by "registering" various
-objects that one wants to look at during the course of a simulation.
-The simulation code then periodically polls a network socket to see if
-anyone has requested anything. If so, the simulation will stop for a
-moment, generate the requested information, send it to the user, and
-then continue on with the calculation. A simplified example of using
-the server is as follows :
-
-<blockquote> <pre>
-# Simplified script using a web-server
-from vis import *
-from web import *
-
-web = SPaSMWeb()
-web.add(WebMain(""))
-web.add(WebFileText("Msg"+`run_no`))
-
-# Create an image object
-
-set_graphics_mode(HTTP)
-ke = Spheres(KE,0,20)
-ke.title = "Kinetic Energy"
-web.add(WebImage("ke.gif",ke))
-
-def run(nsteps):
- for i in xrange(0,nsteps):
- integrate(1) # Integrate 1 timestep
- web.poll() # Anyone looking for me?
-
-# Run it
-run(10000)
-</pre></blockquote>
-
-While simple, this example gives the basic idea. We create a
-server object and register a few "links." When a user connects with
-the server, they will be presented with some status information and a
-list of available links. When the links are accessed, the server
-feeds real-time data back to the user. In the case of
-images, they are generated immediately and sent back in GIF format. During
-this process, no temporary files are created, nor is the server
-transmitting previously stored information (i.e. everything is
-created on-the-fly).
-
-<p>
-While we are still refining the implementation, this approach has turned
-out to be useful--not only can we periodically check up
-on a running simulation, this can can be done from any machine that
-has a Web-browser, including PCs and Macs running over a modem line
-(allowing a bored physicist to check on long-running jobs from home
-or while on travel). Of course, the most amazing fact of all is that
-this was implemented by one person in an afternoon and only involved
-about 150 lines of Python code (with generous help from the Python library).
-
-<h3> Development Support </h3>
-
-Finally, we have found Python to be quite useful for supporting
-the future development of our code. Some of this comes in the form of
-sophisticated debugging--Python can be used to analyze internal data
-structures and track down problems. Since Python can read
-and modify most of the core C data structures, it is possible to
-prototype new functions or to perform one-time operations without ever
-loading up the C compiler.
-
-<p>
-We have also used Python in conjunction with code
-management. One of the newer problems we have faced is the task of
-finding the definitions of C functions (for example,
-we might want to know how a particular command has been
-implemented in C). To support this, we have written tools for
-browsing source directories, displaying definitions, and spawning
-editors. All of this is implemented in Python and can be performed
-directly from the Physics application. Python has made these kinds
-of tools very easy to write--often only requiring a few hours of
-effort.
-
-<h2> Python and the Development of Scientific Software </h2>
-
-The adoption of Python has had a profound effect on the overall
-structure of our application. With time, the code became more
-modular, more reliable, and better organized.
-Furthermore, these gains have been achieved
-without significant losses in performance, increased coding complexity,
-or substantially increased development cost. It should also be stressed
-that automated tools such as SWIG have played a critical role in this
-effort by hiding the Python-C interface and allowing us to concentrate
-on the real problems at hand (i.e. physics).
-
-<p>
-One point, that we would like to strongly emphasize, is the dynamic
-nature of many scientific applications. Our application is not a huge
-monolithic package that never changes and which no one is supposed to
-modify. Rather, the code is <em>constantly</em> changing to explore
-new problems, try new numerical methods, or to provide better
-performance. The highly modular nature of Python works great in
-this environment. We provide a common repository of modules that are shared by all
-of the users of the system. Different users are typically responsible
-for different modules and all users may be working on different modules
-at the same time.
-Whenever changes to a module are made, they are immediately propagated
-to everyone else. In the case of bug-fixes, this means that patched
-versions of code are available immediately. Likewise, new
-features show up automatically and can be easily tested by everyone.
-And of course, if something breaks--others tend to notice almost immediately
-(which we feel is a good thing).
-
-<h2> Limitations of Python </h2>
-
-While we consider our Python "experiment" to be highly successful, we
-have experienced a number of problems along the way. The first is
-merely a technical issue--it would be nice if the mechanism for
-building static extensions to Python were made easier. While we are
-currently using dynamic loading, many machines, especially
-supercomputing systems, do not support it. On these machines it is
-necessary to staticly link everything. Libraries help simplify the
-task, but combining different statically linked modules together into
-a single Python interpreter still remains magical and somewhat
-problematic (especially since we are creating an application that
-changes a lot--not merely trying to patch the Python core with a new
-extension module).
-
-<p>
-A second problem is that of education--we have found that some users
-have a very difficult time making sense of the system (even we're
-somewhat amazed that it really works).
-Interestingly enough, this does not seem to be directly related to the
-use of C code or Python for that matter, but to issues related to the
-configuration, compilation, debugging, and installation of modules. While most
-users have written programs before, they have never dealt with shared
-libraries, automated code generators, high-level languages, and third-party packages
-such as Python. In other cases, there seems to be a
-"fear of autoconf"--if a program requires a configure script, it must
-be too complicated to understand (which is not the case
-here). The combination of these
-factors has led some users to believe that the system is far more
-complicated and fragile than it really is. We're not sure how to combat
-this problem other than to try and educate the users
-(i.e. it's essentially the same code as before, but with a really cool
-hack).
-
-<h2> Conclusions and Future Work </h2>
-
-Python is cool and we plan to keep using it. However much work
-remains. One of the more exciting aspects of Python is its solid
-support for modular programming and the culture of cooperation in the
-Python community. There are already many Python-related scientific
-computing projects underway. If these efforts were coordinated
-in some manner, we feel that the results could be spectacular.
-
-<h2> Acknowledgments </h2>
-
-We would like acknowledge our collaborators Brad Holian, Tim Germann, Shujia Zhou, and Wanshu Huang at Los Alamos National Laboratory. We would also like
-to acknowledge Paul Dubois and Brian Yang at Lawrence Livermore
-National Laboratory for many interesting conversations concerning Python
-and its use in physics applications. We would also like to
-acknowledge the Scientific Computing and Imaging Group at the
-University of Utah for their continued support. Finally, we'd like to
-thank the entire Python development community for making a truly
-awesome tool for solving real problems. Development of the SPaSM code
-has been performed under the auspices of the United States Department
-of Energy.
-
-<h2> References </h2>
-
-<p>
-[1] D.M.Beazley and P.S. Lomdahl, "Message
-Passing Multi-Cell Molecular Dynamics on the Connection Machine 5,"
-Parallel Computing 20 (1994), p. 173-195. <p>
-
-<p>
-[2] P.S.Lomdahl, P.Tamayo, N.Gronbech-Jensen,
-and D.M.Beazley, "50 Gflops Molecular Dynamics on the CM-5," Proceedings
-of Supercomputing 93, IEEE Computer Society (1993), p.520-527. <p>
-
-<p>
-[3] S.J.Zhou, D.M. Beazley, P.S. Lomdahl, B.L. Holian, Physical Review
-Letters. 78, 479 (1997).
-
-<p>
-[4] P. Dubois, K. Hinsen, and J. Hugunin, Computers in Physics (10), (1996)
-p. 262-267.
-
-<p>
-[5] D. M. Beazley and P.S. Lomdahl, "Extensible Message Passing Application
-Development and Debugging with Python", Proceedings of IPPS'97, Geneva
-Switzerland, IEEE Computer Society (1997).
-
-<p>
-[6] T.-Y.B. Yang, D.M. Beazley, P. F. Dubois, G. Furnish, "Steering Object-oriented Computations with
-Python", Python Workshop 5, Washington D.C., Nov. 4-5, 1996.
-
-<p>
-[7] D.M. Beazley and P.S. Lomdahl, "High
-Performance Molecular Dynamics Modeling with SPaSM : Performance and
-Portability Issues," Proceedings of the Workshop on Debugging and
-Tuning for Parallel Computer Systems, Chatham, MA, 1994 (IEEE Computer
-Society Press, Los Alamitos, CA, 1996), pp. 337-351.
-
-<p>
-[8] D.M. Beazley, "Using SWIG to Control, Prototype, and Debug C Programs with Python",
-Proceedings of the 4th International Python Conference, Lawrence Livermore
-National Laboratory, June 3-6, 1996.
-
-<p>
-[9] K. Hinsen, The Molecular Modeling Toolkit, <tt>http://starship.skyport.net/crew/hinsen/mmtk.html</tt>
-
-<p>
-[10] Jim Hugunin, Numeric Python, <tt>http://www.sls.lcs.mit.edu/jjh/numpy</tt>
-
-<p>
-[11] Fredrik Lundh, Python Imaging Library, <tt>http://www.python.org/sigs/image-sig/Imaging.html</tt>
-</body>
-</html>
diff --git a/swigweb/papers/Py97/beazley.html b/swigweb/papers/Py97/beazley.html
deleted file mode 100755
index 32322c4..0000000
--- a/swigweb/papers/Py97/beazley.html
+++ /dev/null
@@ -1,763 +0,0 @@
-<html>
-<title> Feeding a Large-scale Physics Application to Python </title>
-<body bgcolor="#ffffff">
-
-<h1> Feeding a Large-scale Physics Application to Python </h1>
-
-David M. Beazley <br>
-Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 <br>
-<tt> beazley@cs.utah.edu </tt> <br>
-<p>
-Peter S. Lomdahl <br>
-Theoretical Division <br>
-Los Alamos National Laboratory <br>
-Los Alamos, New Mexico 87545 <br>
-<tt> pxl@lanl.gov </tt> <br>
-
-<p>
-(Presented at the 6th International Python Conference, San Jose, California. October 14-17, 1997).
-
-<h2> Abstract </h2>
-
-<em>
-We describe our experiences using Python with the SPaSM molecular
-dynamics code at Los Alamos National Laboratory. Originally developed
-as a large monolithic application for massively parallel processing
-systems, we have used Python to transform our application into a
-flexible, highly modular, and extremely powerful system for performing
-simulation, data analysis, and visualization. In addition, we
-describe how Python has solved a number of important problems related
-to the development, debugging, deployment, and maintenance of
-scientific software. </em>
-
-<h2> Background </h2>
-
-For the past 5 years, we have been developing a large-scale physics
-code for performing molecular-dynamics simulations of
-materials. This code, SPaSM (Scalable Parallel Short-range
-Molecular-dynamics), was originally developed for the Connection
-Machine 5 massively parallel supercomputing system and later moved to
-a number of other machines including the Cray T3D, multiprocessor Sun
-and SGI systems, and Unix workstations [1,2]. Our goal has
-been to investigate material properties such as fracture, crack
-propagation, dislocation generation, friction, and ductile-brittle transitions [3].
-The SPaSM code
-helps us investigate these problems by performing atomistic
-simulations--that is, we simulate the dynamics of every atom in a
-material and hope to make sense of what happens. Of course, the
-underlying physics is not so important for this discussion.
-
-<p>
-While the development of SPaSM is an ongoing effort, we
-have been hampered by a number of serious problems.
-First, typical
-simulations generate tens to hundreds of gigabytes of data that must
-be analyzed. This task is not easily performed on a user's
-workstation, nor is it economically feasible to buy everyone their own
-personal desktop supercomputer. A second problem is that of
-interactivity and control. We are constantly making changes to
-investigate new physical models, different materials, and so forth.
-This would usually require changes to the underlying C
-code--a process that was tedious and not very user friendly. We
-wanted a more flexible mechanism.
-Finally, there were many difficulties associated with the
-development and maintenance of our software. While we are only a small
-group, it was not uncommon for different users to have their
-own private copies of the software that had been modified in some manner.
-This, in turn, led to a maintenance nightmare that made it almost impossible
-to update the software or apply bug-fixes in a consistent manner.
-
-<p>
-To address these problems, we started investigating the use of scripting
-languages. In 1995, we wrote a special purpose parallel-scripting language,
-but replaced it with Python a year later (although the interface
-generation tool for that scripting language lives on as SWIG). In this
-paper, we hope to describe some of our experiences with Python and how
-it has helped us solve practical scientific computing problems. In particular,
-we describe the organization of our system, module building process,
-interesting tools that Python has helped us develop, and why we think this
-approach is particularly well-suited for scientific computing research.
-
-<h2> Why Python? </h2>
-
-Although our code originally used a custom scripting language, we decided
-to switch to Python for a number of reasons :
-
-<p>
-<ul>
-<li> Features. Python had a rich set of datatypes, support for
-object oriented programming, namespaces, exceptions, dynamic loading,
-and a large number of useful modules.
-<li> Syntax. Our system is controlled through
-text-based commands and scripts. We felt that Python had a nice
-syntax that does not require users to
-type weird symbols ($,%,@, etc...) or use syntax that is radically
-different than C.
-<li> A small core. The modular structure of Python makes it easy for us
-to remove or add modules as needed. Given the difficult task of running
-on parallel machines and supercomputers, we felt that this structure
-would make it easier for us to port Python to a variety of special-purpose
-machines (since we could just remove problematic modules).
-<li> Availability of documentation. Users could go to the bookstore
-to find out more about Python.
-<li> Support and stability. Python appeared to be highly stable and
-well supported through newsgroups, special interest groups, and the PSA.
-<li> Freely available. We have been able to
-use and modify Python as needed for our application. This would have
-been impossible without access to the Python source.
-</ul>
-
-<p>
-Another factor, not to be overlooked, is the increasing acceptance of
-Python elsewhere in the computational science community. Efforts at
-Lawrence Livermore National Laboratory and elsewhere were
-attractive--in particular, we saw Python as being a potential vehicle
-for sharing modules and utilizing third-party tools [4,9,10].
-
-<h2> System Organization </h2>
-
-Our goal was to build a highly modular system that could perform
-simulation, data analysis, and visualization--often performing
-all of these tasks simultaneously. Unfortunately, there is a tendency
-to do this by building a tightly integrated
-monolithic package (perhaps using a well-structured C++ class
-hierarchy for example). In our view, this is too
-formal and restrictive. We wanted to support modules that might only
-be loosely related to each other. For example, there is no need for a
-graphics library to depend on the same structures as a simulation code
-or to even be written in the same language for that matter. Likewise,
-we wanted to exploit third-party modules where no assumptions
-could be made about their internal structure.
-
-<p>
-The major components of our system take the form of C libraries. When
-Python is used, the libraries are compiled into shared libraries and
-dynamically loaded into Python as extension modules. The
-functionality of each library is exposed as a collection of Python
-"commands." Because of this, the C and Python programming
-environments are closely related. In many cases, it is possible to
-implement the same code in both C or Python. For example :
-
-<blockquote>
-<tt><pre>
-/* A simple function written in C */
-#include "SPaSM.h"
-void run(int nsteps, double Dt, int freq) {
- int i;
- char filename[64];
- for (i = 0; i < nsteps; i++) {
- integrate_adv_coord(Dt);
- boundary_periodic();
- redistribute();
- force_eam();
- integrate_adv_velocity(Dt);
- if ((i % freq) == 0) {
- sprintf(filename,"Dat%d",i);
- output_particles(filename);
- }
- }
-}</pre>
-</tt>
-</blockquote>
-
-Now, in Python :
-
-<blockquote><tt><pre>
-# A function written in Python
-from SPaSM import *
-def run(nsteps, Dt, freq):
- for i in xrange(0, nsteps):
- integrate_adv_coord(Dt)
- boundary_periodic()
- redistribute()
- force_eam()
- integrate_adv_velocity(Dt)
- if (i % freq) == 0) :
- output_particles('Dat'+str(i))
-</pre>
-</tt>
-</blockquote>
-
-While C libraries provide much of the underlying functionality, the real power
-of the system comes in the form of modules and scripts written entirely in Python.
-Users write scripts to set up and control simulations. Several major
-components such as the visualization and data-analysis system make heavy
-use of Python. We also utilize a variety of modules in the Python
-library and have dynamically loadable versions of Tkinter and the
-Python Imaging Library [11].
-
-<h2> Embedding Python and Hiding System Dependencies </h2>
-
-One of the biggest implementation problems we have encountered is the
-fact that the SPaSM code is a parallel application that relies heavily
-upon the proper implementation of low-level system services such as
-I/O and process management. Currently, it is possible to run the code
-in two different configurations--one that uses message passing via the
-MPI library and another using Solaris threads. Using Python with
-both versions of code requires a degree of care--in particular, we
-have found it to be necessary to provide Python with enhanced I/O
-support to run properly in parallel. This work has been described
-elsewhere [5,6].
-
-<p>
-Handling two operational modes introduces a number of problems related
-to code maintenance and installation. Traditionally, we would
-recompile the entire system and all of its modules for each
-configuration (placing the files in an architecture dependent
-subdirectory). Users would have to decide which system they wanted to
-use and compile all of their modules by linking against the
-appropriate libraries and setting the right compile-time options.
-Changing configurations would typically require a complete recompile.
-
-<p>
-With dynamic loading and shared libraries however, we have been able
-to devise a different approach to this problem. Rather
-than recompiling everything for each configuration, we use an
-implementation independent layer of system wrappers. These wrappers
-provide a generic implementation of message passing, parallel I/O, and
-thread management. All of the core modules are then compiled
-using these generic wrappers. This makes the modules independent
-of the underlying operational mode---to use MPI or threads, we simply
-need to supply a different implementation of the system wrapper libraries.
-This is easily accomplished by building two different versions of
-Python that are linked against the appropriate system libraries.
-To run in a particular mode, we now just run the appropriate
-version of Python (i.e. 'python' or 'pythonmpi'). The neat
-part about this approach is that all of the modules work with both
-operational modes without any recompilation or reconfiguration. If a
-user is using threads, but wants to switch to MPI, they simply run
-a different version of Python--no recompilation of modules is necessary.
-
-<p>
-A full discussion of writing system-wrappers can be found elsewhere.
-In particular, a discussion of writing parallel I/O wrappers for
-Python can be found in [5]. An earlier discussion of the technique we
-have used for writing message passing and I/O wrappers can also be
-found in [7].
-
-<h2> Module Building with SWIG </h2>
-
-To build modules, we have been using SWIG [8].
-Each module is described by a SWIG interface file containing the ANSI
-C declarations of functions, structures, and variables in that module.
-For example :
-
-<blockquote><pre>
-// SWIG interface file
-%module SPaSM
-%{
-#include "SPaSM.h"
-%}
-void integrate_adv_coord(double Dt);
-void boundary_periodic();
-void redistribute();
-void force_eam();
-void integrate_adv_velocity(double Dt);
-int output_particles(char *filename);
-</pre></blockquote>
-
-SWIG provides a logical mapping of the underlying C implementation into
-Python. During compilation, interface files are automatically
-converted into wrapper code and compiled into Python modules. This
-process is entirely transparent--changes made to the interface
-are automatically propagated to Python whenever a module is recompiled.
-Given the constantly evolving nature of research applications, this makes
-it easy to extend and maintain the system.
-
-<h3> Separation of Implementation and Interface </h3>
-
-An important aspect of SWIG is that it is requires no modifications to
-existing C code which allows us to maintain a strict
-separation between the implementation of C modules and their
-Python interface. We believe that this results in code that
-is more organized and generally reusable. There is no particular
-reason why a C module should depend on Python (one might
-want to use it as a stand-alone package or in a different application).
-Despite using Python extensively, the SPaSM code can still be
-compiled with no Python interface (of course, you lose all of
-the benefits gained by having Python).
-We feel that most physics codes tend
-to have a rather long life-span. Maintaining a separation of
-implementation and interface helps insure that our physics code will
-be usable in the future--even if there are drastic changes in the
-interface along the way.
-
-<h3> Providing Access to Data Structures </h3>
-
-For the purposes of debugging and data exploration, we have
-used SWIG to provide wrappers around C data structures. For example,
-a collection of C structures such as the following
-
-<blockquote><pre>
-typedef struct {
- double x,y,z;
-} Vector;
-
-typedef struct {
- int type;
- Vector r;
- Vector v;
- Vector f;
-} Particle;
-</pre></blockquote>
-
-can be turned into Python wrapper classes. In addition, SWIG can extend structures with member functions as follows :
-
-<blockquote> <pre>
-// SWIG interface for vector and particle structures
-%include datatypes.h
-
-// Extend data structures with a few useful methods
-%addmethods Vector {
- char *__str__() {
- static char a[1024];
- sprintf(a,"[ %0.10f, %0.10f, %0.10f ]", self->x, self->y, self->z);
- return a;
- }
-}
-%addmethods Particle {
- Particle *__getitem__(int index) {
- return self+index;
- }
- char *__str__() {
- // print out a particle
- ...
- }
-}
-</pre>
-</blockquote>
-
-When the Python interface is built, C structures now appear like
-Python objects. By providing Python-specific methods (such as
-<tt>__getitem__</tt>) we can even provide array access.
-For example, the following Python code would print out
-all of the coordinates of stored particles :
-
-<blockquote>
-<pre>
-# Print out all coordinates to a file
-f = open("part.data","w")
-p = SPaSM_first_particle() # Get first particle pointer
-for i in xrange(0,SPaSM_count_particles()):
- f.write("%f, %f, %f\n" % (p[i].r.x, p[i].r.y, p[i].r.z))
-f.close()
-</pre>
-</blockquote>
-
-While only a simple example, having direct access to underlying data has
-proven to be quite valuable since we view the internal representation
-of data, check values, and perform diagnostics.
-
-<h3> Improving the Reliability of Modules </h3>
-
-When instrumenting our original physics application to use scripting,
-we found that many parts of the code were not written in an entirely
-"reliable" manner. In particular, the code had never been operated in
-an event-driven manner. Functions often made assumptions about
-initializations and rarely checked the validity of input parameters.
-To address these issues, most sections of code were gradually changed
-to provide some kind of validation of input values and error recovery.
-The SWIG compiler has also been extended to provide some of these
-capabilities as well.
-<p>
-One of Python's most powerful features is its exception handling mechanism.
-Exceptions are easily raised and handled in Python scripts as follows :
-
-<blockquote><pre>
-# A Python function that throws an exception
-def allocate(nbytes):
- ptr = SPaSM_malloc(nbytes)
- if ptr == "NULL": raise MemoryError,"Out of memory!"
-
-# A Python function that catches an exception
-def foo():
- try:
- allocate(NBYTES)
- except:
- return # Bailing out
-
-</blockquote></pre>
-
-We have borrowed this idea and implemented a similar exception handling
-mechanism for our C code. This is accomplished using functions in the
-<tt><setjmp.h></tt> library and defining a few C macros for "<tt>Try</tt>", "<tt>Except</tt>",
-"<tt>Throw</tt>", etc... Using these macros, many of our library functions now look like the following :
-
-<blockquote><pre>
-/* A C function that throws an exception */
-void *SPaSM_malloc(size_t nbytes) {
- void *ptr = (void *) malloc(nbytes);
- if (!ptr) Throw("SPaSM_malloc : Out of memory!");
- return ptr;
-}
-</pre></blockquote>
-
-Like Python, we allow C functions to
-catch exceptions and provide their own recovery as follows :
-
-<blockquote> <pre>
-/* A C function catching an exception */
-int foo() {
- void *p;
- Try {
- p = SPaSM_malloc(NBYTES);
- } Except {
- printf("Unable to allocate memory. Returning!\n");
- return -1;
- }
-}
-</pre></blockquote>
-
-In the case of a stand-alone C application, exceptions can
-be caught and handled internally. Should an uncaught exception
-occur, the code prints an error message and terminates. However,
-when Python is used, we can
-generate Python exceptions using a SWIG user-defined
-exception handler such as the following :
-
-<blockquote> <pre>
-%module SPaSM
-// A SWIG user defined exception handler
-%except(python) {
- Try {
- $function
- } Except {
- PyErr_SetString(PyExc_RuntimeError,SPaSM_error_msg());
- }
-}
-// C declarations
-...
-</pre></blockquote>
-
-The handler code gets placed into all of the Python
-"wrapper" functions and is responsible for translating C exceptions
-into Python exceptions. Doing this makes our physics code operate
-in a more seamless manner and gives it a precisely defined error recovery
-procedure (i.e. internal errors always result Python exceptions). For example :
-
-<blockquote><pre>
->>> SPaSM_malloc(1000000000)
-RuntimeError: SPaSM_malloc(1000000000). Out of memory!
-(Line 52 in memory.c)
->>>
-</pre></blockquote>
-
-We have found error recovery to be critical. Without it, simulations may
-continue to run, only to generate wrong answers or a mysterious
-system crash.
-
-<h2> More Than Scripting </h2>
-
-When we originally started using scripting languages, we thought
-they would mainly be a convenient mechanism for gluing C libraries
-together and controlling them in an interactive manner. However,
-we have come to realize that scripting languages are
-much more powerful than this. Now, we find ourselves
-implementing significant functionality entirely in Python--bypassing
-C altogether. The most surprising (well, not really that surprising)
-fact is that Python makes it possible to build very powerful tools with
-only a small amount of extra programming. In this section, we present
-a brief overview of some of the tools we have developed--most of
-which have been implemented largely in Python.
-
-<h3> Object-Oriented Visualization and Data Analysis </h3>
-
-Our original goal was to add a powerful data analysis and
-visualization component to our application. To this end, we developed
-a lightweight high-performance graphics library implemented in C.
-This library supports both 2D and 3D plotting and produces output in
-the form of GIF images. To make plots, a user writes simple C
-functions such as the following :
-
-<blockquote><pre>
-void plot_spheres(Plot3D *p3, DataFunction func, double min, double max,
- double radius) {
- Particle *p = Particles;
- int i, npart, color;
- npart = SPaSM_count_particles();
- for (i = 0; i < npart; i++, p++) {
- /* Compute color value */
- value = (*func)(p);
- color = (value-min)/(max-min)*255;
- /* Plot it */
- Plot3D_sphere(p3,p->r.x,p->r.y,p->r.z,radius,color);
- }
-}
-</pre></blockquote>
-When executed, this function produces a raw image such as the following
-showing stacking-faults generated by a passing shock wave in an fcc crystal
-of 10 million atoms :
-<p>
-<center>
-<img src="bigshockraw.gif">
-</center>
-<p>
-While simple, we often want our images to contain more information
-including titles, axis labels, colorbars, time-stamps, and bounding
-boxes. To do this, we have built an object-oriented visualization
-framework in Python. Python classes provide methods for graph annotation
-and common graph operations. If a user wants to make a new kind of plot,
-they simply inherit from an appropriate base class and provide a function
-to plot the desired data. For example, a "Sphere" plot using the above C
-function would look like this :
-
-<blockquote><pre>
-class Spheres(Image3D):
- def __init__(self, func, min, max, radius=0.5):
- Image3D.__init__(self, ...
- self.func = func
- self.min = min
- self.max = max
- self.radius = radius
- def draw(self):
- self.newplot()
- plot_spheres(self.p3,self.func,self.min,self.max,self.radius)
-</pre></blockquote>
-
-To use the new image, one simply creates an object of that type and
-manipulates it. For example :
-
-<blockquote><pre>
->>> s = Spheres(PE,-8,-3.5) # Create a new image
->>> s.rotd(45) # Rotate it down
->>> s.zoom(200) # Zoom in
->>> s.show() # generate Image and display it
->>> ...
-</pre></blockquote>
-
-<center>
-<img src="bigshock.gif">
-</center>
-
-<p>
-Thus, with a simple C function and a simple Python class, we get a lot
-of functionality for free, including methods for image manipulation,
-graph annotation, and display. In the current system, there are about
-a dozen different types of images for 2D and 3D plotting. It is also
-possible to perform filtering, apply clipping planes, and other
-advanced operations. Most of this is supported by about 2000 lines of
-Python code and a relatively small C library containing performance
-critical operations.
-
-<h3> Web-Based Simulation Monitoring </h3>
-
-One feature of many physics codes is that they tend to run for a long
-time. In our case, a simulation may run for tens to hundreds of
-hours. During the course of a simulation, it is desirable to check on
-its status and see how it is progressing. Given the strong Internet
-support already bundled with Python, we decided to write a simple
-physics web-server that could be used for this purpose. Unlike a
-more traditional server, our server is used by "registering" various
-objects that one wants to look at during the course of a simulation.
-The simulation code then periodically polls a network socket to see if
-anyone has requested anything. If so, the simulation will stop for a
-moment, generate the requested information, send it to the user, and
-then continue on with the calculation. A simplified example of using
-the server is as follows :
-
-<blockquote> <pre>
-# Simplified script using a web-server
-from vis import *
-from web import *
-
-web = SPaSMWeb()
-web.add(WebMain(""))
-web.add(WebFileText("Msg"+`run_no`))
-
-# Create an image object
-
-set_graphics_mode(HTTP)
-ke = Spheres(KE,0,20)
-ke.title = "Kinetic Energy"
-web.add(WebImage("ke.gif",ke))
-
-def run(nsteps):
- for i in xrange(0,nsteps):
- integrate(1) # Integrate 1 timestep
- web.poll() # Anyone looking for me?
-
-# Run it
-run(10000)
-</pre></blockquote>
-
-While simple, this example gives the basic idea. We create a
-server object and register a few "links." When a user connects with
-the server, they will be presented with some status information and a
-list of available links. When the links are accessed, the server
-feeds real-time data back to the user. In the case of
-images, they are generated immediately and sent back in GIF format. During
-this process, no temporary files are created, nor is the server
-transmitting previously stored information (i.e. everything is
-created on-the-fly).
-
-<p>
-While we are still refining the implementation, this approach has turned
-out to be useful--not only can we periodically check up
-on a running simulation, this can can be done from any machine that
-has a Web-browser, including PCs and Macs running over a modem line
-(allowing a bored physicist to check on long-running jobs from home
-or while on travel). Of course, the most amazing fact of all is that
-this was implemented by one person in an afternoon and only involved
-about 150 lines of Python code (with generous help from the Python library).
-
-<h3> Development Support </h3>
-
-Finally, we have found Python to be quite useful for supporting
-the future development of our code. Some of this comes in the form of
-sophisticated debugging--Python can be used to analyze internal data
-structures and track down problems. Since Python can read
-and modify most of the core C data structures, it is possible to
-prototype new functions or to perform one-time operations without ever
-loading up the C compiler.
-
-<p>
-We have also used Python in conjunction with code
-management. One of the newer problems we have faced is the task of
-finding the definitions of C functions (for example,
-we might want to know how a particular command has been
-implemented in C). To support this, we have written tools for
-browsing source directories, displaying definitions, and spawning
-editors. All of this is implemented in Python and can be performed
-directly from the Physics application. Python has made these kinds
-of tools very easy to write--often only requiring a few hours of
-effort.
-
-<h2> Python and the Development of Scientific Software </h2>
-
-The adoption of Python has had a profound effect on the overall
-structure of our application. With time, the code became more
-modular, more reliable, and better organized.
-Furthermore, these gains have been achieved
-without significant losses in performance, increased coding complexity,
-or substantially increased development cost. It should also be stressed
-that automated tools such as SWIG have played a critical role in this
-effort by hiding the Python-C interface and allowing us to concentrate
-on the real problems at hand (i.e. physics).
-
-<p>
-One point, that we would like to strongly emphasize, is the dynamic
-nature of many scientific applications. Our application is not a huge
-monolithic package that never changes and which no one is supposed to
-modify. Rather, the code is <em>constantly</em> changing to explore
-new problems, try new numerical methods, or to provide better
-performance. The highly modular nature of Python works great in
-this environment. We provide a common repository of modules that are shared by all
-of the users of the system. Different users are typically responsible
-for different modules and all users may be working on different modules
-at the same time.
-Whenever changes to a module are made, they are immediately propagated
-to everyone else. In the case of bug-fixes, this means that patched
-versions of code are available immediately. Likewise, new
-features show up automatically and can be easily tested by everyone.
-And of course, if something breaks--others tend to notice almost immediately
-(which we feel is a good thing).
-
-<h2> Limitations of Python </h2>
-
-While we consider our Python "experiment" to be highly successful, we
-have experienced a number of problems along the way. The first is
-merely a technical issue--it would be nice if the mechanism for
-building static extensions to Python were made easier. While we are
-currently using dynamic loading, many machines, especially
-supercomputing systems, do not support it. On these machines it is
-necessary to staticly link everything. Libraries help simplify the
-task, but combining different statically linked modules together into
-a single Python interpreter still remains magical and somewhat
-problematic (especially since we are creating an application that
-changes a lot--not merely trying to patch the Python core with a new
-extension module).
-
-<p>
-A second problem is that of education--we have found that some users
-have a very difficult time making sense of the system (even we're
-somewhat amazed that it really works).
-Interestingly enough, this does not seem to be directly related to the
-use of C code or Python for that matter, but to issues related to the
-configuration, compilation, debugging, and installation of modules. While most
-users have written programs before, they have never dealt with shared
-libraries, automated code generators, high-level languages, and third-party packages
-such as Python. In other cases, there seems to be a
-"fear of autoconf"--if a program requires a configure script, it must
-be too complicated to understand (which is not the case
-here). The combination of these
-factors has led some users to believe that the system is far more
-complicated and fragile than it really is. We're not sure how to combat
-this problem other than to try and educate the users
-(i.e. it's essentially the same code as before, but with a really cool
-hack).
-
-<h2> Conclusions and Future Work </h2>
-
-Python is cool and we plan to keep using it. However much work
-remains. One of the more exciting aspects of Python is its solid
-support for modular programming and the culture of cooperation in the
-Python community. There are already many Python-related scientific
-computing projects underway. If these efforts were coordinated
-in some manner, we feel that the results could be spectacular.
-
-<h2> Acknowledgments </h2>
-
-We would like acknowledge our collaborators Brad Holian, Tim Germann, Shujia Zhou, and Wanshu Huang at Los Alamos National Laboratory. We would also like
-to acknowledge Paul Dubois and Brian Yang at Lawrence Livermore
-National Laboratory for many interesting conversations concerning Python
-and its use in physics applications. We would also like to
-acknowledge the Scientific Computing and Imaging Group at the
-University of Utah for their continued support. Finally, we'd like to
-thank the entire Python development community for making a truly
-awesome tool for solving real problems. Development of the SPaSM code
-has been performed under the auspices of the United States Department
-of Energy.
-
-<h2> References </h2>
-
-<p>
-[1] D.M.Beazley and P.S. Lomdahl, "Message
-Passing Multi-Cell Molecular Dynamics on the Connection Machine 5,"
-Parallel Computing 20 (1994), p. 173-195. <p>
-
-<p>
-[2] P.S.Lomdahl, P.Tamayo, N.Gronbech-Jensen,
-and D.M.Beazley, "50 Gflops Molecular Dynamics on the CM-5," Proceedings
-of Supercomputing 93, IEEE Computer Society (1993), p.520-527. <p>
-
-<p>
-[3] S.J.Zhou, D.M. Beazley, P.S. Lomdahl, B.L. Holian, Physical Review
-Letters. 78, 479 (1997).
-
-<p>
-[4] P. Dubois, K. Hinsen, and J. Hugunin, Computers in Physics (10), (1996)
-p. 262-267.
-
-<p>
-[5] D. M. Beazley and P.S. Lomdahl, "Extensible Message Passing Application
-Development and Debugging with Python", Proceedings of IPPS'97, Geneva
-Switzerland, IEEE Computer Society (1997).
-
-<p>
-[6] T.-Y.B. Yang, D.M. Beazley, P. F. Dubois, G. Furnish, "Steering Object-oriented Computations with
-Python", Python Workshop 5, Washington D.C., Nov. 4-5, 1996.
-
-<p>
-[7] D.M. Beazley and P.S. Lomdahl, "High
-Performance Molecular Dynamics Modeling with SPaSM : Performance and
-Portability Issues," Proceedings of the Workshop on Debugging and
-Tuning for Parallel Computer Systems, Chatham, MA, 1994 (IEEE Computer
-Society Press, Los Alamitos, CA, 1996), pp. 337-351.
-
-<p>
-[8] D.M. Beazley, "Using SWIG to Control, Prototype, and Debug C Programs with Python",
-Proceedings of the 4th International Python Conference, Lawrence Livermore
-National Laboratory, June 3-6, 1996.
-
-<p>
-[9] K. Hinsen, The Molecular Modeling Toolkit, <tt>http://starship.skyport.net/crew/hinsen/mmtk.html</tt>
-
-<p>
-[10] Jim Hugunin, Numeric Python, <tt>http://www.sls.lcs.mit.edu/jjh/numpy</tt>
-
-<p>
-[11] Fredrik Lundh, Python Imaging Library, <tt>http://www.python.org/sigs/image-sig/Imaging.html</tt>
-</body>
-</html>
diff --git a/swigweb/papers/Py97/bigshock.gif b/swigweb/papers/Py97/bigshock.gif
deleted file mode 100755
index a80de44..0000000
--- a/swigweb/papers/Py97/bigshock.gif
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Py97/bigshockraw.gif b/swigweb/papers/Py97/bigshockraw.gif
deleted file mode 100755
index e2bfb99..0000000
--- a/swigweb/papers/Py97/bigshockraw.gif
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/PyTutorial97/PyTutorial97.pdf b/swigweb/papers/PyTutorial97/PyTutorial97.pdf
deleted file mode 100644
index e6ac402..0000000
--- a/swigweb/papers/PyTutorial97/PyTutorial97.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/PyTutorial98/PyTutorial98.pdf b/swigweb/papers/PyTutorial98/PyTutorial98.pdf
deleted file mode 100644
index 70fa305..0000000
--- a/swigweb/papers/PyTutorial98/PyTutorial98.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Tcl96/.~newtcl.html b/swigweb/papers/Tcl96/.~newtcl.html
deleted file mode 100755
index af26551..0000000
--- a/swigweb/papers/Tcl96/.~newtcl.html
+++ /dev/null
@@ -1,1084 +0,0 @@
-<html>
-<title> SWIG : An Easy to Use Tool For Integrating Scriptint Languages
-with C and C++ </title>
-<body bgcolor="#ffffff">
-<h1>
-SWIG : An Easy to Use Tool for Integrating Scripting Languages with C and C++
-</h1>
-
-<b> David M. Beazley </b> <br>
-<em> Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 <br>
-beazley@cs.utah.edu <br> </em>
-
-<br> <br>
-(To be presented at the 4th Annual Tcl/Tk Workshop, Monterey, CA. July 6-10, 1996. )
-
-<h2> Abstract </h2>
-
-<em>
-I present SWIG (Simplified Wrapper and Interface Generator), a
-program development tool that automatically generates the bindings
-between C/C++ code and common scripting languages including
-Tcl, Python, Perl and Guile. SWIG supports most C/C++ datatypes
-including pointers, structures, and classes.
-Unlike many other approaches, SWIG
-uses ANSI C/C++ declarations and requires the user to make virtually
-no modifications to the underlying C code.
-In addition, SWIG automatically
-produces documentation in HTML, LaTeX, or ASCII format.
-SWIG has been primarily designed for scientists, engineers, and application
-developers who would like to use scripting languages with their C/C++ programs
-without worrying about the underlying implementation details
-of each language or using a complicated software development tool.
-This paper concentrates on SWIG's use with Tcl/Tk.
-</em>
-
-<h2> 1. Introduction </h2>
-SWIG (Simplified Wrapper and Interface Generator)
-is a software
-development tool that I never intended to develop. At the time,
-I was trying to add a data analysis and visualization capability to
-a molecular dynamics (MD) code I had helped develop for massively
-parallel supercomputers at Los Alamos National Laboratory [Beazley,Lomdahl]. I wanted
-to provide a simple, yet flexible user interface that could be used
-to glue various code modules together and an extensible scripting
-language seemed like an ideal solution. Unfortunately there were constraints.
-First, I didn't want to hack up 4-years of code development trying to
-fit our MD code into yet another interface scheme (having done so several
-times already). Secondly, this code
-was routinely run on systems ranging from Connection Machines and Crays to
-workstations and I didn't want to depend on any one
-interface language---out of fear that it might not be supported on
-all of these platforms. Finally, the users were constantly adding
-new code and making modifications. I needed a flexible, yet easy to use
-system that did not get in the way of the physicists. <br> <br>
-
-SWIG is my solution to this problem. Simply stated, SWIG automatically generates all
-of the code
-needed to bind C/C++ functions with scripting languages using only
-a simple input file containing C function and variable declarations.
-At first, I supported
-a scripting language I had developed specifically for use
-on massively parallel systems. Later I decided to rewrite SWIG in C++ and extend it to support
-Tcl, Python, Perl, Guile and other languages that interested me. I also
-added more data-types, support for pointers, C++ classes, documentation generation, and
-a few other features. <br> <br>
-
-This paper provides a brief overview of SWIG
-with a particular emphasis on Tcl/Tk. However, the reader should
-remain aware that SWIG works equally well with
-Perl and other languages. It is not my intent to provide
-a tutorial or a user's guide, but rather to show
-how SWIG can be used to do interesting things such as
-adding Tcl/Tk interfaces to existing C applications,
-quickly debugging and prototyping C code,
-and building interface-language-independent C applications.
-
-<h2> 2. Tcl and Wrapper Functions </h2>
-
-In order to add a new C or C++ function to Tcl, it is necessary to
-write a special ``wrapper'' function that parses the function arguments
-presented as ASCII strings by the Tcl interpreter into a representation
-that can be used to call the C function. For example, if you wanted
-to add the factorial function to Tcl, a wrapper function might
-look like the following : <br>
-
-<blockquote>
-<tt> <pre>
-int wrap_fact(ClientData clientData,
- Tcl_Interp *interp,
- int argc, char *argv[]) {
- int result;
- int arg0;
- if (argc != 2) {
- interp->result = "wrong # args";
- return TCL_ERROR;
- }
- arg0 = atoi(argv[1]);
- result = fact(arg0);
- sprintf(interp->result,"%d",result);
- return TCL_OK;
-}
-</pre>
-</tt>
-</blockquote>
-
-In addition to writing the wrapper function, a user will also need to
-write code to add this function to the Tcl interpreter. In the case of
-Tcl 7.5, this could be done by writing an initialization function to
-be called when the extension is loaded dynamically. While writing
-a wrapper function usually is not too difficult, the process quickly
-becomes tedious and error prone as the number of functions increases.
-Therefore, automated approaches for producing wrapper functions are
-appealing--especially when working with a large number of C functions
-or with C++ (in which case the wrapper code tends to get more complicated).
-
-<h2> 3. Prior Work </h2>
-
-The idea of automatically generating wrapper code is certainly not new.
-Some efforts such as
-Itcl++, Object Tcl, or the XS language included with Perl5, provide a mechanism for
-generating wrapper code, but require the user to provide detailed
-specifications, type conversion rules, or use a specialized
-syntax [heidrich,Wetherall,perl5]. Large packages
-such as the Visualization Toolkit (vtk) may use their own C/C++ translators,
-but these almost always tend to be somewhat special purpose (in fact, SWIG started
-out in this manner) [vtk].
-If supporting multiple languages is the ultimate goal, a programmer might
-consider a package such as ILU [Janssen].
-Unfortunately,
-this requires the user to provide specifications in IDL--a process which
-is unappealing to many users.
-SWIG is not necessarily intended to compete with
-these approaches, but rather is designed to be a no-nonsense tool that
-scientists and engineers can use to easily add Tcl and other scripting
-languages to their own applications. SWIG is also
-very different than Embedded Tk (ET) which also aims to
-simplify code development [ET]. Unlike ET, SWIG is designed to
-integrate C functions into Tcl/Tk as opposed to integrating Tcl/Tk into
-C programs.
-
-<h2> 4. A Quick Tour of SWIG </h2>
-
-<h3> 4.1 Organization </h3>
-
-<center>
-<img alt = "SWIG Organization" src="fig1.gif"> <br>
-Figure 1 : SWIG Organization <br> <br>
-</center>
-
-Figure 1 shows the structure of SWIG. At the core is a YACC parser
-for reading input files along with some utility functions.
-To generate code,
-the parser calls about a dozen functions from a generic language
-class to do things like write a wrapper function, link a
-variable, wrap a C++ member function, etc... Each target language is
-implemented as a C++ class containing the functions that emit
-the resulting C code. If an ``empty'' language definition is given
-to SWIG, it will produce no output. Thus, each language class can
-be implemented in almost any manner.
-The documentation system is implemented in a similar manner and can
-currently produce ASCII, LaTeX, or HTML output. As output,
-SWIG produces a C file that should be compiled and linked with the rest
-of the code and a documentation file that can be used for later reference.
-
-<h3> 4.2. Interface Files </h3>
-
-As input, SWIG takes a single input file referred to as an ``interface file.''
-This file contains a few SWIG specific directives, but otherwise contains
-ANSI C function and variable declarations. Unlike the approach in [Heidrich], no type conversion rules are needed and all declarations are made
-using familiar ANSI C/C++ prototypes. The following code shows an
-interface file for wrapping a few C file I/O and memory management functions.
-
-<blockquote>
-<tt> <pre>
-/* File : file.i */
-%module fileio
-%{
-#include <stdio.h>
-%}
-
-FILE *fopen(char *filename, char *type);
-int fclose(FILE *stream);
-typedef unsigned int size_t
-size_t fread(void *ptr, size_t size,
- size_t nobj, FILE *stream);
-size_t fwrite(void *ptr, size_t size,
- size_t nobj,FILE *stream);
-void *malloc(size_t nbytes);
-void free(void *);
-</pre> </tt> </blockquote>
-
-The <tt> %module </tt> directive
-sets the name of the initialization function. This is optional, but is
-recommended if building a Tcl 7.5 module.
-Everything inside the <tt> %{, %} </tt>
-block is copied directly into the output, allowing the inclusion of
-header files and additional C code.
-Afterwards, C/C++ function and variable declarations are listed in any
-order.
-Building a new Tcl module is usually as
-easy as the following :
-
-<blockquote>
-<tt> <pre>
-unix > swig -tcl file.i
-unix > gcc file_wrap.c -I/usr/local/include
-unix > ld -shared file_wrap.o -o Fileio.so
-</pre> </tt>
-</blockquote>
-
-
-<h3> 4.3. A Tcl Example </h3>
-
-Newly added functions work like ordinary Tcl procedures. For
-example, the following Tcl script copies a file using the binary
-file I/O functions added in the previous example :
-
-<blockquote>
-<tt> <pre>
-proc filecopy {name1 name2} {
- set buffer [malloc 8192];
- set f1 [fopen $name1 r];
- set f2 [fopen $name2 w];
- set nbytes [fread $buffer 1 8192 $f1];
- while {$nbytes > 0} {
- fwrite $buffer 1 $nbytes $f2;
- set nbytes [fread $buffer 1 8192 $f1];
- }
- fclose $f1;
- fclose $f2;
- free $buffer
-}
-</pre> </tt>
-</blockquote>
-
-<h3> 4.4. Datatypes and Pointers </h3>
-
-SWIG supports the basic datatypes of <tt> int, short,
-long, float, double, char, </tt> and <tt> void </tt>
-as well as signed and unsigned integers. SWIG
-also allows derived types such as pointers, structures, and classes,
-but these are all encoded as pointers.
-If an unknown type is encountered, SWIG assumes
-that it is a complex datatype that has been defined earlier.
-No attempt is made to figure out what data that datatype actually contains
-or how it should be used. Of course, this this is only possible
-since SWIG's mapping of complex types into pointers allows them
-to be handled in a uniform manner.
-As a result, SWIG does not normally need any sort
-of type-mapping, but <tt> typedef </tt> can be used to map any of the built-in
-datatypes to new types if desired. <br> <br>
-
-SWIG encodes pointers as hexadecimal strings with type-information. This
-type information is used to provide a run-time type checking mechanism.
-Thus, a typical SWIG pointer looks something like the following : <br> <br>
-
-<center>
-<tt> _1008e614_Vector_p </tt> <br> <br>
-</center>
-
-If this pointer is passed into a function requiring some other kind of
-pointer, SWIG will generate a Tcl error and return an error message.
-The NULL pointer is represented by the string "NULL". The SWIG run-time
-type checker is saavy to typedefs and the relationship between base classes
-and derived classes in C++. Thus if a
-user specifies <br> <br>
-
-<center>
-<tt> typedef double Real; </tt> <br> <br>
-</center>
-
-the type checker knows that <tt> Real * </tt> and <tt> double * </tt>
-are equivalent (more on C++ in a minute).
-From the point of view of other Tcl extensions,
-SWIG pointers should be seen as special "handles" except that they
-happen to contain the pointer value and its type. <br> <br>
-
-To some, this approach may seem horribly restrictive (or error prone),
-but keep in mind that SWIG was primarily designed to work with
-existing C applications. Since most C programs pass complex datatypes
-around by reference this technique works remarkably well in practice.
-Run time type-checking also eliminates most common crashes by catching
-stupid mistakes such as using a wrong variable name or forgetting the
-"$" character in a Tcl script. While it is still possible to crash Tcl by forging a
-SWIG pointer value (or making a call to buggy C code), it is worth
-emphasizing that existing Tcl extensions
-may also crash if given an invalid handle.
-
-<h3> 4.5. Global Variables and Constants </h3>
-
-SWIG can install global C variables and constants using Tcl's variable linkage
-mechanism.
-Variables may also be declared as ``read only''
-within the Tcl interpreter. The following example shows
-how variables and constants can be added to Tcl :
-
-<blockquote>
-<tt> <pre>
-// SWIG file with variables and constants
-%{
-%}
-
-// Some global variables
-extern int My_variable;
-extern char *default_path;
-extern double My_double;
-
-// Some constants
-#define PI 3.14159265359
-#define PI_4 PI/4.0
-enum colors {red,blue,green};
-const int SIZEOF_VECTOR = sizeof(Vector);
-
-// A read only variable
-%readonly
-extern int Status;
-%readwrite
-
-</pre>
-</tt>
-</blockquote>
-
-<h3> 4.6. C++ Support </h3>
-
-The SWIG parser can handle simple C++ class definitions and supports public
-inheritance, virtual functions, static functions, constructors and
-destructors. Currently, C++ translation is performed
-by politely tranforming C++ code into C code and generating wrappers for the
-C functions. For example, consider the following SWIG interface file
-containing a C++ class definition:
-
-<blockquote>
-<tt> <pre>
-%module tree
-%{
-#include "tree.h"
-%}
-
-class Tree {
-public:
- Tree();
- ~Tree();
- void insert(char *item);
- int search(char *item);
- int remove(char *item);
-static void print(Tree *t);
-};
-</pre>
-</tt>
-</blockquote>
-
-When translated, the class will be access used the following set of
-functions (created automatically by SWIG).
-
-<blockquote>
-<tt>
-<pre>
-Tree *new_Tree();
-void delete_Tree(Tree *this);
-void Tree_insert(Tree *this, char *item);
-int Tree_search(Tree *this, char *item);
-int Tree_remove(Tree *this, char *item);
-void Tree_print(Tree *t);
-</pre>
-</tt>
-</blockquote>
-
-
-All C++ functions wrapped by SWIG explicitly require the <tt> this </tt> pointer
-as shown. This approach has the advantage of working for all of the target
-languages. It also makes it easier to pass objects between
-other C++ functions since every C++ object is simply represented as a SWIG pointer. SWIG does not support function overloading, but overloaded functions
-can be resolved by renaming them with the SWIG <tt> %name </tt> directive as follows:
-
-<blockquote>
-<tt> <pre>
-class List {
-public:
- List();
-%name(ListMax) List(int maxsize);
-...
-};
-</pre> </tt> </blockquote>
-
-The approach used by SWIG is
-quite different than that used in systems such as
-Object Tcl or vtk [vtk,Wetherall]. As a result, users of those systems
-may find it to be confusing. However,
-It is important to note that the modular design of
-SWIG allows the user to completely redefine the output behavior of
-the system. Thus, while the current C++ implementation is quite different
-than other systems supporting C++, it would be entirely possible
-write a new SWIG module that wrapped C++ classes into a representation
-similar to that used by Object Tcl (in fact, in might even be possible
-to use SWIG to produce the input files used for Object Tcl).
-
-<h3> 4.7. Multiple Files and Code Reuse </h3>
-
-An essential feature of SWIG is its support for multiple files
-and modules. A SWIG interface file may include another interface
-file using the "<tt> %include </tt>" directive. Thus, an interface
-for a large system might be broken up into a collection of smaller
-modules as shown
-
-<blockquote>
-<tt> <pre>
-%module package
-%{
-#include "package.h"
-%}
-
-%include geometry.i
-%include memory.i
-%include network.i
-%include graphics.i
-%include physics.i
-
-%include wish.i
-</pre> </tt> </blockquote>
-
-Common operations can be placed into a SWIG library for use in
-all applications. For example, the <tt> %include wish.i </tt> directive
-tells SWIG to include code for the <tt> Tcl_AppInit() </tt> function
-needed to rebuild the <tt> wish </tt> program. The library can also be
-used to build modules
-allowing SWIG to be used with common Tcl extensions such
-as Expect [Expect]. Of course, the primary use of the library is with
-large applications such as Open-Inventor which contain hundreds of
-modules and a substantial class hierarchy [Invent]. In this case a user
-could use SWIG's include mechanism to selectively pick which modules
-they wanted to use for a particular problem.
-
-<h3> 4.8. The Documentation System </h3>
-
-SWIG produces documentation in ASCII, LaTeX, or HTML
-format describing everything that was wrapped. The documentation
-follows the syntax rules of the target language and can
-can be further enhanced by adding descriptions in a C/C++ comment
-immediately following a declaration. These comments may also contain
-embedded LaTeX or HTML commands. For example:
-
-<blockquote>
-<tt> <pre>
-extern size_t fread(void *ptr, size_t size,
- size_t nobj, FILE *stream);
-/* {\tt fread} reads from {\tt stream} into
-the array {\tt ptr} at most {\tt nobj} objects
-of size {\tt size}. {\tt fread} returns
-the number of objects read. */
-</pre> </tt> </blockquote>
-
-When output by SWIG and processed by LaTeX, this appears as follows :
-
-<ul>
-<tt> size_t : fread ptr size nobj stream </tt> <br>
-<ul>
- <tt> fread </tt> reads from <tt> stream </tt> into the array <tt> ptr </tt> at
- most <tt> nobj </tt> objects of size <tt> size </tt>. <tt> fread </tt>
- returns
- the number of objects read.
-</ul>
-</ul>
-
-<h3> 4.9. Extending the SWIG System </h3>
-
-Finally, SWIG itself can be extended by the user to provide new
-functionality. This is done by modifying an existing or creating a
-new language class. A typical class must specify the following
-functions that determine the behavior of the parser output :
-
-<blockquote>
-<tt> <pre>
-// File : swigtcl.h
-class TCL : public Language {
-private:
- // Put private stuff here
-public :
- TCL();
- int main(int, char *argv[]);
- void create_function(char *,char *,DataType*,
- ParmList *);
- void link_variable(char *,char *,DataType *);
- void declare_const(char *,int,char *);
- void initialize(void);
- void headers(void);
- void close(void);
- void usage_var(char *,DataType*,char **);
- void usage_func(char *,DataType*,ParmList*,
- char **);
- void usage_const(char *,int,char*,char**);
- void set_module(char *);
- void set_init(char *);
-};
-</pre> </tt> </blockquote>
-
-Descriptions of these functions can be found in the SWIG
-users manual. To build a new version of SWIG, the user
-only needs to provide the function definitions and a main
-program which looks something like the following :
-
-<blockquote>
-<tt> <pre>
-
-// SWIG main program
-
-#include "swig.h"
-#include "swigtcl.h"
-
-int main(int argc, char **argv) {
-
- Language *lang;
-
- lang = new TCL;
- SWIG_main(argc,argv,lang,(Documentation *) 0);
-
-}
-</pre> </tt> </blockquote>
-
-When linked with a library file, any extensions and
-modifications can now be used with the SWIG parser. While
-writing a new language definition is not entirely trivial,
-it can usually be done by just copying one of the existing
-modules and modifying it appropriately.
-
-<h2> 5. Examples </h2>
-
-<h3> 5.1. A C-Tcl Linked List </h3>
-
-SWIG can be used to build simple data structures that are usuable in
-both C and Tcl. The following code shows a SWIG interface file for
-building a simple linked list.
-
-<blockquote>
-<tt> <pre>
-/* File : list.i */
-%{
-struct Node {
- Node(char *n) {
- name = new char[strlen(n)+1];
- strcpy(name,n);
- next = 0;
- };
- char *name;
- Node *next;
-};
-%}
-
-// Just add struct definition to
-// the interface file.
-
-struct Node {
- Node(char *);
- char *name;
- Node *next;
-};
-
-</pre> </tt> </blockquote>
-
-When used in a Tcl script, we can now create new nodes and access
-individual members of the <tt> Node </tt> structure. In fact, we can
-write code to convert between Tcl lists and linked lists entirely
-in Tcl as shown :
-
-<blockquote>
-<tt> <pre>
-# Builds linked list from a Tcl list
-proc buildlist {list head} {
- set nitems [llength $list];
- for {set i 0} {$i < $nitems} {incr i -1} {
- set item [lrange $list $i $i]
- set n [new_Node $item]
- Node_set_next $n $head
- set head $n
- }
- return $head
-}
-# Builds a Tcl list from a linked list
-proc get_list {llist} {
- set list {}
- while {$llist != "NULL"} {
- lappend list [Node_name_get $llist]
- set llist [Node_get_next $llist]
- }
- return $list
-}
-</pre> </tt> </blockquote>
-
-When run interactively, we could now use our Tcl functions as
-follows.
-
-<blockquote>
-<tt> <pre>
-% set l {John Anne Mary Jim}
-John Anne Mary Jim
-% set ll [buildlist $l _0_Node_p]
-_1000cab8_Node_p
-% get_list $ll
-Jim Mary Anne John
-% set ll [buildlist {Mike Peter Dave} $ll]
-_1000cc38_Node_p
-% get_list $ll
-Dave Peter Mike Jim Mary Anne John
-%
-</pre> </tt> </blockquote>
-Aside from the pointer values, our script acts like any other
-Tcl script. However, we have built up a real
-C data structure that could be easily passed to other C functions
-if needed.
-
-<h3> 5.2. Using C Data-Structures with Tk </h3>
-
-In manner similar to the linked list example, Tcl/Tk can be used
-to build complex C/C++ data structures. For example, suppose we
-wanted to interactively build a graph of ``Nodes'' for use in a C
-application.
-A typical interface file might include the following functions:
-
-<blockquote> <tt> <pre>
-%{
-#include "nodes.h"
-%}
-
-%include wish
-extern Node *new_node();
-extern void AddEdge(Node *n1, Node *n2);
-</pre> </tt> </blockquote>
-
-Within a Tcl/Tk script, loosely based on one to make ball and stick graphs
-in [Ousterhout], a graph could be built as follows:
-
-<blockquote> <tt> <pre>
-proc makeNode {x y} {
- global nodeX nodeY nodeP edgeFirst edgeSecond
- set new [.create oval [expr $x-15] \
- [expr $y-15] [expr $x+15] \
- [expr $y+15] -outline black \
- -fill white -tags node]
- set newnode [new_node]
- set nodeX($new) $x
- set nodeY($new) $y
- set nodeP($new) $newnode
- set edgeFirst($new) {}
- set edgeSecond($new) {}
-}
-proc makeEdge {first second} {
- global nodeX nodeY nodeP edgeFirst edgeSecond
- set x1 $nodeX($first); set y1 $nodeY($first)
- set x2 $nodeX($second); set y2 $nodeY($second)
- set edge [.c create line $x1 $y1 $x2 $y2 \
- -tags edge}
- .c lower edge
- lappend edgeFirst($first) $edge
- lappend edgeSecond($first) $edge
- AddEdge $nodeP($first) $nodeP($second)
-}
-</pre> </tt> </blockquote>
-
-These functions create
-Tk canvas items, but also attach a pointer to a C data structure to each one.
-This is done by maintaining an associative array mapping
-item identifiers to pointers (with the <tt> nodeP() </tt> array).
-When a
-particular ``node'' is referenced later, we can use this to
-get its pointer use it in calls to C functions.
-
-<h3> 5.3. Parsing a C++ Simple Class Hierarchy </h3>
-
-As mentioned earlier, SWIG can handle C++ classes and public
-inheritance. The following example provides a few classes
-and illustrates how this is accomplished (some code has been
-ommitted for readability).
-
-<blockquote> <tt> <pre>
-// A SWIG inheritance example
-%module shapes
-%{
-#include "shapes.h"
-%}
-
-class Shape {
-private:
- double xc, yc;
-public:
- virtual double area() = 0;
- virtual double perimeter() = 0;
- void set_position(double x, double y);
- void print_position();
-};
-
-class Circle: public Shape {
- private:
- double radius;
- public:
- Circle(double r);
- double area();
- double perimeter();
-};
-
-class Square : public Shape {
-private:
- double width;
-public:
- Square(double w);
- double area();
- double perimeter();
-};
-
-</pre> </tt> </blockquote>
-
-Now, when wrapped by SWIG (note :
-When parsing C++ classes, SWIG throws away everything declared as private,
-inline code, and alot of the other clutter found in C++ header files.
-Primarily this is provided only to make it easier to build interfaces from
-existing C++ header files.), we can use our class structure as follows:
-
-<blockquote> <tt> <pre>
-% set c [new_Circle 4]
-_1000ad70_Circle_p
-% set s [new_Square 10]
-_1000adc0_Square_p
-% Shape_area $c
-50.26548246400000200
-% Shape_area $s
-100.00000000000000000
-% Shape_set_position $c -5 10
-% Circle_print_position $c
-xc = -5, yc = 10
-%
-</pre> </tt> </blockquote>
-
-In our example, we have created new <tt> Circle </tt> and <tt> Square </tt> objects,
-but these can be used interchangably in any functions defined in the <tt> Shape </tt>
-base class. The SWIG type checker is encoded with the class hierarchy and
-knows the relationship between the different classes. Thus, while an
-object of type <tt> Circle </tt> is perfectly acceptable to a function operating
-on shapes, it would be unacceptable to a function operating only on the
-<tt> Square </tt> type. As in C++, any functions in the base class can be
-called in the derived class as shown by the <tt> Circle_print_position </tt>
-function above.
-
-<h2> 6. Using SWIG in Real Applications </h2>
-
-So far only a few simple toy examples have been presented to illustrate
-the operation of SWIG in general.
-This section will describe how SWIG can be used
-with larger applications.
-
-<h3> 6.1. Use in Scientific Applications </h3>
-
-Many users, especially within the scientific and engineering
-community, have spent years developing simulation codes.
-While many of these users appreciate the
-power that a scripting language can provide, they don't want to
-completely rewrite their applications or spend all of their time
-trying to build a user-interface (most users would rather be working
-on the scientific problem at hand). While SWIG certainly won't do everything,
-it can dramatically simplify this process. <br> <br>
-
-As an example, the first SWIG application was the SPaSM molecular
-dynamics code developed at Los Alamos National Laboratory
-[Beazley,Lomdahl]. This code is currently being used for materials
-science problems and consists of more than 200 C functions and about 20000 lines
-of code.
-In order to use SWIG, only the <tt> main() </tt> function had to be
-rewritten along with a few other minor modifications.
-The full user interface is built using a collection of modules for
-simulation, graphics, memory management, etc...
-A user may also supply their own interface modules--allowing the code to
-be easily extended with new functionality capabilities as needed.
-All of the interface files, containing a few hundred lines of
-function declarations, are automatically translated into more than
-2000 lines of wrapper code at compile time. As a result, many users
-of the system know how to extend it, but are unaware of the actual
-wrapping procedure. <br> <br>
-
-After modifying the SPaSM code to use SWIG, most of the C code remained
-unchanged. In fact, in subsequent work, we were able to eliminate
-more than 25% of the source code--almost all of which was related to the
-now obsolete interface method that we replaced. More importantly, we
-were able to turn a code that was difficult to use and modify into a
-flexible package that was easy to use and extend. This has had a
-huge impact, which can not be understated, on the use of the SPaSM
-code to solve real problems.
-
-<h3> 6.2. Open-GL and Inventor </h3>
-
-While SWIG was primarily designed to work with application codes, it
-can also be used to wrap large libraries. At the University of Utah,
-Peter-Pike Sloan used SWIG to wrap the entire contents of the Open-GL
-library into Tcl for use with an Open-GL Tk widget. The process of
-wrapping Open-GL with SWIG was as simple as the following :
-
-<ul>
-<li> Make a copy of the <tt> gl.h </tt> header file.
-<li> Clean it up by taking a few C preprocessor directives out
- of it. Fix a few typedefs.
-<li> Insert the following code into the beginning
-<blockquote> <tt> <pre>
-%module opengl
-%{
-#include <GL/gl.h>
-%}
-... Copy edited gl.h here ...
-</pre> </tt> </blockquote>
-
-<li> Modify the Open-GL widget to call <tt> Opengl_Init </tt>.
-<li> Recompile
-</ul>
-
-The entire process required only about 10 minutes of work, but resulted
-in more than 500 constants and 360 functions being added to Tcl. Furthermore,
-this extension allows Open-GL commands to be issued directly from Tcl's
-interpreted environment as shown in this example
-(from the Open-GL manual [OpenGL]).
-
-<blockquote> <tt> <pre>
-% ... open GL widget here ...
-% glClearColor 0.0 0.0 0.0 0.0
-% glClear $GL_COLOR_BUFFER_BIT
-% glColor3f 1.0 1.0 1.0
-% glOrtho -1.0 1.0 -1.0 1.0 -1.0 1.0
-% glBegin $GL_POLYGON
-% glVertex2f -0.5 -0.5
-% glVertex2f -0.5 0.5
-% glVertex2f 0.5 0.5
-% glVertex2f 0.5 -0.5
-% glEnd
-% glFlush
-</pre> </tt> </blockquote>
-
-Early work has also been performed on using SWIG to wrap portions
-of the Open-Inventor package [Invent]. This is a more ambitious project
-since Open-Inventor consists of a very large collection of header
-files and C++ classes. However, the SWIG library mechanism can be
-used effective in this case. For each Inventor header, we can create
-a sanitized SWIG interface file (removing alot of the clutter found in
-the header files). These interface files can then be organized to mirror the
-structure of the Inventor system. To build a module for Tcl, a user
-could simply specify which modules they wanted to use as follows :
-
-<blockquote> <tt> <pre>
-%module invent
-%{
-... put headers here ...
-%}
-
-%include "Inventor/Xt/SoXt.i"
-%include "Inventor/Xt/SoXtRenderArea.i"
-%include "Inventor/nodes/SoCone.i"
-%include "Inventor/nodes/SoDirectionalLight.i"
-%include "Inventor/nodes/SoMaterial.i"
-%include "Inventor/nodes/SoPerspectiveCamera.i"
-%include "Inventor/nodes/SoSeparator.i"
-</pre> </tt> </blockquote>
-
-While wrapping the Inventor library will require significantly
-more work than Open-GL, SWIG can be used effectively with such
-systems.
-
-<h3> 6.3. Building Interesting Applications by Cut and Paste </h3>
-
-SWIG can be used to construct tools out of dissimiliar
-packages and libraries.
-In contrast to combining packages at an input level as one might
-do with with Expect, SWIG can be used to build applications at a
-function level [Expect].
-For example, using
-a simple interface file, you can wrap the
-C API of MATLAB 4.2 [MATLAB].
-This in turn lets you build a Tcl/Tk interface for controlling
-MATLAB programs. Separately, you could wrap a numerical simulation
-code. Now, a few translation functions could be written and both
-packages combined into a single Tcl/Tk application. You have
-now built a simple ``computational steering'' system that allows you
-to run a simulation code, visualize data in MATLAB, and control the
-entire system with a Tcl/Tk based interface. Figure 2 shows
-a screen snapshot from such a simulation in which the SPaSM molecular
-dynamics code, a visualization module library, image server (using xv),
-and MATLAB have been
-combined. Under this system, the user can interactively set up
-and run simulations while watching the results evolve in real-time.
-<br> <br>
-<center>
-<img alt = "Tcl/Tk/MATLAB/SPASM Figure" src="steer2.gif"> <br>
-Figure 2: Simple Tcl/Tk Steering Application Built with SWIG <br>
-</center>
-
-<h3> 6.4. Language Independent Applications </h3>
-
-
-Each scripting language has it's own strengths and weaknesses.
-Rather
-than trying to choose the language that is the best at everything (which
-is probably impossible),
-SWIG allows a user to use the best language for the job at hand. I'm
-always finding myself writing little utilities and programs to support
-my scientific computing work. Why should I be forced to use only one
-language for everything? With SWIG, I can put a Perl interface on a
-tool and switch over to Tcl/Tk at anytime by just changing a few
-Makefile options. <br> <br>
-
-Since SWIG provides a language-independent interface specification,
-it is relatively easy to use SWIG generated modules in a variety of
-interesting applications. For example, the identical MATLAB
-module used in the last Tcl example could be imported as Perl5 module
-and combined with a Perl script to produce graphical displays from
-Web-server logs as shown in Figure 3. <br> <br>
-
-<center>
-<img alt="Perl5 web stats example" src="hits.gif"> <br>
-Figure 3:Web-server activity graph. Generated from a Perl script, but
-uses an unmodified SWIG generated module for integrating MATLAB with Tcl/Tk. <br> <br>
-</center>
-
-Some have promoted the idea of encapsulating several languages into
-a higher level language as has been proposed with Guile [Lord].
-This may be fine if one wants to write code that uses different languages
-all at once, but when I want to use only Tcl or Perl for an application,
-I almost always prefer using the real versions instead of an encapsulated
-variant. SWIG makes this possible without much effort.
-
-<h3> 6.5. Using Tcl as a debugger </h3>
-
-Since SWIG can work with existing C code, it can be used quite effectively
-as a debugger.
-You can wrap C functions and interact
-with them from <tt> tclsh </tt> or <tt> wish </tt>.
-Unlike most traditional debuggers, you
-can create objects, buffers, arrays, and other things on the fly
-by putting appropriate definitions in the interface file.
-Since <tt> tclsh </tt> or <tt> wish </tt> provides a <tt> main() </tt> function, you
-can even rip small pieces out of a larger package without including
-that package's main program.
-Scripts can be written to test out different parts of your
-code as it is developed. When you are satisfied with the module,
-removing the interface is as easy as discarding the SWIG interface
-file. I have used SWIG as a debugger for developing graphics libraries,
-network servers, simulation codes, and a wide range of other projects--some
-of which didn't even use a scripting language when completed.
-
-<h2> 7. Limitations </h2>
-
-SWIG represents a balance of flexibility and ease of use.
-I have always felt that the tool shouldn't be more complicated than
-the original problem. Therefore, SWIG certainly won't do everything.
-While I believe the pointer representation of complex datatypes works
-well in practice, some users have found this to be too general or
-confusing. SWIG's
-support for C++ is also limited by the fact that SWIG does not support
-operator overloading, multiple inheritance, templates, and a number
-of other more advanced C++ features. SWIG also lacks support for
-default or variable length function arguments, array notation,
-pointers to functions (unless hidden by a typedef) and an exception
-mechanism.
-Finally, SWIG
-does
-not support all of the features of Tcl such as associative arrays.
-These aren't an inherent part of the C language so it is difficult
-to generalize how they should be handled or generated. I prefer to
-keep the tool simple while leaving these issues up to the individual
-programmer. <br> <br>
-
-
-Fortunately, it is almost always possible to work around
-many problems by writing special library functions or making
-modifications to the SWIG language modules to produce the desired effect.
-For example, when wrapping Open-GL, SWIG installed all of the Open-GL
-constants as Tcl global variables. Unfortunately, none of these
-variables were accessible inside Tcl procedures unless they were explicitly
-declared global. By making a modification to the Tcl language module,
-it was possible to put the GL constants into hash table and perform
-a hidden ``lookup'' inside all of the GL-related functions. Similarly,
-much of the functionality of SWIG can be placed into library
-files for use in other modules.
-
-<h2> 8. Conclusions </h2>
-
-SWIG has been in use for approximately one year. At Los Alamos National Laboratory, its use with the SPaSM code has
-proven to
-be a remarkably simple, stable, and bug-free way to build and modify user
-interfaces. At the University of Utah, SWIG is being used in a variety
-of other applications where the users have quickly come to appreciate its
-ease of use and flexibility. <br> <br>
-
-While SWIG may be inappropriate for certain applications, I feel that it
-opens up Tcl/Tk, Python, Perl, Guile, and other languages to
-users who would like to develop interesting user interfaces for their codes,
-but who don't want to worry about the low-level details or figuring
-out how to use a complicated tool. <br> <br>
-
-Future directions for SWIG include support for other scripting languages,
-and a library of extensions. SWIG may also be extended to support packages
-such as incremental Tcl. Work is also underway to port SWIG to non-unix
-platforms.
-
-<h2> Acknowledgments </h2>
-
-This project would not have been possible without the support of a number
-of people. Peter Lomdahl, Shujia Zhou, Brad Holian, Tim Germann, and Niels
-Jensen at Los Alamos National Laboratory were the first users and were
-instrumental in testing out the first designs. Patrick Tullmann at
-the University of Utah suggested the idea of automatic documentation
-generation. John Schmidt, Kurtis
-Bleeker, Peter-Pike Sloan, and Steve Parker at the University of Utah tested out some of the newer versions and
-provided valuable feedback. John Buckman suggested many interesting
-improvements and has been instrumental the recent development of SWIG.
-Finally
-I'd like to thank Chris Johnson and the members of the Scientific
-Computing and Imaging group at the University of Utah for their continued
-support and for putting up with my wrapping every software package
-I could get my hands on. SWIG was developed in part under the
-auspices of the US Department of Energy, the National Science Foundation,
-and National Institutes of Health.
-
-<h2> Availability </h2>
-
-SWIG is free software and available via anonymous FTP at <br> <br>
-
-<center>
-<tt> ftp.cs.utah.edu/pub/beazley/SWIG </tt> <br> <br>
-</center>
-
-More information is also available on the SWIG homepage at <br> <br>
-
-<center>
-<a href="http://www.cs.utah.edu/~beazley/SWIG"> <tt> http://www.cs.utah.edu/~beazley/SWIG </tt> </a>
-</center> <br> <br>
-
-<h2> References </h2>
-
-[Beazley] D.M. Beazley and P.S. Lomdahl,
-<em> Message-Passing Multi-Cell Molecular Dynamics on the Connection
-Machine 5 </em>, Parallel Computing 20 (1994) p. 173-195. <br> <br>
-
-[ET] Embedded Tk, <br>
-<tt> ftp://ftp.vnet.net/pub/users/drh/ET.html </tt> <br> <br>
-
-[Expect] Don Libes, <em> Exploring Expect </em>, O'Reilly & Associates, Inc. (1995). <br> <br>
-
-[Heidrich] Wolfgang Heidrich and Philipp Slusallek, <em>
-Automatic Generation of Tcl Bindings for C and C++ Libraries.</em>,
-USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[Janssen] Bill Janssen, Mike Spreitzer, <em> ILU : Inter-Language Unification via Object Modules </em>, OOPSLA 94 Workshop on Multi-Language
-Object Models. <br> <br>
-
-[Lomdahl] P.S. Lomdahl, P. Tamayo,
-N.Gronbech-Jensen, and D.M. Beazley,
-<em> Proc. of Supercomputing 93 </em>, IEEE Computer Society (1993), p. 520-527.
-<br> <br>
-
-[Lord] Thomas Lord, <em> An Anatomy of Guile, The Interface to
-Tcl/Tk </em>, Proceedings of the USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[MATLAB] <em> MATLAB External Interface Guide </em>, The Math Works, Inc. (1993).
-<br> <br>
-
-[Ousterhout] John K. Ousterhout, <em> Tcl and the Tk Toolkit </em>, Addison-Wesley Publishers (1994). <br> <br>
-
-[Perl5] Perl5 Programmers reference, <br>
-<tt> http://www.metronet.com/perlinfo/doc </tt>, (1996). <br> <br>
-
-[vtk] W. Schroeder, K. Martin, and B. Lorensen, <em> The
-Visualization Toolkit </em>, Prentice Hall (1995). <br> <br>
-
-[Invent] J. Wernecke,<em> The Inventor Mentor </em>, Addison-Wesley Publishing (1994). <br> <br>
-
-[Wetherall] D. Wetherall, C. J. Lindblad, <em> Extending Tcl for
-Dynamic Object-Oriented Programming </em>, Proceedings of the USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[OpenGL] J. Neider, T. Davis, M. Woo, <em> OpenGL Programming Guide </em>, Addison-Wesley Publishing (1993). <br> <br>
-
-</body>
-</html>
-
-
-
-
-
-
-
-
diff --git a/swigweb/papers/Tcl96/Tcl_Talk.pdf b/swigweb/papers/Tcl96/Tcl_Talk.pdf
deleted file mode 100755
index 9e6d27f..0000000
--- a/swigweb/papers/Tcl96/Tcl_Talk.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Tcl96/fig1.gif b/swigweb/papers/Tcl96/fig1.gif
deleted file mode 100755
index b80c870..0000000
--- a/swigweb/papers/Tcl96/fig1.gif
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Tcl96/hits.gif b/swigweb/papers/Tcl96/hits.gif
deleted file mode 100755
index 7aea968..0000000
--- a/swigweb/papers/Tcl96/hits.gif
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Tcl96/steer2.gif b/swigweb/papers/Tcl96/steer2.gif
deleted file mode 100755
index 02b0187..0000000
--- a/swigweb/papers/Tcl96/steer2.gif
+++ /dev/null
Binary files differ
diff --git a/swigweb/papers/Tcl96/tcl96.html b/swigweb/papers/Tcl96/tcl96.html
deleted file mode 100755
index c2bdbdc..0000000
--- a/swigweb/papers/Tcl96/tcl96.html
+++ /dev/null
@@ -1,1084 +0,0 @@
-<html>
-<title> SWIG : An Easy to Use Tool For Integrating Scriptint Languages
-with C and C++ </title>
-<body bgcolor="#ffffff">
-<h1>
-SWIG : An Easy to Use Tool for Integrating Scripting Languages with C and C++
-</h1>
-
-<b> David M. Beazley </b> <br>
-<em> Department of Computer Science <br>
-University of Utah <br>
-Salt Lake City, Utah 84112 <br>
-beazley@cs.utah.edu <br> </em>
-
-<br> <br>
-(Presented at the 4th Annual Tcl/Tk Workshop, Monterey, CA. July 6-10, 1996. )
-
-<h2> Abstract </h2>
-
-<em>
-I present SWIG (Simplified Wrapper and Interface Generator), a
-program development tool that automatically generates the bindings
-between C/C++ code and common scripting languages including
-Tcl, Python, Perl and Guile. SWIG supports most C/C++ datatypes
-including pointers, structures, and classes.
-Unlike many other approaches, SWIG
-uses ANSI C/C++ declarations and requires the user to make virtually
-no modifications to the underlying C code.
-In addition, SWIG automatically
-produces documentation in HTML, LaTeX, or ASCII format.
-SWIG has been primarily designed for scientists, engineers, and application
-developers who would like to use scripting languages with their C/C++ programs
-without worrying about the underlying implementation details
-of each language or using a complicated software development tool.
-This paper concentrates on SWIG's use with Tcl/Tk.
-</em>
-
-<h2> 1. Introduction </h2>
-SWIG (Simplified Wrapper and Interface Generator)
-is a software
-development tool that I never intended to develop. At the time,
-I was trying to add a data analysis and visualization capability to
-a molecular dynamics (MD) code I had helped develop for massively
-parallel supercomputers at Los Alamos National Laboratory [Beazley,Lomdahl]. I wanted
-to provide a simple, yet flexible user interface that could be used
-to glue various code modules together and an extensible scripting
-language seemed like an ideal solution. Unfortunately there were constraints.
-First, I didn't want to hack up 4-years of code development trying to
-fit our MD code into yet another interface scheme (having done so several
-times already). Secondly, this code
-was routinely run on systems ranging from Connection Machines and Crays to
-workstations and I didn't want to depend on any one
-interface language---out of fear that it might not be supported on
-all of these platforms. Finally, the users were constantly adding
-new code and making modifications. I needed a flexible, yet easy to use
-system that did not get in the way of the physicists. <br> <br>
-
-SWIG is my solution to this problem. Simply stated, SWIG automatically generates all
-of the code
-needed to bind C/C++ functions with scripting languages using only
-a simple input file containing C function and variable declarations.
-At first, I supported
-a scripting language I had developed specifically for use
-on massively parallel systems. Later I decided to rewrite SWIG in C++ and extend it to support
-Tcl, Python, Perl, Guile and other languages that interested me. I also
-added more data-types, support for pointers, C++ classes, documentation generation, and
-a few other features. <br> <br>
-
-This paper provides a brief overview of SWIG
-with a particular emphasis on Tcl/Tk. However, the reader should
-remain aware that SWIG works equally well with
-Perl and other languages. It is not my intent to provide
-a tutorial or a user's guide, but rather to show
-how SWIG can be used to do interesting things such as
-adding Tcl/Tk interfaces to existing C applications,
-quickly debugging and prototyping C code,
-and building interface-language-independent C applications.
-
-<h2> 2. Tcl and Wrapper Functions </h2>
-
-In order to add a new C or C++ function to Tcl, it is necessary to
-write a special ``wrapper'' function that parses the function arguments
-presented as ASCII strings by the Tcl interpreter into a representation
-that can be used to call the C function. For example, if you wanted
-to add the factorial function to Tcl, a wrapper function might
-look like the following : <br>
-
-<blockquote>
-<tt> <pre>
-int wrap_fact(ClientData clientData,
- Tcl_Interp *interp,
- int argc, char *argv[]) {
- int result;
- int arg0;
- if (argc != 2) {
- interp->result = "wrong # args";
- return TCL_ERROR;
- }
- arg0 = atoi(argv[1]);
- result = fact(arg0);
- sprintf(interp->result,"%d",result);
- return TCL_OK;
-}
-</pre>
-</tt>
-</blockquote>
-
-In addition to writing the wrapper function, a user will also need to
-write code to add this function to the Tcl interpreter. In the case of
-Tcl 7.5, this could be done by writing an initialization function to
-be called when the extension is loaded dynamically. While writing
-a wrapper function usually is not too difficult, the process quickly
-becomes tedious and error prone as the number of functions increases.
-Therefore, automated approaches for producing wrapper functions are
-appealing--especially when working with a large number of C functions
-or with C++ (in which case the wrapper code tends to get more complicated).
-
-<h2> 3. Prior Work </h2>
-
-The idea of automatically generating wrapper code is certainly not new.
-Some efforts such as
-Itcl++, Object Tcl, or the XS language included with Perl5, provide a mechanism for
-generating wrapper code, but require the user to provide detailed
-specifications, type conversion rules, or use a specialized
-syntax [heidrich,Wetherall,perl5]. Large packages
-such as the Visualization Toolkit (vtk) may use their own C/C++ translators,
-but these almost always tend to be somewhat special purpose (in fact, SWIG started
-out in this manner) [vtk].
-If supporting multiple languages is the ultimate goal, a programmer might
-consider a package such as ILU [Janssen].
-Unfortunately,
-this requires the user to provide specifications in IDL--a process which
-is unappealing to many users.
-SWIG is not necessarily intended to compete with
-these approaches, but rather is designed to be a no-nonsense tool that
-scientists and engineers can use to easily add Tcl and other scripting
-languages to their own applications. SWIG is also
-very different than Embedded Tk (ET) which also aims to
-simplify code development [ET]. Unlike ET, SWIG is designed to
-integrate C functions into Tcl/Tk as opposed to integrating Tcl/Tk into
-C programs.
-
-<h2> 4. A Quick Tour of SWIG </h2>
-
-<h3> 4.1 Organization </h3>
-
-<center>
-<img alt = "SWIG Organization" src="fig1.gif"> <br>
-Figure 1 : SWIG Organization <br> <br>
-</center>
-
-Figure 1 shows the structure of SWIG. At the core is a YACC parser
-for reading input files along with some utility functions.
-To generate code,
-the parser calls about a dozen functions from a generic language
-class to do things like write a wrapper function, link a
-variable, wrap a C++ member function, etc... Each target language is
-implemented as a C++ class containing the functions that emit
-the resulting C code. If an ``empty'' language definition is given
-to SWIG, it will produce no output. Thus, each language class can
-be implemented in almost any manner.
-The documentation system is implemented in a similar manner and can
-currently produce ASCII, LaTeX, or HTML output. As output,
-SWIG produces a C file that should be compiled and linked with the rest
-of the code and a documentation file that can be used for later reference.
-
-<h3> 4.2. Interface Files </h3>
-
-As input, SWIG takes a single input file referred to as an ``interface file.''
-This file contains a few SWIG specific directives, but otherwise contains
-ANSI C function and variable declarations. Unlike the approach in [Heidrich], no type conversion rules are needed and all declarations are made
-using familiar ANSI C/C++ prototypes. The following code shows an
-interface file for wrapping a few C file I/O and memory management functions.
-
-<blockquote>
-<tt> <pre>
-/* File : file.i */
-%module fileio
-%{
-#include <stdio.h>
-%}
-
-FILE *fopen(char *filename, char *type);
-int fclose(FILE *stream);
-typedef unsigned int size_t
-size_t fread(void *ptr, size_t size,
- size_t nobj, FILE *stream);
-size_t fwrite(void *ptr, size_t size,
- size_t nobj,FILE *stream);
-void *malloc(size_t nbytes);
-void free(void *);
-</pre> </tt> </blockquote>
-
-The <tt> %module </tt> directive
-sets the name of the initialization function. This is optional, but is
-recommended if building a Tcl 7.5 module.
-Everything inside the <tt> %{, %} </tt>
-block is copied directly into the output, allowing the inclusion of
-header files and additional C code.
-Afterwards, C/C++ function and variable declarations are listed in any
-order.
-Building a new Tcl module is usually as
-easy as the following :
-
-<blockquote>
-<tt> <pre>
-unix > swig -tcl file.i
-unix > gcc file_wrap.c -I/usr/local/include
-unix > ld -shared file_wrap.o -o Fileio.so
-</pre> </tt>
-</blockquote>
-
-
-<h3> 4.3. A Tcl Example </h3>
-
-Newly added functions work like ordinary Tcl procedures. For
-example, the following Tcl script copies a file using the binary
-file I/O functions added in the previous example :
-
-<blockquote>
-<tt> <pre>
-proc filecopy {name1 name2} {
- set buffer [malloc 8192];
- set f1 [fopen $name1 r];
- set f2 [fopen $name2 w];
- set nbytes [fread $buffer 1 8192 $f1];
- while {$nbytes > 0} {
- fwrite $buffer 1 $nbytes $f2;
- set nbytes [fread $buffer 1 8192 $f1];
- }
- fclose $f1;
- fclose $f2;
- free $buffer
-}
-</pre> </tt>
-</blockquote>
-
-<h3> 4.4. Datatypes and Pointers </h3>
-
-SWIG supports the basic datatypes of <tt> int, short,
-long, float, double, char, </tt> and <tt> void </tt>
-as well as signed and unsigned integers. SWIG
-also allows derived types such as pointers, structures, and classes,
-but these are all encoded as pointers.
-If an unknown type is encountered, SWIG assumes
-that it is a complex datatype that has been defined earlier.
-No attempt is made to figure out what data that datatype actually contains
-or how it should be used. Of course, this this is only possible
-since SWIG's mapping of complex types into pointers allows them
-to be handled in a uniform manner.
-As a result, SWIG does not normally need any sort
-of type-mapping, but <tt> typedef </tt> can be used to map any of the built-in
-datatypes to new types if desired. <br> <br>
-
-SWIG encodes pointers as hexadecimal strings with type-information. This
-type information is used to provide a run-time type checking mechanism.
-Thus, a typical SWIG pointer looks something like the following : <br> <br>
-
-<center>
-<tt> _1008e614_Vector_p </tt> <br> <br>
-</center>
-
-If this pointer is passed into a function requiring some other kind of
-pointer, SWIG will generate a Tcl error and return an error message.
-The NULL pointer is represented by the string "NULL". The SWIG run-time
-type checker is saavy to typedefs and the relationship between base classes
-and derived classes in C++. Thus if a
-user specifies <br> <br>
-
-<center>
-<tt> typedef double Real; </tt> <br> <br>
-</center>
-
-the type checker knows that <tt> Real * </tt> and <tt> double * </tt>
-are equivalent (more on C++ in a minute).
-From the point of view of other Tcl extensions,
-SWIG pointers should be seen as special "handles" except that they
-happen to contain the pointer value and its type. <br> <br>
-
-To some, this approach may seem horribly restrictive (or error prone),
-but keep in mind that SWIG was primarily designed to work with
-existing C applications. Since most C programs pass complex datatypes
-around by reference this technique works remarkably well in practice.
-Run time type-checking also eliminates most common crashes by catching
-stupid mistakes such as using a wrong variable name or forgetting the
-"$" character in a Tcl script. While it is still possible to crash Tcl by forging a
-SWIG pointer value (or making a call to buggy C code), it is worth
-emphasizing that existing Tcl extensions
-may also crash if given an invalid handle.
-
-<h3> 4.5. Global Variables and Constants </h3>
-
-SWIG can install global C variables and constants using Tcl's variable linkage
-mechanism.
-Variables may also be declared as ``read only''
-within the Tcl interpreter. The following example shows
-how variables and constants can be added to Tcl :
-
-<blockquote>
-<tt> <pre>
-// SWIG file with variables and constants
-%{
-%}
-
-// Some global variables
-extern int My_variable;
-extern char *default_path;
-extern double My_double;
-
-// Some constants
-#define PI 3.14159265359
-#define PI_4 PI/4.0
-enum colors {red,blue,green};
-const int SIZEOF_VECTOR = sizeof(Vector);
-
-// A read only variable
-%readonly
-extern int Status;
-%readwrite
-
-</pre>
-</tt>
-</blockquote>
-
-<h3> 4.6. C++ Support </h3>
-
-The SWIG parser can handle simple C++ class definitions and supports public
-inheritance, virtual functions, static functions, constructors and
-destructors. Currently, C++ translation is performed
-by politely tranforming C++ code into C code and generating wrappers for the
-C functions. For example, consider the following SWIG interface file
-containing a C++ class definition:
-
-<blockquote>
-<tt> <pre>
-%module tree
-%{
-#include "tree.h"
-%}
-
-class Tree {
-public:
- Tree();
- ~Tree();
- void insert(char *item);
- int search(char *item);
- int remove(char *item);
-static void print(Tree *t);
-};
-</pre>
-</tt>
-</blockquote>
-
-When translated, the class will be access used the following set of
-functions (created automatically by SWIG).
-
-<blockquote>
-<tt>
-<pre>
-Tree *new_Tree();
-void delete_Tree(Tree *this);
-void Tree_insert(Tree *this, char *item);
-int Tree_search(Tree *this, char *item);
-int Tree_remove(Tree *this, char *item);
-void Tree_print(Tree *t);
-</pre>
-</tt>
-</blockquote>
-
-
-All C++ functions wrapped by SWIG explicitly require the <tt> this </tt> pointer
-as shown. This approach has the advantage of working for all of the target
-languages. It also makes it easier to pass objects between
-other C++ functions since every C++ object is simply represented as a SWIG pointer. SWIG does not support function overloading, but overloaded functions
-can be resolved by renaming them with the SWIG <tt> %name </tt> directive as follows:
-
-<blockquote>
-<tt> <pre>
-class List {
-public:
- List();
-%name(ListMax) List(int maxsize);
-...
-};
-</pre> </tt> </blockquote>
-
-The approach used by SWIG is
-quite different than that used in systems such as
-Object Tcl or vtk [vtk,Wetherall]. As a result, users of those systems
-may find it to be confusing. However,
-It is important to note that the modular design of
-SWIG allows the user to completely redefine the output behavior of
-the system. Thus, while the current C++ implementation is quite different
-than other systems supporting C++, it would be entirely possible
-write a new SWIG module that wrapped C++ classes into a representation
-similar to that used by Object Tcl (in fact, in might even be possible
-to use SWIG to produce the input files used for Object Tcl).
-
-<h3> 4.7. Multiple Files and Code Reuse </h3>
-
-An essential feature of SWIG is its support for multiple files
-and modules. A SWIG interface file may include another interface
-file using the "<tt> %include </tt>" directive. Thus, an interface
-for a large system might be broken up into a collection of smaller
-modules as shown
-
-<blockquote>
-<tt> <pre>
-%module package
-%{
-#include "package.h"
-%}
-
-%include geometry.i
-%include memory.i
-%include network.i
-%include graphics.i
-%include physics.i
-
-%include wish.i
-</pre> </tt> </blockquote>
-
-Common operations can be placed into a SWIG library for use in
-all applications. For example, the <tt> %include wish.i </tt> directive
-tells SWIG to include code for the <tt> Tcl_AppInit() </tt> function
-needed to rebuild the <tt> wish </tt> program. The library can also be
-used to build modules
-allowing SWIG to be used with common Tcl extensions such
-as Expect [Expect]. Of course, the primary use of the library is with
-large applications such as Open-Inventor which contain hundreds of
-modules and a substantial class hierarchy [Invent]. In this case a user
-could use SWIG's include mechanism to selectively pick which modules
-they wanted to use for a particular problem.
-
-<h3> 4.8. The Documentation System </h3>
-
-SWIG produces documentation in ASCII, LaTeX, or HTML
-format describing everything that was wrapped. The documentation
-follows the syntax rules of the target language and can
-can be further enhanced by adding descriptions in a C/C++ comment
-immediately following a declaration. These comments may also contain
-embedded LaTeX or HTML commands. For example:
-
-<blockquote>
-<tt> <pre>
-extern size_t fread(void *ptr, size_t size,
- size_t nobj, FILE *stream);
-/* {\tt fread} reads from {\tt stream} into
-the array {\tt ptr} at most {\tt nobj} objects
-of size {\tt size}. {\tt fread} returns
-the number of objects read. */
-</pre> </tt> </blockquote>
-
-When output by SWIG and processed by LaTeX, this appears as follows :
-
-<ul>
-<tt> size_t : fread ptr size nobj stream </tt> <br>
-<ul>
- <tt> fread </tt> reads from <tt> stream </tt> into the array <tt> ptr </tt> at
- most <tt> nobj </tt> objects of size <tt> size </tt>. <tt> fread </tt>
- returns
- the number of objects read.
-</ul>
-</ul>
-
-<h3> 4.9. Extending the SWIG System </h3>
-
-Finally, SWIG itself can be extended by the user to provide new
-functionality. This is done by modifying an existing or creating a
-new language class. A typical class must specify the following
-functions that determine the behavior of the parser output :
-
-<blockquote>
-<tt> <pre>
-// File : swigtcl.h
-class TCL : public Language {
-private:
- // Put private stuff here
-public :
- TCL();
- int main(int, char *argv[]);
- void create_function(char *,char *,DataType*,
- ParmList *);
- void link_variable(char *,char *,DataType *);
- void declare_const(char *,int,char *);
- void initialize(void);
- void headers(void);
- void close(void);
- void usage_var(char *,DataType*,char **);
- void usage_func(char *,DataType*,ParmList*,
- char **);
- void usage_const(char *,int,char*,char**);
- void set_module(char *);
- void set_init(char *);
-};
-</pre> </tt> </blockquote>
-
-Descriptions of these functions can be found in the SWIG
-users manual. To build a new version of SWIG, the user
-only needs to provide the function definitions and a main
-program which looks something like the following :
-
-<blockquote>
-<tt> <pre>
-
-// SWIG main program
-
-#include "swig.h"
-#include "swigtcl.h"
-
-int main(int argc, char **argv) {
-
- Language *lang;
-
- lang = new TCL;
- SWIG_main(argc,argv,lang,(Documentation *) 0);
-
-}
-</pre> </tt> </blockquote>
-
-When linked with a library file, any extensions and
-modifications can now be used with the SWIG parser. While
-writing a new language definition is not entirely trivial,
-it can usually be done by just copying one of the existing
-modules and modifying it appropriately.
-
-<h2> 5. Examples </h2>
-
-<h3> 5.1. A C-Tcl Linked List </h3>
-
-SWIG can be used to build simple data structures that are usuable in
-both C and Tcl. The following code shows a SWIG interface file for
-building a simple linked list.
-
-<blockquote>
-<tt> <pre>
-/* File : list.i */
-%{
-struct Node {
- Node(char *n) {
- name = new char[strlen(n)+1];
- strcpy(name,n);
- next = 0;
- };
- char *name;
- Node *next;
-};
-%}
-
-// Just add struct definition to
-// the interface file.
-
-struct Node {
- Node(char *);
- char *name;
- Node *next;
-};
-
-</pre> </tt> </blockquote>
-
-When used in a Tcl script, we can now create new nodes and access
-individual members of the <tt> Node </tt> structure. In fact, we can
-write code to convert between Tcl lists and linked lists entirely
-in Tcl as shown :
-
-<blockquote>
-<tt> <pre>
-# Builds linked list from a Tcl list
-proc buildlist {list head} {
- set nitems [llength $list];
- for {set i 0} {$i < $nitems} {incr i -1} {
- set item [lrange $list $i $i]
- set n [new_Node $item]
- Node_set_next $n $head
- set head $n
- }
- return $head
-}
-# Builds a Tcl list from a linked list
-proc get_list {llist} {
- set list {}
- while {$llist != "NULL"} {
- lappend list [Node_name_get $llist]
- set llist [Node_get_next $llist]
- }
- return $list
-}
-</pre> </tt> </blockquote>
-
-When run interactively, we could now use our Tcl functions as
-follows.
-
-<blockquote>
-<tt> <pre>
-% set l {John Anne Mary Jim}
-John Anne Mary Jim
-% set ll [buildlist $l _0_Node_p]
-_1000cab8_Node_p
-% get_list $ll
-Jim Mary Anne John
-% set ll [buildlist {Mike Peter Dave} $ll]
-_1000cc38_Node_p
-% get_list $ll
-Dave Peter Mike Jim Mary Anne John
-%
-</pre> </tt> </blockquote>
-Aside from the pointer values, our script acts like any other
-Tcl script. However, we have built up a real
-C data structure that could be easily passed to other C functions
-if needed.
-
-<h3> 5.2. Using C Data-Structures with Tk </h3>
-
-In manner similar to the linked list example, Tcl/Tk can be used
-to build complex C/C++ data structures. For example, suppose we
-wanted to interactively build a graph of ``Nodes'' for use in a C
-application.
-A typical interface file might include the following functions:
-
-<blockquote> <tt> <pre>
-%{
-#include "nodes.h"
-%}
-
-%include wish
-extern Node *new_node();
-extern void AddEdge(Node *n1, Node *n2);
-</pre> </tt> </blockquote>
-
-Within a Tcl/Tk script, loosely based on one to make ball and stick graphs
-in [Ousterhout], a graph could be built as follows:
-
-<blockquote> <tt> <pre>
-proc makeNode {x y} {
- global nodeX nodeY nodeP edgeFirst edgeSecond
- set new [.create oval [expr $x-15] \
- [expr $y-15] [expr $x+15] \
- [expr $y+15] -outline black \
- -fill white -tags node]
- set newnode [new_node]
- set nodeX($new) $x
- set nodeY($new) $y
- set nodeP($new) $newnode
- set edgeFirst($new) {}
- set edgeSecond($new) {}
-}
-proc makeEdge {first second} {
- global nodeX nodeY nodeP edgeFirst edgeSecond
- set x1 $nodeX($first); set y1 $nodeY($first)
- set x2 $nodeX($second); set y2 $nodeY($second)
- set edge [.c create line $x1 $y1 $x2 $y2 \
- -tags edge}
- .c lower edge
- lappend edgeFirst($first) $edge
- lappend edgeSecond($first) $edge
- AddEdge $nodeP($first) $nodeP($second)
-}
-</pre> </tt> </blockquote>
-
-These functions create
-Tk canvas items, but also attach a pointer to a C data structure to each one.
-This is done by maintaining an associative array mapping
-item identifiers to pointers (with the <tt> nodeP() </tt> array).
-When a
-particular ``node'' is referenced later, we can use this to
-get its pointer use it in calls to C functions.
-
-<h3> 5.3. Parsing a C++ Simple Class Hierarchy </h3>
-
-As mentioned earlier, SWIG can handle C++ classes and public
-inheritance. The following example provides a few classes
-and illustrates how this is accomplished (some code has been
-ommitted for readability).
-
-<blockquote> <tt> <pre>
-// A SWIG inheritance example
-%module shapes
-%{
-#include "shapes.h"
-%}
-
-class Shape {
-private:
- double xc, yc;
-public:
- virtual double area() = 0;
- virtual double perimeter() = 0;
- void set_position(double x, double y);
- void print_position();
-};
-
-class Circle: public Shape {
- private:
- double radius;
- public:
- Circle(double r);
- double area();
- double perimeter();
-};
-
-class Square : public Shape {
-private:
- double width;
-public:
- Square(double w);
- double area();
- double perimeter();
-};
-
-</pre> </tt> </blockquote>
-
-Now, when wrapped by SWIG (note :
-When parsing C++ classes, SWIG throws away everything declared as private,
-inline code, and alot of the other clutter found in C++ header files.
-Primarily this is provided only to make it easier to build interfaces from
-existing C++ header files.), we can use our class structure as follows:
-
-<blockquote> <tt> <pre>
-% set c [new_Circle 4]
-_1000ad70_Circle_p
-% set s [new_Square 10]
-_1000adc0_Square_p
-% Shape_area $c
-50.26548246400000200
-% Shape_area $s
-100.00000000000000000
-% Shape_set_position $c -5 10
-% Circle_print_position $c
-xc = -5, yc = 10
-%
-</pre> </tt> </blockquote>
-
-In our example, we have created new <tt> Circle </tt> and <tt> Square </tt> objects,
-but these can be used interchangably in any functions defined in the <tt> Shape </tt>
-base class. The SWIG type checker is encoded with the class hierarchy and
-knows the relationship between the different classes. Thus, while an
-object of type <tt> Circle </tt> is perfectly acceptable to a function operating
-on shapes, it would be unacceptable to a function operating only on the
-<tt> Square </tt> type. As in C++, any functions in the base class can be
-called in the derived class as shown by the <tt> Circle_print_position </tt>
-function above.
-
-<h2> 6. Using SWIG in Real Applications </h2>
-
-So far only a few simple toy examples have been presented to illustrate
-the operation of SWIG in general.
-This section will describe how SWIG can be used
-with larger applications.
-
-<h3> 6.1. Use in Scientific Applications </h3>
-
-Many users, especially within the scientific and engineering
-community, have spent years developing simulation codes.
-While many of these users appreciate the
-power that a scripting language can provide, they don't want to
-completely rewrite their applications or spend all of their time
-trying to build a user-interface (most users would rather be working
-on the scientific problem at hand). While SWIG certainly won't do everything,
-it can dramatically simplify this process. <br> <br>
-
-As an example, the first SWIG application was the SPaSM molecular
-dynamics code developed at Los Alamos National Laboratory
-[Beazley,Lomdahl]. This code is currently being used for materials
-science problems and consists of more than 200 C functions and about 20000 lines
-of code.
-In order to use SWIG, only the <tt> main() </tt> function had to be
-rewritten along with a few other minor modifications.
-The full user interface is built using a collection of modules for
-simulation, graphics, memory management, etc...
-A user may also supply their own interface modules--allowing the code to
-be easily extended with new functionality capabilities as needed.
-All of the interface files, containing a few hundred lines of
-function declarations, are automatically translated into more than
-2000 lines of wrapper code at compile time. As a result, many users
-of the system know how to extend it, but are unaware of the actual
-wrapping procedure. <br> <br>
-
-After modifying the SPaSM code to use SWIG, most of the C code remained
-unchanged. In fact, in subsequent work, we were able to eliminate
-more than 25% of the source code--almost all of which was related to the
-now obsolete interface method that we replaced. More importantly, we
-were able to turn a code that was difficult to use and modify into a
-flexible package that was easy to use and extend. This has had a
-huge impact, which can not be understated, on the use of the SPaSM
-code to solve real problems.
-
-<h3> 6.2. Open-GL and Inventor </h3>
-
-While SWIG was primarily designed to work with application codes, it
-can also be used to wrap large libraries. At the University of Utah,
-Peter-Pike Sloan used SWIG to wrap the entire contents of the Open-GL
-library into Tcl for use with an Open-GL Tk widget. The process of
-wrapping Open-GL with SWIG was as simple as the following :
-
-<ul>
-<li> Make a copy of the <tt> gl.h </tt> header file.
-<li> Clean it up by taking a few C preprocessor directives out
- of it. Fix a few typedefs.
-<li> Insert the following code into the beginning
-<blockquote> <tt> <pre>
-%module opengl
-%{
-#include <GL/gl.h>
-%}
-... Copy edited gl.h here ...
-</pre> </tt> </blockquote>
-
-<li> Modify the Open-GL widget to call <tt> Opengl_Init </tt>.
-<li> Recompile
-</ul>
-
-The entire process required only about 10 minutes of work, but resulted
-in more than 500 constants and 360 functions being added to Tcl. Furthermore,
-this extension allows Open-GL commands to be issued directly from Tcl's
-interpreted environment as shown in this example
-(from the Open-GL manual [OpenGL]).
-
-<blockquote> <tt> <pre>
-% ... open GL widget here ...
-% glClearColor 0.0 0.0 0.0 0.0
-% glClear $GL_COLOR_BUFFER_BIT
-% glColor3f 1.0 1.0 1.0
-% glOrtho -1.0 1.0 -1.0 1.0 -1.0 1.0
-% glBegin $GL_POLYGON
-% glVertex2f -0.5 -0.5
-% glVertex2f -0.5 0.5
-% glVertex2f 0.5 0.5
-% glVertex2f 0.5 -0.5
-% glEnd
-% glFlush
-</pre> </tt> </blockquote>
-
-Early work has also been performed on using SWIG to wrap portions
-of the Open-Inventor package [Invent]. This is a more ambitious project
-since Open-Inventor consists of a very large collection of header
-files and C++ classes. However, the SWIG library mechanism can be
-used effective in this case. For each Inventor header, we can create
-a sanitized SWIG interface file (removing alot of the clutter found in
-the header files). These interface files can then be organized to mirror the
-structure of the Inventor system. To build a module for Tcl, a user
-could simply specify which modules they wanted to use as follows :
-
-<blockquote> <tt> <pre>
-%module invent
-%{
-... put headers here ...
-%}
-
-%include "Inventor/Xt/SoXt.i"
-%include "Inventor/Xt/SoXtRenderArea.i"
-%include "Inventor/nodes/SoCone.i"
-%include "Inventor/nodes/SoDirectionalLight.i"
-%include "Inventor/nodes/SoMaterial.i"
-%include "Inventor/nodes/SoPerspectiveCamera.i"
-%include "Inventor/nodes/SoSeparator.i"
-</pre> </tt> </blockquote>
-
-While wrapping the Inventor library will require significantly
-more work than Open-GL, SWIG can be used effectively with such
-systems.
-
-<h3> 6.3. Building Interesting Applications by Cut and Paste </h3>
-
-SWIG can be used to construct tools out of dissimiliar
-packages and libraries.
-In contrast to combining packages at an input level as one might
-do with with Expect, SWIG can be used to build applications at a
-function level [Expect].
-For example, using
-a simple interface file, you can wrap the
-C API of MATLAB 4.2 [MATLAB].
-This in turn lets you build a Tcl/Tk interface for controlling
-MATLAB programs. Separately, you could wrap a numerical simulation
-code. Now, a few translation functions could be written and both
-packages combined into a single Tcl/Tk application. You have
-now built a simple ``computational steering'' system that allows you
-to run a simulation code, visualize data in MATLAB, and control the
-entire system with a Tcl/Tk based interface. Figure 2 shows
-a screen snapshot from such a simulation in which the SPaSM molecular
-dynamics code, a visualization module library, image server (using xv),
-and MATLAB have been
-combined. Under this system, the user can interactively set up
-and run simulations while watching the results evolve in real-time.
-<br> <br>
-<center>
-<img alt = "Tcl/Tk/MATLAB/SPASM Figure" src="steer2.gif"> <br>
-Figure 2: Simple Tcl/Tk Steering Application Built with SWIG <br>
-</center>
-
-<h3> 6.4. Language Independent Applications </h3>
-
-
-Each scripting language has it's own strengths and weaknesses.
-Rather
-than trying to choose the language that is the best at everything (which
-is probably impossible),
-SWIG allows a user to use the best language for the job at hand. I'm
-always finding myself writing little utilities and programs to support
-my scientific computing work. Why should I be forced to use only one
-language for everything? With SWIG, I can put a Perl interface on a
-tool and switch over to Tcl/Tk at anytime by just changing a few
-Makefile options. <br> <br>
-
-Since SWIG provides a language-independent interface specification,
-it is relatively easy to use SWIG generated modules in a variety of
-interesting applications. For example, the identical MATLAB
-module used in the last Tcl example could be imported as Perl5 module
-and combined with a Perl script to produce graphical displays from
-Web-server logs as shown in Figure 3. <br> <br>
-
-<center>
-<img alt="Perl5 web stats example" src="hits.gif"> <br>
-Figure 3:Web-server activity graph. Generated from a Perl script, but
-uses an unmodified SWIG generated module for integrating MATLAB with Tcl/Tk. <br> <br>
-</center>
-
-Some have promoted the idea of encapsulating several languages into
-a higher level language as has been proposed with Guile [Lord].
-This may be fine if one wants to write code that uses different languages
-all at once, but when I want to use only Tcl or Perl for an application,
-I almost always prefer using the real versions instead of an encapsulated
-variant. SWIG makes this possible without much effort.
-
-<h3> 6.5. Using Tcl as a debugger </h3>
-
-Since SWIG can work with existing C code, it can be used quite effectively
-as a debugger.
-You can wrap C functions and interact
-with them from <tt> tclsh </tt> or <tt> wish </tt>.
-Unlike most traditional debuggers, you
-can create objects, buffers, arrays, and other things on the fly
-by putting appropriate definitions in the interface file.
-Since <tt> tclsh </tt> or <tt> wish </tt> provides a <tt> main() </tt> function, you
-can even rip small pieces out of a larger package without including
-that package's main program.
-Scripts can be written to test out different parts of your
-code as it is developed. When you are satisfied with the module,
-removing the interface is as easy as discarding the SWIG interface
-file. I have used SWIG as a debugger for developing graphics libraries,
-network servers, simulation codes, and a wide range of other projects--some
-of which didn't even use a scripting language when completed.
-
-<h2> 7. Limitations </h2>
-
-SWIG represents a balance of flexibility and ease of use.
-I have always felt that the tool shouldn't be more complicated than
-the original problem. Therefore, SWIG certainly won't do everything.
-While I believe the pointer representation of complex datatypes works
-well in practice, some users have found this to be too general or
-confusing. SWIG's
-support for C++ is also limited by the fact that SWIG does not support
-operator overloading, multiple inheritance, templates, and a number
-of other more advanced C++ features. SWIG also lacks support for
-default or variable length function arguments, array notation,
-pointers to functions (unless hidden by a typedef) and an exception
-mechanism.
-Finally, SWIG
-does
-not support all of the features of Tcl such as associative arrays.
-These aren't an inherent part of the C language so it is difficult
-to generalize how they should be handled or generated. I prefer to
-keep the tool simple while leaving these issues up to the individual
-programmer. <br> <br>
-
-
-Fortunately, it is almost always possible to work around
-many problems by writing special library functions or making
-modifications to the SWIG language modules to produce the desired effect.
-For example, when wrapping Open-GL, SWIG installed all of the Open-GL
-constants as Tcl global variables. Unfortunately, none of these
-variables were accessible inside Tcl procedures unless they were explicitly
-declared global. By making a modification to the Tcl language module,
-it was possible to put the GL constants into hash table and perform
-a hidden ``lookup'' inside all of the GL-related functions. Similarly,
-much of the functionality of SWIG can be placed into library
-files for use in other modules.
-
-<h2> 8. Conclusions </h2>
-
-SWIG has been in use for approximately one year. At Los Alamos National Laboratory, its use with the SPaSM code has
-proven to
-be a remarkably simple, stable, and bug-free way to build and modify user
-interfaces. At the University of Utah, SWIG is being used in a variety
-of other applications where the users have quickly come to appreciate its
-ease of use and flexibility. <br> <br>
-
-While SWIG may be inappropriate for certain applications, I feel that it
-opens up Tcl/Tk, Python, Perl, Guile, and other languages to
-users who would like to develop interesting user interfaces for their codes,
-but who don't want to worry about the low-level details or figuring
-out how to use a complicated tool. <br> <br>
-
-Future directions for SWIG include support for other scripting languages,
-and a library of extensions. SWIG may also be extended to support packages
-such as incremental Tcl. Work is also underway to port SWIG to non-unix
-platforms.
-
-<h2> Acknowledgments </h2>
-
-This project would not have been possible without the support of a number
-of people. Peter Lomdahl, Shujia Zhou, Brad Holian, Tim Germann, and Niels
-Jensen at Los Alamos National Laboratory were the first users and were
-instrumental in testing out the first designs. Patrick Tullmann at
-the University of Utah suggested the idea of automatic documentation
-generation. John Schmidt, Kurtis
-Bleeker, Peter-Pike Sloan, and Steve Parker at the University of Utah tested out some of the newer versions and
-provided valuable feedback. John Buckman suggested many interesting
-improvements and has been instrumental the recent development of SWIG.
-Finally
-I'd like to thank Chris Johnson and the members of the Scientific
-Computing and Imaging group at the University of Utah for their continued
-support and for putting up with my wrapping every software package
-I could get my hands on. SWIG was developed in part under the
-auspices of the US Department of Energy, the National Science Foundation,
-and National Institutes of Health.
-
-<h2> Availability </h2>
-
-SWIG is free software and available via anonymous FTP at <br> <br>
-
-<center>
-<tt> ftp.cs.utah.edu/pub/beazley/SWIG </tt> <br> <br>
-</center>
-
-More information is also available on the SWIG homepage at <br> <br>
-
-<center>
-<a href="http://www.cs.utah.edu/~beazley/SWIG"> <tt> http://www.cs.utah.edu/~beazley/SWIG </tt> </a>
-</center> <br> <br>
-
-<h2> References </h2>
-
-[Beazley] D.M. Beazley and P.S. Lomdahl,
-<em> Message-Passing Multi-Cell Molecular Dynamics on the Connection
-Machine 5 </em>, Parallel Computing 20 (1994) p. 173-195. <br> <br>
-
-[ET] Embedded Tk, <br>
-<tt> ftp://ftp.vnet.net/pub/users/drh/ET.html </tt> <br> <br>
-
-[Expect] Don Libes, <em> Exploring Expect </em>, O'Reilly & Associates, Inc. (1995). <br> <br>
-
-[Heidrich] Wolfgang Heidrich and Philipp Slusallek, <em>
-Automatic Generation of Tcl Bindings for C and C++ Libraries.</em>,
-USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[Janssen] Bill Janssen, Mike Spreitzer, <em> ILU : Inter-Language Unification via Object Modules </em>, OOPSLA 94 Workshop on Multi-Language
-Object Models. <br> <br>
-
-[Lomdahl] P.S. Lomdahl, P. Tamayo,
-N.Gronbech-Jensen, and D.M. Beazley,
-<em> Proc. of Supercomputing 93 </em>, IEEE Computer Society (1993), p. 520-527.
-<br> <br>
-
-[Lord] Thomas Lord, <em> An Anatomy of Guile, The Interface to
-Tcl/Tk </em>, Proceedings of the USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[MATLAB] <em> MATLAB External Interface Guide </em>, The Math Works, Inc. (1993).
-<br> <br>
-
-[Ousterhout] John K. Ousterhout, <em> Tcl and the Tk Toolkit </em>, Addison-Wesley Publishers (1994). <br> <br>
-
-[Perl5] Perl5 Programmers reference, <br>
-<tt> http://www.metronet.com/perlinfo/doc </tt>, (1996). <br> <br>
-
-[vtk] W. Schroeder, K. Martin, and B. Lorensen, <em> The
-Visualization Toolkit </em>, Prentice Hall (1995). <br> <br>
-
-[Invent] J. Wernecke,<em> The Inventor Mentor </em>, Addison-Wesley Publishing (1994). <br> <br>
-
-[Wetherall] D. Wetherall, C. J. Lindblad, <em> Extending Tcl for
-Dynamic Object-Oriented Programming </em>, Proceedings of the USENIX 3rd Annual Tcl/Tk Workshop (1995). <br> <br>
-
-[OpenGL] J. Neider, T. Davis, M. Woo, <em> OpenGL Programming Guide </em>, Addison-Wesley Publishing (1993). <br> <br>
-
-</body>
-</html>
-
-
-
-
-
-
-
-
diff --git a/swigweb/papers/Tcl98/TclChap.html b/swigweb/papers/Tcl98/TclChap.html
deleted file mode 100644
index 6aaea85..0000000
--- a/swigweb/papers/Tcl98/TclChap.html
+++ /dev/null
@@ -1,1898 +0,0 @@
-<!-- Published by Quadralay WebWorks HTML Lite 1.5.1 -->
-<!-- And munged by Dave's special Python script -->
-<html>
-<head>
-<title>Tcl and SWIG as a C/C++ Development Tool</title>
-</head>
-
-<body bgcolor="#ffffff">
-<a name="n0"></a><h1> Tcl and SWIG as a C/C++ Development Tool</h1>
-
-David M. Beazley <br>
-Department of Computer Science <br>
-University of Chicago<br>
-Chicago, Illinois 60637 <br>
-<address> <a href="http://www.cs.uchicago.edu/~beazley">beazley@cs.uchicago.edu</a></address> <br>
-<p>
-
-Copyright (C) 1998 <br>
-All Rights Reserved <br>
-
-<h2> About This Document </h2>
-
-This paper was originally written as a chapter for a Tcl book project.
-However, that project ran into some difficulties so the chapter (and
-the book itself) never appeared. Since the chapter may be of use to
-SWIG and Tcl users, it has been slightly revamped and republished in
-electronic form here. Permission is hereby granted to distribute this
-document in electronic form without royalties or fees provided that the above
-copyright and this notice appear in all reproductions.
-Hard-copy (paper) reproductions of this article are strictly
-prohibited without the written consent of the author.
-
-<a name="n1"></a><h2> Introduction</h2>
-One of the greatest strengths of Tcl is its ability to be easily extended with code written in C or C++. More often than not, compiled extensions to Tcl take the form of Tk widgets and general purpose libraries that provide access to databases, sockets, and other system services. Application developers might also extend Tcl in order to build a user-interface to a large package written in a compiled language. However, many C/C++ developers might be surprised to learn that Tcl can also be used as a general purpose C/C++ development tool--even in situations where Tcl is not part of the final product or design.<p>
-<p>
-To answer the question of why one might want to use Tcl for this purpose, consider the features that Tcl provides. First, Tcl provides an interpreted environment that allows you interactively control and manipulate the underlying C program. In other words, a Tcl interface allows you to call C functions, examine variables, and perform tasks that might otherwise be found in a debugger. Second, Tcl provides a high-level programming language that can be used to write programs, rapidly prototype new features, develop testing scripts, and interact with C code in a highly flexible manner. And finally, one shouldn't forget that Tcl allows you to utilize other extensions and modules people have developed (for example, you could later write a graphical user interface in Tk, access database systems with OraTcl, and so forth). In short, Tcl provides a number of attractive features that simply aren't found in a typical C/C++ development environment. <p>
-<p>
-In this chapter, I describe SWIG (Simplified Wrapper and Interface Generator), a development tool that integrates C/C++ code with Tcl and other scripting languages. SWIG is a compiler that can be used to automatically generate Tcl extensions to existing C code. It requires no modifications to the underlying code and provides access to most C programming features including pointers, arrays, structures, classes, and so forth. Unlike traditional Tcl extension programming, SWIG automatically generates extensions and hides almost all of the underlying implementation details. As a result, SWIG makes it easy to use Tcl in a rapidly changing C/C++ development environment--even if the underlying C/C++ code does not involve Tcl. <p>
-<p>
-SWIG is freely available from <a href="http://www.swig.org">www.swig.org</a> and supports Tcl on Unix, Windows-NT, and Macintosh platforms. SWIG also generates Perl and Python extensions and many of the features described in this chapter also apply to those languages. Finally, SWIG is packaged with more than 300 pages of tutorial-style documentation. It is not my intent to repeat that documentation here although there will be some unavoidable overlap. Rather, the goal is to describe how SWIG works, what it does, and how it can be used as a C/C++ development tool.<p>
-<a name="n6"></a><h3> Tcl Extension Building</h3>
-Tcl provides an extensive C API that can be used to create compiled extensions in C or C++. To integrate Tcl and C/C++, it is necessary to write "wrapper functions" that provide the glue between C and the Tcl interpreter. To illustrate, suppose that you wanted to access the pow(x,y) function in the C math library from Tcl. To do this, you would write a wrapper function such as the following :<p>
-<p>
-<blockquote><pre>/* PowObjCmd
- *
- * Tcl 8.x wrapper for the pow(x,y) function.
- */
-
-#include <math.h>
-int
-PowObjCmd(ClientData clientData, Tcl_Interp *interp,
- int objc, Tcl_Obj *CONST objv[])
-{
- Tcl_Obj *resultptr;
- double x,y,result;
- int error;
-
- if (objc != 3) {
- Tcl_WrongNumArgs(interp,2,objv,
- "Usage : pow x y");
- return TCL_ERROR;
- }
- error = Tcl_GetDoubleFromObj(interp, objv[1], &x);
- if (error != TCL_OK) return error;
- error = Tcl_GetDoubleFromObj(interp, objv[2], &y);
- if (error != TCL_OK) return error;
-
- result = pow(x,y);
- resultptr = Tcl_GetObjResult(interp);
- Tcl_SetDoubleObj(resultptr,result);
- return TCL_OK;
-}
-
-</pre></blockquote>
-To make this new command available to Tcl, you also need to write an initialization function such as follows:<p>
-<p>
-<blockquote><pre>int
-Example_Init(Tcl_Interp *interp) {
- Tcl_CreateObjCommand(interp, "pow", PowObjCmd,
- (ClientData) NULL, (Tcl_CmdDeleteProc *) NULL);
- return TCL_OK;
-}
-
-</pre></blockquote>
-Finally, to build the Tcl extension, these functions (and the original C functions) are compiled into an extension module. In newer versions of Tcl, this is usually done by compiling the extension module into a shared library or DLL that can be dynamically loaded into the Tcl interpreter. In this case, using the module from Tcl might look like this :<p>
-<p>
-<blockquote><pre>tclsh
-% load ./example.so Example
-% pow 2 3
-8.0
-%
-
-</pre></blockquote>
-In cases where dynamic loading is not supported, extension modules can be compiled into the tclsh or wish executable directly (also known as static linking). This is accomplished by writing a <tt>Tcl_AppInit()</tt> function and a <tt>main()</tt> function.<p>
-<p>
-<blockquote><pre>/* main.c */
-#include <tcl.h>
-int Tcl_AppInit(Tcl_Interp *interp);
-
-int main(int argc, char *argv[]) {
- Tcl_Main(argc, argv, Tcl_AppInit);
-}
-int Tcl_AppInit(Tcl_Interp *interp) {
- /* Initialize Tcl */
- if (Tcl_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
- /* Initialize our extension */
- if (Example_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
- return TCL_OK;
-}
-
-</pre></blockquote>
-Although writing a simple Tcl extension may be easy enough, consider the problem of providing a Tcl interface to a large C/C++ library containing hundreds of functions, classes, objects, variables, and constants. In this case, it would be necessary to write hundreds of complicated wrapper functions---a time consuming task to be certain. Not only that, providing a mapping between C and Tcl is further complicated by data representation issues and object management (i.e. how do you manage C/C++ objects, pointers, arrays, etc...). To make matters worse, consider the use of Tcl in a rapidly changing C/C++ application development environment where APIs are evolving, packages might only be partially implemented, and designs are being revised. Needless to say, it is difficult to write and maintain Tcl wrappers in this setting. Given the choice, most developers would rather concentrate on the job at hand--not the task of writing Tcl wrapper code. As a result, the use of Tcl might be ignored entirely or only considered much later in a project (after the code has stabilized).<p>
-<a name="n7"></a><h3> A 30 Second Introduction to SWIG</h3>
-SWIG is a development tool that automates the Tcl extension building process. For example, consider the earlier example of the pow(x,y) function. With SWIG, the Tcl extension can be defined entirely by the following file (by convention these are called "interface files" and are usually given a <tt>.i</tt> suffix) :<p>
-<p>
-<blockquote><pre>
-// example.i : A Simple SWIG interface
-%module example
-%{
-#include <math.h>
-%}
-
-// ANSI C/C++ prototypes
-double pow(double x, double y);
-
-</pre></blockquote>
-In this file, the functionality of the Tcl module is defined entirely with ANSI C prototypes. Instead of writing wrapper code, you only need to list the functions that you want to access. In the first part of the file, the <tt>%module</tt> directive names the extension module. The <tt>%{, %}</tt> section is used to enclose code that should be copied into the output wrapper code (usually this is used to grab the right header files and provide additional support code when needed).<p>
-<p>
-To build the extension, you simply run SWIG on this file to generate the Tcl wrapper code (in this case SWIG creates a file called example_wrap.c). This file is then compiled into a Tcl extension module exactly as before. For example (shown for Linux) :<p>
-<p>
-<blockquote><pre>> swig -tcl8 example.i
-Generating wrappers for Tcl 8.x
-> gcc -fpic -c example_wrap.c
-> gcc -shared example_wrap.o -o example.so -lm
-> tclsh
-% load ./example.so example
-% pow 2 3
-8.0
-%
-
-</pre></blockquote>
-With SWIG, the extension module works exactly as expected--however, you didn't have to know anything about Tcl other than knowing how to compile and link the final extension module. <p>
-<p>
-Unlike normal Tcl extension building, SWIG extensions can be very easy to generate. In the example, you could easily make an interface to the entire <math.h> library by simply copying all of the function prototypes out of the header file and placing them in the interface. If you later wanted to change the Tcl interface, you would simply make these changes to the interface file. The resulting Tcl interface would then be updated when the extension module was recompiled.<p>
-<p>
-At this point, you know about 90% of what you need to know to start using SWIG (and the simple example given here can even be used as a starting point for your own applications). The key thing to keep in mind is that SWIG is entirely automatic and it uses an extended subset of ANSI C syntax. Modules can usually be created by simply massaging existing header files and other sources of ANSI C prototypes. In fact, many users are surprised to find out how easy it can be to build Tcl extensions in this manner (in fact, one early SWIG user was able to wrap the entire OpenGL library into a Tcl module with less than ten minutes of effort!).<p>
-<a name="n2"></a><h2> A Tour of SWIG</h2>
-In this section, I provide a high-level tour of SWIG. This is intended to be a quick overview and not a replacement for the SWIG users manual (which contains all of the gory details). <p>
-<a name="n8"></a><h3> The Design and Implementation of SWIG</h3>
-In a nutshell, SWIG is a special purpose C/C++ compiler. As input, SWIG accepts ANSI C/C++ definitions and translates them into the C wrapper code needed to access that functionality from a variety of scripting languages. SWIG also understands a number of directives that are preceded by a `%'. These directives augment the ANSI C definitions and provide additional information that SWIG uses when generating the wrapper code. Finally, in addition to producing wrapper code, SWIG also generates documentation files (in ASCII, HTML, or LaTeX). <p>
-<p>
-
-SWIG is designed to be extensible with new language modules and documentation methods. In addition to producing wrappers for Tcl, SWIG can be used for interfacing with a variety of other languages including Perl, Python, and Guile (in fact, users have even developed modules for Java and commercial packages such as MATLAB).<p>
-<p>
-SWIG was originally developed at Los Alamos National Laboratory as a development tool for integrating physics applications with scripting languages. With this in mind, there were a number of design goals :<p>
-<p>
-<ul>
-<li>Complete automation. Modules should be completely defined by the input to SWIG and fully functional. In other words, a user should never have to modify SWIG's output.
-<li>Use ANSI C/C++ syntax. This makes SWIG easy to apply to existing software packages because interfaces can be built from header files. The other benefit is that you don't need to learn a special interface definition language to use SWIG--if you know C, then you already know most of SWIG.
-<li>Non-invasive interface building. SWIG attempts to make scripting language interfaces without requiring modifications to the underlying C/C++ code.
-<li>Language independence. Using a common interface specification, SWIG can generate modules for Perl, Python, Guile, and a variety other systems. Different languages are better at different tasks (and everyone seems to have a personal preference). SWIG allows you to keep your options open.
-<li>Adaptability. Given the huge variety of C/C++ coding styles and techniques, SWIG needs to be able to adapt itself to any number of situations. As a result, SWIG provides a variety of customization options as well as the ability to shoot yourself in the foot if necessary. Looking at it another way, SWIG is designed to build scripting interfaces, not legislate morality.
-<li>Extensibility. The SWIG compiler is designed to be extended with new language modules and capabilities. In addition, SWIG includes a standard library that can be used to help in the construction of interfaces and to provide more functionality.
-</ul>
-<p>
-The separation between the interface description and wrapper code is one of SWIG's most important features. First, it allows Tcl to be used with ordinary C/C++ code--in fact, this code doesn't need to know anything about the Tcl interface. Second, this allows for rapid change and development. If the C code changes in some manner, the Tcl interface can be easily regenerated to reflect the new implementation. It is also easy to build a stand-alone C application, switch scripting languages, or even upgrade to newer versions of Tcl (for example, switching from Tcl 7.6 to Tcl 8.0). Finally, SWIG shifts the focus from the development of Tcl wrapper functions to the problem at hand. As a result, it becomes possible to use Tcl in situations where it might otherwise have not been considered.<p>
-<a name="n9"></a><h3> Running SWIG</h3>
-SWIG is invoked using the <tt>swig</tt> command. SWIG operates like a C compiler and accepts a number of options :<p>
-<p>
-<blockquote><pre>swig <options> filename
-
--tcl Generate Tcl 7.x wrappers
--tcl8 Generate Tcl 8.x wrappers
--perl5 Generate Perl5 wrappers
--python Generate Python wrappers
--dascii Produce ASCII documentation
--dhtml Produce HTML documentation
--dlatex Produce LaTeX documentation
--c++ Enable C++ mode
--objc Enable Objective-C mode
--Idir Add a directory to the SWIG search path
--lfile Include a SWIG library file
--o outfile Set the name of the output file
--module name Set the module name
--Dsymbol Define a symbol
--version Display SWIG's version number
--help Display all options
-</pre></blockquote>
-<p>
-This is only a partial list of options. A full listing of options can be obtained by invoking "swig -help".<p>
-<p>
-When given an input file of `<tt>myfile.i</tt>', SWIG will produce an output file of `<tt>myfile_wrap.c</tt>' as well as a documentation file. If necessary, the name of the output file can be changed using the <tt>-o</tt> option (this is sometimes necessary when working with C++ compilers that expect to see a C++ suffix on source files).<p>
-<p>
-Although SWIG can be invoked directly on the command line, most users find it easier to invoke SWIG within a Makefile. A typical Tcl Makefile might look like the following :<p>
-<p>
-<blockquote><pre># Sample Makefile for a Tcl extension
-SRCS = example.c # Source files
-OBJS = # Object files (already created)
-INTERFACE = example.i # SWIG Interface file
-WRAPFILE = $(INTERFACE:.i=_wrap.c)
-WRAPOBJ = $(INTERFACE:.i=_wrap.o)
-TARGET = example.so # Output file
-
-
-# Compiler options
-CC = gcc
-CFLAGS =
-INCLUDE =
-
-# SWIG Options
-SWIG = /usr/local/bin/swig
-SWIGOPT = -tcl # use -tcl8 for Tcl 8.0
-SWIGCC = $(CC)
-
-# Rules for creating .o files from source.
-COBJS = $(SRCS:.c=.o)
-ALLOBJS = $(COBJS) $(OBJS)
-
-# Shared library options (Shown for Linux)
-CCSHARED = -fpic
-BUILD = $(CC) -shared
-
-# Tcl installation (where is Tcl/Tk located)
-TCL_INCLUDE = -I/usr/local/include
-TCL_LIB = -L/usr/local/lib
-
-# Additional link libraries
-LIBS =
-
-.SUFFIXES: .c
-
-.c.o:
- $(CC) $(CCSHARED) $(CFLAGS) $(INCLUDE) -c $<
-
-all: $(TARGET)
-
-# Convert the SWIG wrapper file into an object file
-$(WRAPOBJ) : $(WRAPFILE)
- $(SWIGCC) -c $(CCSHARED) $(CFLAGS) $(WRAPFILE) $(INCLUDE) \
- $(TCL_INCLUDE)
-
-# Run SWIG
-$(WRAPFILE) : $(INTERFACE)
- $(SWIG) $(SWIGOPT) -o $(WRAPFILE) $(INTERFACE)
-
-# Build the final extension module
-$(TARGET): $(WRAPOBJ) $(ALLOBJS)
- $(BUILD) $(WRAPOBJ) $(ALLOBJS) $(LIBS) -o $(TARGET)
-
-</pre></blockquote>
-<p>
-Windows-NT users can invoke SWIG directly from the MS-DOS command shell, from Makefiles, or as a special processing option in whatever development environment that they are using. For example, in Visual C++, you can invoke SWIG in the same manner as you would invoke other code generation tools such as Lex and Yacc. Consult the documentation for your development environment for more details.<p>
-<a name="n10"></a><h3> The Input to SWIG</h3>
-Most interface files have the following format <p>
-<p>
-<blockquote><pre>%module mymodule
-%{
-/* Include header files here */
-#include "myheader.h"
-%}
-// Now list ANSI C declarations
-extern double foo(double);
-...
-</pre></blockquote>
-<p>
-SWIG also includes a preprocessor that can be used for conditional compilation and macro expansion. This can be used to create mixed interface/header files that are acceptable to both SWIG and the C compiler. For example :<p>
-<p>
-<blockquote><pre>/* example.h : A Mixed SWIG/C file */
-
-#ifdef SWIG
-%module example
-%{
-#include "example.h"
-%}
-#endif
-
-#ifdef __STDC__
-#define _ANSI_ARGS(a) a
-#else
-#define _ANSI_ARGS(a) ()
-#endif
-#ifdef __cplusplus
-#define EXTERN extern "C"
-#else
-#define EXTERN extern
-#endif
-
-/* Now declare function prototypes */
-EXTERN double foo _ANSI_ARGS((double));
-...
-</pre></blockquote>
-<p>
-In systems that change alot, this approach makes it easier to maintain consistency between header files and interface specifications (even if header files play preprocessor tricks to address system and compiler dependencies).<p>
-<p>
-For the most part, anything that can be given to a C compiler can also be given to SWIG. However, it is important to understand that SWIG is not a full C/C++ compiler. In some cases, it may get confused by extremely complicated declarations. Other features simply aren't supported--for example, variable length arguments, operator overloading, templates, etc... When in doubt, the best thing to do is try it and see. If SWIG complains, you can either remove the offending declaration, comment it out, or use conditional compilation to hide it. However, the SWIG compiler is always improving so current limitations may be eliminated in the future.<p>
-<a name="n11"></a><h3> The Basic Tcl Interface</h3>
-SWIG attempts to provide a direct mapping between C and Tcl. C functions are turned into new Tcl commands. Global variables are turned into Tcl variables using the variable linking mechanism if possible. Constants are simply turned into read-only Tcl variables. Thus, if you give SWIG the following interface file :<p>
-<p>
-<blockquote><pre>%module
-example
-
-int factorial(int n);
-extern double My_variable;
-#define PI 3.1415926
-const int SPAM = 42;
-...
-
-</pre></blockquote>
-These declarations are accessible in Tcl as follows<p>
-<p>
-<blockquote><pre>% puts [factorial 4] ;# Call a C function
-24
-% set My_variable 3.4 ;# Change a C global variable
-% puts $My_variable ;# Read a C global variable
-3.4
-% puts $PI ;# Output the value of a C constant
-3.1415926
-% puts $SPAM
-42
-%
-
-</pre></blockquote>
-For C global variables, the Tcl interpreter only supports a small subset of C datatypes (int, double, and char *). When other datatypes are used such as the following,<p>
-<p>
-<blockquote><pre>short My_short;
-</pre></blockquote>
-<p>
-SWIG creates a pair of accessor functions as follows :<p>
-<p>
-<blockquote><pre>puts [My_short_get] ;# Get value of a global variable
-My_short_set 5.5 ;# Set value of a global variable
-
-</pre></blockquote>
-<a name="n12"></a><h3> Pointers</h3>
-SWIG supports C/C++ pointers by mapping them into character strings that encode the value and type. For example, a pointer of type "<tt>Vector *</tt>" would look similar to the following in Tcl :<p>
-<p>
-<blockquote><pre>_100f8e2_Vector_p
-
-</pre></blockquote>
-Pointers may appear throughout a SWIG interface file. Furthermore, type definitions are not generally required. For example :<p>
-<blockquote><pre>
-%module vector
-%{
-#include "vector.h"
-%}
-
-Vector *new_vector(double x, double y, double z);
-double dot_product(Vector *a, Vector *b);
-...
-
-</pre></blockquote>
-In Tcl, pointers are opaque objects that can be passed around between different C functions and operate like you would expect. For example :<p>
-<p>
-<blockquote><pre>% set v1 [new_Vector 2 3 4] # Create two vectors
-% set v2 [new_Vector 5 6 7]
-% puts $v1
-_100f8e2_Vector_p
-% dot_product $v1 $v2
-56
-%
-
-</pre></blockquote>
-For the most part, pointers in Tcl work in the same way as they do in C. However, the primary difference is that pointers can't be dereferenced in Tcl. In other words, you can't peer inside objects and manipulate them (well, at least not without a little help).<p>
-<p>
-Interestingly enough, this approach avoids a number of difficult problems related to data representation and working with multiple languages. By supporting pointers, it is not necessary for SWIG or Tcl to understand the underlying implementation of C/C++ objects. In fact, SWIG does not need the definition of complex objects in order to use them. For example, the Vector type was used above, but the definition of Vectors was never specified in the interface file.<p>
-<p>
-Finally, SWIG uses the pointer type-signature to perform type-checking. Whenever a pointer is passed to a C function, its type is checked against an expected value. If a mismatch occurs, the pointer will be rejected and a Tcl error raised. For example :<p>
-<p>
-<blockquote><pre>% set v1 [new_vector 2 3 4]
-% set m [new_matrix 10 10]
-% dot_product $v1 $m
-Type error in argument 2 of dot_product. Expected _Vector_p.
-</pre></blockquote>
-<p>
-With type checking, it is safe to pass pointers around in Tcl much in the same way as would be done in C/C++ (which may be a good or bad thing depending on your point of view--or all bad if you're a language purist). <p>
-<a name="n13"></a><h3> Structures and Classes</h3>
-The SWIG pointer mechanism is a powerful way to manipulate C objects from Tcl. However, you may also want to access the internals of an object. To support this, SWIG can parse C structure definitions and turn them into "accessor" functions. For example,<p>
-<p>
-<blockquote><pre>struct Vector {
- double x,y,z;
-};
-
-</pre></blockquote>
-is translated into the following collection of C functions :<p>
-<p>
-<blockquote><pre>double Vector_x_get(struct Vector *obj) {
- return obj->x;
-}
-double Vector_x_set(struct Vector *obj, double x) {
- return (obj->x = x);
-}
-double Vector_y_get(struct Vector *obj) {
- return obj->y;
-}
-double Vector_y_set(struct Vector *obj, double y) {
- return (obj->y = y);
-}
-double Vector_z_get(struct Vector *obj) {
- return obj->z;
-}
-double Vector_z_set(struct Vector *obj, double z) {
- return (obj->z = z);
-}
-
-</pre></blockquote>
-Accessor functions simply take an object as the first argument and provide a way to manipulate its internal representation from Tcl. For example<p>
-<p>
-<blockquote><pre># v is a Vector that got created somehow
-% Vector_x_get $v
-3.5
-% Vector_x_set $v 7.8 ;# Change x component
-
-</pre></blockquote>
-Similar access is provided for unions and the data members of C++ classes. <p>
-<p>
-For C++ class definitions, the same technique is used to provide access to member functions, constructors, and destructors. For example,<p>
-<blockquote><pre>
-class List {
-public:
- List();
- ~List();
- int search(char *item);
- void insert(char *item);
- void remove(char *item);
- char *get(int n);
- int length;
-static void print(List *l);
-};
-</pre></blockquote>
-<p>
-is translated into the following functions :<p>
-<p>
-<blockquote><pre>List *new_List() {
- return new List;
-};
-void delete_List(List *l) {
- delete l;
-}
-int List_search(List *l, char *item) {
- return l->search(item);
-}
-void List_insert(List *l, char *item) {
- l->insert(item);
-}
-void List_remove(List *l, char *item) {
- l->remove(item);
-}
-char *List_get(List *l, int n) {
- return l->get(n);
-}
-int List_length_get(List *l) {
- return l->length;
-}
-int List_length_set(List *l, int n) {
- return (l->length = n);
-}
-void List_print(List *l) {
- List::print(l);
-}
-
-</pre></blockquote>
-Within Tcl, you can use the functions as follows :<p>
-<blockquote><pre>
-% set l [new_List]
-% List_insert $l Ale
-% List_insert $l Stout
-% List_insert $l Lager
-% List_print $l
-Lager
-Stout
-Ale
-% puts [List_length_get $l]
-3
-% puts $l
-_1008560_List_p
-%
-
-</pre></blockquote>
-<p>
-While somewhat primitive, the low-level SWIG interface provides direct and flexible access to almost any C++ object. As it turns out, it is not necessary to provide SWIG with the complete definition of a structure or class. Access can be restricted by only providing a limited definition (or no definition at all). <p>
-<p>
-For C++, SWIG also supports inheritance (including multiple inheritance). Inheritance hierarchies are encoded into the run-time pointer type-checker and work as you would expect. For example, suppose you had the following classes :<p>
-<p>
-<blockquote><pre>class Shape {
-public:
- virtual double area() = 0;
- virtual double perimeter() = 0;
-};
-
-class Circle : public Shape {
-public:
- Circle(double radius);
- ~Circle();
- double area();
- double perimeter();
-};
-
-class Square : public Shape {
-public:
- Square(double width);
- ~Square();
- double area();
- double perimeter();
-};
-
-</pre></blockquote>
-In the Tcl interface, "Circle" and "Square" objects would be accepted any place a "Shape" is expected. However, the type system does not allow situations that are illegal (or problematic) in C++. For example :<p>
-<p>
-<blockquote><pre>tclsh
-% set c [new_Circle 4] ;# Create a circle
-% set s [new_Square 10] ;# Create a square
-% Square_area $a ;# Use derived class
-100.0
-% Shape_area $s ;# Use base class
-100.0
-% Shape_perimeter $c
-25.1327412287
-% Square_area $c # Try to violate the type system
-Type error in argument 1 of Square_area. Expected _Square_p.
-
-</pre></blockquote>
-<a name="n14"></a><h3> The Object Interface</h3>
-Although SWIG turns structures and classes into accessor functions, an optional object-oriented interface is also available. This interface allows C/C++ objects to appear like Tcl objects (or Tk widgets). As an example, consider the List class mentioned in the previous section. Using the optional object interface, you could write the following Tcl code<p>
-<p>
-<blockquote><pre>% List l ;# Create a new list
-% l insert Ale ;# Invoke some member functions
-% l insert Stout
-% l insert Lager
-% List_print [l cget -this]
-Lager
-Stout
-Ale
-% puts [l cget -length] ;# Get the length
-3
-% puts [l cget -this] ;# Get the `this' pointer
-_1008560_List_p
-% rename l "" ;# Delete l
-
-</pre></blockquote>
-For many users, this provides a much more natural interface to C/C++ objects. It also looks rather familiar to what is done in Tcl extensions such as [incr Tcl]. Even though this interface provides an alternative mechanism for managing objects, it is still closely related to the pointer handling mechanism already described. In particular, it may be necessary to extract a pointer value from a Tcl object. This can be done by extracting the `this' value from an object as follows:<p>
-<p>
-<blockquote><pre>set t [l cget -this] # Extract the pointer value
-
-</pre></blockquote>
-In other cases, it may be useful to turn an existing pointer into a Tcl object. This can be done as follows :<p>
-<p>
-<blockquote><pre>List l -this $t # Turn a pointer into an object
-
-</pre></blockquote>
-<p>
-Although the object interface provides a "natural" interface to objects, it also has a number of limitations. First, it can result in a substantial amount of additional wrapper code. If wrapping hundreds of structures and classes, the size of the module created by SWIG can be quite large. If this is a concern, the object interface can be disabled by running SWIG with the `<tt>-noobject</tt>' option. Second, SWIG does not make Tcl object-oriented in the same sense as extensions such as [incr Tcl]. For example, you would not be able to inherit from objects wrapped by SWIG. Finally, the object interface can be awkward to use in combination with functions expecting pointers since you will need to convert back and forth between object model and the pointer model. Although this interface won't be described much further, all of the gory details can be found in the SWIG Users Manual.<p>
-<a name="n15"></a><h3> Renaming</h3>
-Sometimes the contents of a C/C++ library will generate a namespace clash with existing Tcl keywords and commands. To resolve these conflicts, SWIG provides the <tt>%name</tt> directive. For example :<p>
-<p>
-<blockquote><pre>%module example
-...
-%name(mylindex) int lindex();
-...
-%name(clist) class list {
-public:
- ...
-};
-
-</pre></blockquote>
-<tt>%name</tt> simply changes the name of a command, class, or member function when used in Tcl (it has no effect on the underlying C code).<p>
-<a name="n16"></a><h3> Read-only variables</h3>
-To restrict access to global variables and data members of structures, SWIG provides the <tt>%readonly</tt> and <tt>%readwrite</tt> directives. For example :<p>
-<p>
-<blockquote><pre>%readonly
-double foo; // foo will be read-only
-int bar; // bar will be read-only
-%readwrite
-int spam = 42; // spam is read-write
-
-class List {
-public:
-...
-%readonly
- int length; // length will be readonly
-%readwrite
-...
-};
-
-</pre></blockquote>
-Read-only mode stays in effect until it is explicitly disabled with the <tt>%readwrite</tt> directive.<p>
-<a name="n17"></a><h3> File Inclusion and the SWIG Library</h3>
-SWIG provides an <tt>%include</tt> directive that can be used to break up interfaces into multiple files. For example, if you were creating an interface to a large package, you might write an interface like this :<p>
-<p>
-<blockquote><pre>// Interface to OpenGL
-%module opengl
-
-// Include a variety of pieces
-%include gl.i
-%include glu.i
-%include "GL/gluaux.h"
-%include "test.c"
-
-</pre></blockquote>
-The other use of <tt>%include</tt> is to retrieve files from the SWIG library--a repository of common modules and extensions that is packaged with the SWIG distribution. For example, if you wanted to relink the <tt>tclsh</tt> interpreter with a SWIG extension added to it, you can do this :<p>
-<p>
-<blockquote><pre>%module example
-%{
-#include "myheader.h"
-%}
-%include tclsh.i // Include Tcl_AppInit() code for tclsh
-
-// C declarations
-
-</pre></blockquote>
-In this case, the library file provides all of the additional support code (<tt>Tcl_AppInit(), main()</tt>, etc...) needed to build a new version of <tt>tclsh</tt>.<p>
-<p>
-Library files can also be included on the command line using the <tt>-l</tt> option. For example :<p>
-<p>
-<blockquote><pre>% swig -tcl8 -lwish.i example.i
-</pre></blockquote>
-<p>
-When files are included in this manner, they are appended to the end of the SWIG input file (i.e. files included on the command line are parsed last).<p>
-<a name="n18"></a><h3> Code Insertion</h3>
-Sometimes it is useful to insert support code into the resulting wrapper file generated by SWIG. The wrapper file produced by SWIG consists of three sections---a header section containing declarations that must appear before any wrapper functions, a wrapper code section containing the actual Tcl wrapper functions, and an initialization function that registers the module's functionality with Tcl.<p>
-<p>
-<p>
-Code can be inserted into the header section by enclosing it with %{, %} (these are also known as code blocks). We have already seen this used to include the right header files. However, you can also include supporting C functions. For example :<p>
-<blockquote><pre>
-%module mymodule
-%{
-#include "my_header.h"
-%}
-
-... Declare C functions here
-
-// Now include a Tcl_AppInit function (note: the tclsh.i library file
-// does the same thing).
-%{
-int main(int argc, char **argv) {
- Tcl_Main(argc, argv, Tcl_AppInit);
- return(0);
-}
-
-int Tcl_AppInit(Tcl_Interp *interp){
- int Mymodule_Init(Tcl_Interp *);
-
- if (Tcl_Init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- /* Now initialize our functions */
- if (Mymodule_Init(interp) == TCL_ERROR)
- return TCL_ERROR;
- return TCL_OK;
-}
-%}
-</pre></blockquote>
-<p>
-Code blocks are also sometimes used to write helper functions. These are C functions that you want to include in the Tcl interface, but might not be part of the original C library or package. For example :<p>
-<p>
-<blockquote><pre>// Include a support function in our module
-%{
-/* Create a new vector */
-static Vector *new_Vector() {
- return (Vector *) malloc(sizeof(Vector));
-}
-%}
-
-// Now tell SWIG about it.
-Vector *new_Vector();
-
-</pre></blockquote>
-Since writing helper functions is relatively common, a shorthand form of the above is available using the <tt>%inline</tt> directive 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 is really just a convenient way to write new C/C++ functions that you would like to include in your Tcl interface.<p>
-<p>
-If you want to insert code into the module initialization function, you can do the following :<p>
-<p>
-<blockquote><pre>%init %{
- init_module(); // Perform module-specific initialization
-%}
-</pre></blockquote>
-<p>
-This code will be executed when Tcl loads or initializes your extension module and can be used to initialize your application.<p>
-<p>
-Finally, there is a <tt>%wrapper</tt> directive for including code into the wrapper section of SWIG's output. This is rarely used (or necessary) but is available for special cases.<p>
-<a name="n19"></a><h3> Structure and Class Extension</h3>
-The object-oriented interface provides a nice way to manipulate C structures and C++ classes. However, in some cases, you may want to extend structures and classes. For example, suppose you wanted to manipulate the following C structure from Tcl :<p>
-<p>
-<blockquote><pre>struct Vector {
- double x, y, z;
-};
-
-</pre></blockquote>
-As is, there is no way to create, destroy, or look at Vectors in a convenient manner. However, with SWIG, you can extend the Vector class with some new methods as follows :<p>
-<p>
-<blockquote><pre>%module vector
-%{
-#include "vector.h"
-%}
-
-struct Vector {
- double x,y,z;
-};
-
-// Now extend the Vector structure with some methods
-%addmethods Vector {
- // Create a new vector
- Vector(double x, double y, double z) {
- Vector *v = (Vector *) malloc(sizeof(Vector));
- v->x = x;
- v->y = y;
- v->z = z;
- return z;
- }
- // Destroy a vector
- ~Vector() {
- free(self);
- }
- // Print out a vector for debugging
- void output() {
- printf("[ %g, %g, %g ]\n", self->x, self->y, self->z);
- }
-};
-
-</pre></blockquote>
-Now, in Tcl, you can do the following :<p>
-<p>
-<blockquote><pre>% Vector v 2 5.5 -9 ; # Create a new vector
-% v output ; # Output it's value
-[ 2, 5.5, -9 ]
-% rename v "" ; # Destroy v (calls the destructor)
-</pre></blockquote>
-<p>
-Thus, with just a little work, you can turn a C structure into something that looks alot like a C++ object with constructors, destructors, and methods. However, this is done without modifying the original C structure or requiring a C++ compiler.<p>
-<p>
-Just as C structures can be extended, C++ classes can also be extended with new methods. The extension process does not modify the original class nor does it rely upon C++ inheritance. <p>
-<a name="n20"></a><h3> Exception Handling</h3>
-In some C/C++ applications it may be useful to catch errors and translate them into Tcl errors. This can be done using the <tt>%except</tt> directive. For example :<p>
-<p>
-<blockquote><pre>// Code for catching a C++ exception
-%except(tcl) {
- try {
- $function // The real function call is placed here
- } catch (RangeError) {
- interp->result = "Out of bounds.";
- return TCL_ERROR;
- }
-}
-
-</pre></blockquote>
-The code you supply is inserted directly into the wrapper code created by SWIG. The `$function' token is simply a placeholder for the actual C/C++ function call. The exception handler remains in effect under it is redefined or disabled. Exceptions can be disabled by simply omitting the code. For example :<p>
-<p>
-<blockquote><pre> %except(tcl);
-
-</pre></blockquote>
-<p>
-Exception handling is not limited to C++ exceptions or any particular error handling mechanism. Essentially any valid C/C++ code for checking errors can be used with the <tt>%except</tt> directive.<p>
-<p>
-SWIG also provides an exception handling library, <tt>exception.i</tt>, that can be used to handle exceptions in a language-neutral manner. For example :<p>
-<p>
-<blockquote><pre>// Include the SWIG exception handling library
-%include exception.i
-// Specify a generic exception handler (works with all target languages)
-%except {
- try {
- $function
- } catch (RangeError) {
- SWIG_exception(SWIG_RuntimeError, "Range Error");
- }
-}
-
-</pre></blockquote>
-The benefit of using the exception library is that exception handlers can be easily written once and used by all of the target scripting languages supported by SWIG.<p>
-<a name="n21"></a><h3> Typemaps</h3>
-Most of SWIG's internal processing is driven by the handling of C datatypes--in particular, rules for converting C datatypes to and from Tcl (and other scripting languages). For example, when SWIG encounters an "int", it needs to know how to convert an integer from Tcl to C, return an integer result to Tcl, link to integer variables, and so forth. By default, SWIG already knows how to perform these simple conversions as well as mapping complex objects into pointers.<p>
-<p>
-For most users, the default behavior is enough to get started. However, in some cases, it may be useful to change SWIG's handling of a particular datatype (by adding special processing or mapping a datatype into Tcl in a different manner). To support this, SWIG provides a customization mechanism known as "typemaps." In a nutshell, a typemap is a special processing rule that is attached to particular C/C++ datatypes. The following example shows a very simple typemap in action :<p>
-<p>
-<blockquote><pre>%module example
-
-// Typemap for converting Tcl8 integers to C integers
-// $source is the Tcl input object
-// $target is the C variable (an int).
-%typemap(tcl8,in) int {
- int error = Tcl_GetDoubleFromObj(interp, $source, &$target);
- if (error != TCL_OK) return error;
- printf("Received : %d\n", $target);
-}
-...
-extern int fact(int n);
-
-</pre></blockquote>
-When this example is compiled into a Tcl 8 module, it will operate as follows :<p>
-<p>
-<blockquote><pre>% fact 6
-Received : 6
-720
-%
-</pre></blockquote>
-<p>
-In this case, the C code used for converting integers from Tcl to C has been changed. <p>
-<p>
-Typemaps can also be applied to named datatypes such as function arguments. For example :<p>
-<p>
-<blockquote><pre>%module example
-%include exception.i
-// Typemap for checking the value of an input argument
-// (this is done after it has been converted from Tcl to C)
-%typemap(tcl8,check) double positive {
- if ($source <= 0) {
- SWIG_exception(SWIG_ValueError, "Expected a positive value");
- }
-}
-
-double log10(double positive);
-double exp(double);
-
-</pre></blockquote>
-In this case, the typemap is only applied to function arguments that exactly match "double positive". Thus, from Tcl, these functions would operate as follows :<p>
-<p>
-<blockquote><pre>% log10 2
-0.301029996554
-% exp -1
-0.367879441171
-% log -1
-Expected a positive value!
-%
-</pre></blockquote>
-<p>
-Typemaps are applied using a simple name-based pattern matching rule. When a typemap for `<tt>int</tt>' is given, it will be applied to all future occurrences of `<tt>int</tt>'. When a typemap for `<tt>double positive</tt>' is given, it will only be applied to arguments that match `<tt>double positive</tt>' (it would not be applied to other uses of `<tt>double</tt>'). However, it is possible to apply existing typemap rules to other datatypes using the <tt>%apply</tt> directive. For example :<p>
-<p>
-<blockquote><pre>%module example
-%include exception.i
-// Typemap for checking the value of an input argument
-// (this is done after it has been converted from Tcl to C)
-%typemap(tcl8,check) double positive {
- if ($source <= 0) {
- SWIG_exception(SWIG_ValueError,"Expected a positive value");
- }
-}
-
-// Now apply this typemap to some other datatypes
-%apply double positive { double px, Real positive };
-
-double log10(double px); // Only accepts positive values
-
-typedef double Real;
-Real log(Real positive); // Only accepts positive values
-...
-
-</pre></blockquote>
-At first glance, the specification of a typemap may look like a horrid mess (which is probably true), but there is a method behind the madness. Typemaps have four essential pieces that are specified as follows :<p>
-<p>
-<blockquote><pre>%typemap(lang, method) type [name] [,type2 [name],type3 [name],...] {
- Conversion Code
-}
-</pre></blockquote>
-<tt>lang</tt> explicitly specifies the target scripting language. Typemaps for any of the target scripting languages can appear at any time in SWIG's input. However, only those matching the current target language will ever be used. <tt>method</tt> specifies the name of a particular type conversion. There are many different types of conversions, but some of the more common ones are as follows<p>
-<p>
-<blockquote><pre>in - Convert function arguments from Tcl to C.
-out - Convert function result from C to Tcl.
-argout - Convert a result returned in an argument from C to Tcl.
-default - Default argument value
-check - Checks the value of an input argument.
-ret - Clean up the return result of a function
-ignore - Tell SWIG to ignore a function argument.
-
-</pre></blockquote>
-<tt>type</tt> and <tt>name</tt> specify the C/C++ datatype that the typemap conversion is being given for. Additional datatypes can also be given as a comma separated list. Finally, the C/C++ conversion code is given in braces. Within the conversion code, a number of special placeholders can be included (this is only a partial list) :<p>
-<p>
-<blockquote><pre>$source - The original value (before conversion)
-$target - The result of a data conversion
-$type - The C datatype used in the typemap
-</pre></blockquote>
-<p>
-The placeholders get filled in by appropriate values when SWIG generates wrapper code.Thus, a more complicated typemap specification might look like this :<p>
-<p>
-<blockquote><pre>// Convert a variety of integer types from Tcl to C
-%typemap(tcl8,in) int,
- short,
- long,
- unsigned,
- unsigned short,
- unsigned long
-{
- int temp;
- if (Tcl_GetIntFromObj(interp, $source, &temp) == TCL_ERROR) {
- return TCL_ERROR;
- $target = ($type) temp;
-}
-</pre></blockquote>
-<p>
-At this point, assuming that you're not completely confused, you may be wondering how the typemap system is really intended to work. Although many of the details about typemaps have been omitted here, the underlying idea behind typemaps is that you can specify special processing rules in advance and use them in an interface by simply following a naming convention. For example, if you wanted to wrap the C math library with some added error checking, it might look like this :<p>
-<p>
-<blockquote><pre>%module math
-%{
-#include <math.h>
-%}
-
-typemap(tcl8,check) double positive { ... }
-typemap(tcl8,check) double nonnegative { ... }
-typemap(tcl8,check) double nonzero { ... }
-
-...
-// Now list ANSI C declarations
-double sin(double);
-double cos(double);
-double log(double positive);
-double log10(double positive);
-double sqrt(double nonnegative);
-
-</pre></blockquote>
-When working with mixed SWIG/C header files, this arrangement allows a file to be acceptable to both SWIG and the C compiler (provided that the SWIG directives are conditionally compiled of course). It also encourages header files and interface specifications to use a consistent naming scheme for different types of function arguments.<p>
-<a name="n22"></a><h3> Extensive information about typemaps is provided in the SWIG Users Manual. For the purposes of this chapter, you should know that typemaps exist and that they are often used behind the scenes to perform many magical tasks. As it turns out, a number of useful typemaps are included in the SWIG library---sparing you the trouble of writing them by hand (but, more about that in a little bit).</h3>
-<a name="n3"></a><h2> Using SWIG</h2>
-Now that you've had a quick tour of the SWIG compiler, it's time to start using it. This section describes some of the techniques (and tricks) that are commonly used to build Tcl interfaces to C/C++ code. Rather than attempting to cover every possible situation, this section covers many of the most common problems and solutions. However, given the flexibility that SWIG provides, there is usually more than one way to do it (just something to keep in mind)<p>
-<a name="n23"></a><h3> Preparing to SWIG</h3>
-Using SWIG generally involves the following steps:<p>
-<p>
-<ul>
-<li>Grab a header file.
-<li>Turn the header file into a SWIG interface file and tweak it if necessary.
-<li>Run SWIG and make a Tcl interface.
-</ul>
-<p>
-<p>
-In addition to preparing an input file, you may need to eliminate the <tt>main()</tt> function from the original C/C++ application. Scripting languages provide their own main() that will be used instead. To eliminate <tt>main()</tt>, you can either omit it when you compile the C code or simply redefine the symbol such as <p>
-<p>
-<blockquote><pre>% cc -c -Dmain=mymain main.c
-
-</pre></blockquote>
-Finally, SWIG is not a full C/C++ compiler and may not support certain features. SWIG will report compilation problems in these cases. To eliminate the problems, you may have to tweak the SWIG input file somewhat. For example :<p>
-<p>
-<blockquote><pre>#ifndef SWIG
-int printf(char *fmt, ...); // varags not supported by SWIG
-#else
-
-</pre></blockquote>
-<a name="n24"></a><h3> Interface Building Considerations</h3>
-Many users are surprised to find out how easy it is to use SWIG. However, this doesn't mean that you will get a good Tcl interface on the first try. In fact, there are a few things to keep in mind<p>
-<p>
-<ul>
-<li>SWIG may generate an interface that is awkward or unusable. This can be avoided, but it may require a little more work (stay tuned).
-<li>It is often unnecessary to wrap everything in a huge library. If you are only interested in a small subset of a library, it may make more sense to simply wrap those pieces.
-<li>Not all C declarations can be effectively translated into a scripting environment. For example, pointers to functions and C++ templates may not make much sense when working with Tcl. Although it is certainly possible to handle such situations, it may require a little more work.
-<li>SWIG is not a substitute for design. Generally speaking, you will get better results by thinking about the Tcl user interface to your C/C++ libraries in advance. However, one of SWIG's most powerful features is its ability to attach to existing code--regardless of the existing design (for better or for worse).
-<li>SWIG may not be appropriate for every Tcl/Tk project. For example, you probably wouldn't write a Tk widget using SWIG. If calling Tcl/Tk from C is your game, you might have better luck using a tool such as ET. Likewise, a variety of object-oriented Tcl extensions are available that may be better suited to certain applications. In other words, your mileage will vary.
-</ul>
-<a name="n25"></a><h3> Creating and Destroying Simple Objects</h3>
-Sometimes it is necessary to manufacture various C/C++ objects from a Tcl interface. In C, objects are easily constructed using malloc() or new, but Tcl needs a little extra help. Thus, object creation and destruction often requires the use of helper functions. For example :<p>
-<p>
-<blockquote><pre>%module example
-%{
-#include "vector.h"
-%}
-
-// Now define some helper functions for creating/destroying vectors
-%inline %{
-Vector *new_Vector(double x, double y, double z) {
- Vector *v = (Vector *) malloc(sizeof(Vector));
- v->x = x;
- v->y = y;
- v->z = z;
- return v;
-}
-
-void delete_Vector(Vector *v) {
- free(v);
-}
-%}
-
-</pre></blockquote>
-An alternative approach to writing helper functions is to explicitly specify C++ constructors and destructors in the interface file. For example :<p>
-<p>
-<blockquote><pre>%module
-%{
-#include "vector.h"
-%}
-
-struct Vector {
- Vector();
- ~Vector();
- double x,y,z;
-};
-
-</pre></blockquote>
-This approach works from both C and C++. In the case of ANSI C, SWIG will simply create constructor and destructor functions that are mapped onto <tt>malloc()</tt> and <tt>free()</tt>.<p>
-<a name="n26"></a><h3> Arrays</h3>
-Manipulating arrays is common practice in many C applications. C arrays can also be handled through the use of helper functions. For example :<p>
-<p>
-<blockquote><pre>// SWIG helper functions for arrays
-%inline %{
-/* Create an array */
-double *double_array(int size) {
- return (double *) malloc(size*sizeof(double));
-}
-
-/* Get a value from an array */
-double double_get(double *a, int index) {
- return a[index];
-}
-/* Set a value in the array */
-double double_set(double *a, int index, double value) {
- return (a[index] = value);
-}
-%}
-%name(double_destroy) void free(void *);
-
-</pre></blockquote>
-From Tcl, these functions would be called explicitly :<p>
-<p>
-<blockquote><pre>% set d [array_double 100] ;# Create 100 doubles
-% puts $d
-_10045f8_double_p
-% for {set i 0} {$i < 100} {incr i} {
- double_set $d $i $i ;# Set a value
-}
-% puts [double_get $d 50] ;# Get a value
-50.0
-% double_destroy $d ;# Destroy the array
-
-</pre></blockquote>
-In this case, the array is simply managed as a pointer that can be passed around to any C function that accepts a double *. Generally speaking, this is a good approach if you are working with very large C arrays since they can be created and passed around without any data copying.<p>
-<p>
-SWIG provides a library file <tt>array.i</tt> that contains helper functions for <tt>int</tt>, <tt>float</tt>, <tt>double</tt>, and <tt>char *</tt> datatypes. To use this library, simply place the `<tt>%include array.i</tt>' directive into your interface file.<p>
-<p>
-A common question that arises with arrays is "can I convert a Tcl list into a C array?" Although the pointer model is adequate for many situations, it may make more sense to work with Tcl lists in certain cases. There are a couple of ways to handle this. First, you can write functions in Tcl to convert a list to a pointer. For example :<p>
-<p>
-<blockquote><pre># Tcl functions for converting a Tcl list to a C array
-proc DoubleListToArray {l} {
- set length [llength $l]
- set a [double_array $length]
- set i 0
- foreach item $l {
- double_set $a $i $item
- incr i 1
- }
- return a
-}
-
-</pre></blockquote>
-Within a Tcl script, you would now do the following :<p>
-<p>
-<blockquote><pre>set a [DoubleListToArray {2.3 4.5 0.5 -13.0}] ;# Create an array
-foo $a ;# Call a C function
-double_destroy $a
-
-</pre></blockquote>
-Alternatively, it is possible to use typemaps as a conversion mechanism. For example :<p>
-<p>
-<blockquote><pre>%typemap(tcl,in) double [ANY] (double temp[$dim0]) {
- char **items;
- int itemc,i;
- if (Tcl_SplitList(interp,$source,&itemc,&items) == TCL_ERROR) {
- return TCL_ERROR;
- }
- if (itemc != $dim0) {
- interp->result = "Array size mismatch!";
- free(items);
- return TCL_ERROR;
- }
- for (i = 0; i < itemc; i++) {
- temp[i] = atof(items[i]);
- }
- $target = temp;
- free(items);
-}
-
-</pre></blockquote>
-Although this might take a little time to digest (considering our limited discussion of typemaps), when given a C function such as the following,<p>
-<p>
-<blockquote><pre>void foo (double a[4]);
-
-</pre></blockquote>
-the typemap makes it possible for the function to be called from Tcl as follows :<p>
-<p>
-<blockquote><pre>foo { 2.3 4.5 0.5 -1.30 }
-
-</pre></blockquote>
-If the list passed to the function does not match the C array size, an error will be generated. Needless to say, there are a variety of ways to manage arrays depending on the problem at hand and your personal preference.<p>
-<a name="n27"></a><h3> Output Arguments</h3>
-Sometimes C functions return results in one of their arguments such as follows :<p>
-<p>
-<blockquote><pre>void add(double a, double b, double *result) {
- *c = a+b;
-}
-
-</pre></blockquote>
-The output argument makes this a little tricky to handle from Tcl, but there are several techniques. That can be used. One approach is to write functions that manufacture a `double' and pass it to the C function. For example :<p>
-<p>
-<blockquote><pre>%inline %{
-double *create_double(double val) {
- double *d = (double *) malloc(sizeof(double));
- *d = val;
- return d;
-}
-double get_double(double *d) {
- return *d;
-}
-double set_double(double *d, double val) {
- return (*d = val);
-}
-%}
-
-</pre></blockquote>
-Now, from Tcl, you would do this :<p>
-<p>
-<blockquote><pre>% set result [create_double 0.0]
-% add 4.5 9 $result ; Call our C function
-% puts [get_double $result]
-13.5
-%
-</pre></blockquote>
-<p>
-If working with C built-in datatypes, it may be easier to use the SWIG pointer library by including the file `<tt>pointer.i</tt>' in your interface. The pointer library adds several new functions for manipulating pointers to various built-in datatypes and can be used as follows :<p>
-<p>
-<blockquote><pre>% set result [ptrcreate double] ; # Create a double
-% add 4.5 9 $result
-% puts [ptrvalue $result] ; # Dereference the result
-13.5
-% ptrfree $result
-
-</pre></blockquote>
-Finally, simple output arguments can be handled through the use of typemaps. This can be done by including the file `<tt>typemaps.i</tt>' in your interface. For example :<p>
-<p>
-<blockquote><pre>%module example
-%include typemaps.i
-
-// Apply an output rule to the output argument
-%apply double *OUTPUT { double *result };
-
-// Now declare the function
-void add(double a, double b, double *result);
-
-</pre></blockquote>
-Now, the function operates as follows :<p>
-<p>
-<blockquote><pre>% set result [add 4.5 9]
-% puts $result
-13.5
-%
-
-</pre></blockquote>
-<a name="n28"></a><h3> Wrapping Preprocessor Macros</h3>
-Many C programs use macros instead of function calls to perform some operation. For example :<p>
-<p>
-<blockquote><pre>#define Image_width(im) (im->xpixels)
-
-</pre></blockquote>
-SWIG is unable to create Tcl wrappers for macros because there is no type information available. However, you can create a wrapper by simply giving SWIG a function prototype.<p>
-<p>
-<blockquote><pre>%module example
-%{
-#include "header.h"
-%}
-// A wrapper for a C macro
-unsigned Image_width(Image *im);
-
-</pre></blockquote>
-The prototype gives SWIG the type information it needs to generate a wrapper. Otherwise, the fact that the "function" is really a macro doesn't matter.<p>
-<a name="n29"></a><h3> Overloading</h3>
-As of this writing, SWIG does not support C++ overloading of functions or operators. To resolve overloaded functions, the <tt>%name()</tt> directive can be used. For example :<p>
-<p>
-<blockquote><pre>class foo {
-public:
- foo();
-%name(copy_foo) foo(foo &f);
- ...
-};
-</pre></blockquote>
-<p>
-Overloaded operators can be handled by writing helper functions. For example :<p>
-<p>
-<blockquote><pre>%inline %{
-Vector vector_add(Vector &a, Vector &b) {
- return a+b;
-}
-%}
-</pre></blockquote>
-<p>
-However, the use of operators from Tcl may result in memory leaks and other problems without some special care. In the above case, SWIG would allocate memory to store the result and return a pointer to Tcl. It would be up to you to explicitly free this memory when you were done with it. <p>
-<p>
-<blockquote><pre>set r [vector_add $v1 $v2] ;# Creates a new vector
-... use it ...
-delete_Vector $r ;# Free the result
-</pre></blockquote>
-<p>
-<a name="n30"></a><h3> Working with other Tcl Extensions</h3>
-Although SWIG generates everything you need to build an interface, it can also be used with other Tcl extensions. If you would like to initialize another Tcl module when your module is loaded, you can write the following :<p>
-<p>
-<blockquote><pre>// Initialize BLT when loaded
-%init %{
- if (Blt_Init(interp) == TCL_ERROR) {
- return TCL_ERROR;
- }
-%}
-
-</pre></blockquote>
-If you have already written some Tcl wrapper functions, these can be added to a SWIG interface using the <tt>%native</tt> directive. For example :<p>
-<p>
-<blockquote><pre>%native(foo) int foo_wrap(Tcl_Interp *, ClientData, int, char **);
-
-</pre></blockquote>
-or simply<p>
-<p>
-<blockquote><pre>%native(foo) foo_wrap;
-
-</pre></blockquote>
-These declarations create a new Tcl command `foo' that is mapped onto the Tcl wrapper function <tt>foo_wrap</tt>.<p>
-<a name="n31"></a><h3> SWIG Preprocessor Magic</h3>
-The SWIG compiler includes a full C preprocessor that can be used in a variety of unusual ways. In fact, the preprocessor can be an extremely useful tool for quickly generating helper functions and other aspects of a Tcl interface. One of the more useful capabilities of the preprocessor is the <tt>%define</tt> directive that lets you define complicated macros. For example, the following interface file could be used to generate a variety of array helper functions<p>
-<p>
-<blockquote><pre>
-// Array access helper functions
-%module array
-
-// Define a macro for creating helper functions
-%define ARRAY(Type,Name)
-%inline %{
-/* Create an array */
-Type * Name ## _array (int size) {
- return (Type *) malloc(sizeof( Type ));
-}
-/* Get an item */
-Type Name ## _get (Type *a, int index) {
- return a[index];
-}
-/* Set an item */
-Type Name ## _set (Type *a, int index, Type value) {
- return (a[index] = value);
-}
-/* Delete the array */
-void Name ## _destroy (Type *a) {
- free(a);
-}
-%}
-%enddef
-
-// Now create a bunch of helper functions
-ARRAY(double,double)
-ARRAY(float,float)
-ARRAY(int,int)
-ARRAY(short,short)
-ARRAY(unsigned int, unsigned)
-ARRAY(long, long)
-ARRAY(struct node, node)
-
-</pre></blockquote>
-Similar techniques can be used to wrap C++ templates and work with other complicated declarations. Of course, it's also possible to confuse yourself.<p>
-<a name="n4"></a><h2> Putting it All Together</h2>
-So far, you have been given a crash course in SWIG and some interface building techniques. In this section, we will build a Tcl interface to a C library, write some scripts, and show how you can use Tcl to interact with the library. In this example, we will use the gd-1.2 library written by Thomas Boutell and available at www.boutell.com. gd is relatively simple and can be used on both Unix and Windows platforms (making it a good example). Furthermore, there are already Tcl interfaces to gd, making it possible to compare to other approaches if you are so inclined.<p>
-<a name="n32"></a><h3> A Brief Introduction to gd</h3>
-gd is a C library that is used to create GIF images. A very simple example in C is as follows :<p>
-<p>
-<blockquote><pre>
-#include <gd.h>
-#include <stdio.h>
-
-int main() {
- gdImagePtr im;
- FILE *out;
- int black, white;
-
- /* Create an image */
- im = gdImageCreate(200,200);
-
- /* Allocate some colors */
- black = gdImageColorAllocate(im,0,0,0);
- white = gdImageColorAllocate(im,255,255,255);
-
- /* Draw a line */
- gdImageLine(im,20,50,180,140,white);
-
- /* Output the image */
- out = fopen("test.gif","wb");
- gdImageGif(im,out);
- fclose(out);
-
- /* Clean up */
- gdImageDestroy(im);
-}
-
-</pre></blockquote>
-A variety of plotting primitives such as lines, circles, boxes, and fonts are also available to make more complicated images.<p>
-<a name="n33"></a><h3> A Simple SWIG interface</h3>
-To build a Tcl interface to gd, we can start with the following interface :<p>
-<p>
-<blockquote><pre>%module gd
-%{
-#include <gd.h>
-%}
-
-// Just grab the gd.h header file
-%include gd.h
-
-// Plus a few file I/O functions (to be explained shortly)
-FILE *fopen(char *filename, char *mode);
-void fclose(FILE *f);
-</pre></blockquote>
-<p>
-Now, you can compile a module (shown for Linux)<p>
-<blockquote><pre>
-% swig -tcl gd.i
-Making wrappers for Tcl
-gd.h : Line 31. Warning. Array member will be read-only.
-gd.h : Line 32. Warning. Array member will be read-only.
-gd.h : Line 33. Warning. Array member will be read-only.
-gd.h : Line 34. Warning. Array member will be read-only.
-gd.h : Line 40. Warning. Array member will be read-only.
-gd.h : Line 41. Warning. Array member will be read-only.
-% gcc -c -fpic gd_wrap.c
-% gcc -shared gd_wrap.o -o gd.so -lgd
-</pre></blockquote>
-<p>
-The warning messages will be explained shortly and can be ignored. Now, you can write a simple Tcl script<p>
-<p>
-<blockquote><pre>load ./gd.so gd
-
-# Create an image
-set im [gdImageCreate 200 200]
-
-# Allocate colors
-set black [gdImageColorAllocate $im 0 0 0]
-set white [gdImageColorAllocate $im 255 255 255]
-
-# Draw a line
-gdImageLine $im 20 50 180 140 $white
-
-# Write the image
-set out [fopen test.gif wb]
-gdImageGif $im $out
-fclose $out
-
-# Clean up
-gdImageDestroy $im
-
-</pre></blockquote>
-In a manner of only a few minutes, we have built a Tcl interface that seems to work.<p>
-<a name="n34"></a><h3> Understanding the Warning Messages</h3>
-The warning messages generated by SWIG were generated from the following data structure :<p>
-<p>
-<blockquote><pre>typedef struct gdImageStruct {
- unsigned char ** pixels;
- int sx;
- int sy;
- int colorsTotal;
- int red[gdMaxColors]; ! Warning
- int green[gdMaxColors]; ! Warning
- int blue[gdMaxColors]; ! Warning
- int open[gdMaxColors]; ! Warning
- int transparent;
- int *polyInts;
- int polyAllocated;
- struct gdImageStruct *brush;
- struct gdImageStruct *tile;
- int brushColorMap[gdMaxColors]; ! Warning
- int tileColorMap[gdMaxColors]; ! Warning
- int styleLength;
- int stylePos;
- int *style;
- int interlace;
-} gdImage;
-</pre></blockquote>
-<p>
-The message "Array member will be read-only" means that SWIG knows how to return the value of an array data member (the value is a pointer to the first element), but does not know how to set the value of the array. From Tcl, you will see the following behavior<p>
-<p>
-<blockquote><pre>% set im [gdImageCreate 200 200]
-_80b51e8_gdImagePtr
-% gdImage_red_get $im ; # Get an array member
-_80b51f8_int_p
-% gdImage_red_set $im 0 ; # Try to change a read-only member
-invalid command name "gdImage_red_set"
-%
-
-</pre></blockquote>
-Although it is not possible to modify array structure members as shown, you could do so using the SWIG pointer library or helper functions. For example,<p>
-<p>
-<blockquote><pre>% swig -tcl -lpointer.i gd.i
-
-</pre></blockquote>
-Now, in Tcl<p>
-<p>
-<blockquote><pre>% set im [gdImageCreate 200 200]
-% gdImageColorAllocate $im 50 200 100
-% gdImageColorAllocate $im 35 210 75
-% set r [gdImage_red_get $im]
-_80b51f8_int_p
-% ptrvalue $r 0 ;# Get r[0]
-50
-% ptrvalue $r 1 ;# Get r[1]
-35
-% ptrset $r 70 1 ;# change r[1]
-% ptrvalue $r 1
-70
-%
-</pre></blockquote>
-Of course, you could also end up shooting yourself in the foot by manipulating things in bizarre ways (SWIG certainly won't stop you from doing this).<p>
-<a name="n35"></a><h3> Working with Files</h3>
-In our simple interface we included two functions to open and close files. A variety of functions in the gd library require the use of a <tt>FILE *</tt> argument such as the following :<p>
-<p>
-<blockquote><pre>gdImagePtr gdImageCreateFromGif(FILE *fd);
-gdImagePtr gdImageCreateFromGd(FILE *in);
-gdImagePtr gdImageCreateFromXbm(FILE *fd);
-void gdImageGif(gdImagePtr im, FILE *out);
-void gdImageGd(gdImagePtr im, FILE *out);
-</pre></blockquote>
-<p>
-An ideal solution would be to use Tcl file handles as <tt>FILE *</tt> arguments. Unfortunately, this requires you to unravel file handles and convert them into the corresponding <tt>FILE *</tt> structure--a task that is not easily accomplished. For the purposes of quickly making an interface, it is often easier to simply include a few supporting functions such as fopen() and fclose(). These functions can be called directly to create files for use with the library. Although files created with these functions are not the same as Tcl file handles, they are still easy to use.<p>
-<a name="n36"></a><h3> Wrapping Macros</h3>
-The gd library provides a collection of macros for accessing various image attributes. Rather than manipulating the C data structure directly, users are advised to use these macros.<p>
-<p>
-<blockquote><pre>#define gdImageSX(im) ((im)->sx)
-#define gdImageSY(im) ((im)->sy)
-#define gdImageColorsTotal(im) ((im)->colorsTotal)
-#define gdImageRed(im, c) ((im)->red[(c)])
-#define gdImageGreen(im, c) ((im)->green[(c)])
-#define gdImageBlue(im, c) ((im)->blue[(c)])
-#define gdImageGetTransparent(im) ((im)->transparent)
-#define gdImageGetInterlaced(im) ((im)->interlace)
-</pre></blockquote>
-<p>
-SWIG won't wrap these macros directly, but you can write some function prototypes to accomplish the same thing. <p>
-<blockquote><pre>
-%module gd
-%{
-#include <gd.h>
-%}
-
-// Just grab the gd.h header file
-%include gd.h
-
-// Clear the previous macro definitions included in gd.h
-#undef gdImageSX
-#undef gdImageSY
-#undef gdImageColorsTotal
-#undef gdImageRed
-#undef gdImageGreen
-#undef gdBlue
-#undef gdImageGetTransparent
-#undef gdImageGetInterlaced
-
-// Provide SWIG with function prototypes for the macros
-int gdImageSX(gdImagePtr im);
-int gdImageSY(gdImagePtr im);
-int gdImageColorsTotal(gdImagePtr im);
-int gdImageRed(gdImagePtr im, int c);
-int gdImageGreen(gdImagePtr im, int c);
-int gdImageBlue(gdImagePtr im, int c);
-int gdImageGetTransparent(gdImagePtr im);
-int gdImageGetInterlaced(gdImagePtr im);
-
-// Plus a few file I/O functions
-FILE *fopen(char *filename, char *mode);
-void fclose(FILE *f);
-
-</pre></blockquote>
-Within Tcl, these macros can now be used just like ordinary functions<p>
-<p>
-<blockquote><pre>% set im [gdImageCreate 200 200]
-% gdImageColorAllocate $im 233 50 40
-% gdImageSX $im
-200
-% gdImageColorsTotal $im
-1
-%
-</pre></blockquote>
-<a name="n37"></a><h3> Wrapping the Fonts</h3>
-gd is packaged with five different fonts that are used with functions such as<p>
-<p>
-<blockquote><pre>void
-gdImageChar(gdImagePtr im, gdFontPtr f, int x, int y, int c, int color);
-</pre></blockquote>
-<p>
-where gdFontPtr is a pointer to a font structure. Each font is defined by a global variable that is defined in a separate header file such as the following :<p>
-<p>
-<blockquote><pre>#ifndef GDFONTS_H
-#define GDFONTS_H 1
-
-/* gdfonts.h: brings in the smaller of the two provided fonts.
- Also link with gdfonts.c. */
-
-#include "gd.h"
-
-/* 6x12 font derived from a public domain font in the X
- distribution. Only contains the 96 standard ascii characters,
- sorry. Feel free to improve on this. */
-
-extern gdFontPtr gdFontSmall;
-
-#endif
-</pre></blockquote>
-<p>
-To make the built-in fonts available to our Tcl interface, you need to make the font pointers available. Since the font header files are fairly simple, this can be done by simply including the header files in our SWIG interface such as follows :<p>
-<p>
-<blockquote><pre>// Make the gd fonts available as read-only variables
-%readonly
-%include "gdfontt.h"
-%include "gdfonts.h"
-%include "gdfontmb.h"
-%include "gdfontl.h"
-%include "gdfontg.h"
-%readwrite
-</pre></blockquote>
-<p>
-The fact that the fonts are global variables presents us with a slight complication. SWIG normally tries to use the Tcl variable linking mechanism, but this only supports the basic datatypes of <tt>double</tt>, <tt>int</tt>, and <tt>char *</tt>. To access other types (including pointers), SWIG generates accessor functions. Thus, in Tcl, these variables are accessed as follows :<p>
-<p>
-<blockquote><pre>% gdFontTiny_get
-_400f695c_gdFontPtr
-% gdImageChar $im [gdFontTiny_get] 20 20 A $white
-
-</pre></blockquote>
-Since this can be a little awkward, it may make more sense to write a simple Tcl script to fix the problem<p>
-<p>
-<blockquote><pre># gdfonts.tcl : Extract the fonts into Tcl variables
-set gdFontTiny [gdFontTiny_get]
-set gdFontSmall [gdFontSmall_get]
-set gdFontMediumBold [gdFontMediumBold_get]
-set gdFontLarge [gdFontLarge_get]
-set gdFontGiant [gdFontGiant_get]
-
-</pre></blockquote>
-Now, you would just write the following :<p>
-<p>
-<blockquote><pre># Simple gd script
-load ./gd.so
-source gdfonts.tcl
-
-set im [gdImageCreate 200 200]
-set black [gdImageColorAllocate $im 0 0 0]
-set white [gdImageColorAllocate $im 255 255 255]
-
-# Draw some text
-gdImageString $im $gdFontLarge 10 50 "Hello World" $white
-
-# Write the image
-set out [fopen test.gif wb]
-gdImageGif $im $out
-fclose $out
-
-# Clean up
-gdImageDestroy $im
-
-</pre></blockquote>
-If writing a little Tcl script to work around the problem isn't your preference, it's also possible to create the variables within the SWIG module. For example :<p>
-<p>
-<blockquote><pre>// Create some Tcl variables for the fontsstartup
-#ifdef SWIGTCL
-%init %{
-{
- char temp[64];
- SWIG_MakePtr(temp, gdFontTiny, "_gdFontPtr");
- Tcl_SetVar(interp,"gdFontTiny",temp,0);
- SWIG_MakePtr(temp, gdFontSmall, "_gdFontPtr");
- Tcl_SetVar(interp,"gdFontSmall",temp,0);
- SWIG_MakePtr(temp, gdFontMediumBold, "_gdFontPtr");
- Tcl_SetVar(interp,"gdFontMediumBold",temp,0);
- SWIG_MakePtr(temp, gdFontLarge, "_gdFontPtr");
- Tcl_SetVar(interp,"gdFontLarge",temp,0);
- SWIG_MakePtr(temp, gdFontGiant, "_gdFontPtr");
- Tcl_SetVar(interp,"gdFontGiant",temp,0);
-}
-%}
-#endif
-
-</pre></blockquote>
-<tt>SWIG_MakePtr()</tt> is a function SWIG uses to create pointer variables. Since this approach would only work with Tcl, conditional compilation is used to make sure this code isn't included when producing interfaces for other languages (<tt>SWIGTCL</tt> is a symbol defined by SWIG when it is running in Tcl mode). <p>
-<a name="n38"></a><h3> Creating Points</h3>
-Finally, the gd library contains a few functions for drawing polygons such as <p>
-<p>
-<blockquote><pre>void gdImagePolygon(gdImagePtr im, gdPointPtr p, int n, int c);
-void gdImageFilledPolygon(gdImagePtr im, gdPointPtr p, int n, int c);
-
-</pre></blockquote>
-These functions require an array of points to be passed as the second argument. Points are defined by the following structure :<p>
-<p>
-<blockquote><pre>typedef struct {
- int x, y;
-} gdPoint, *gdPointPtr;
-
-</pre></blockquote>
-As is, our Tcl interface has no mechanism for creating arrays of points so we will need to provide some helper functions for this. Here's one way to do it<p>
-<p>
-<blockquote><pre>// Helper functions for points
-%inline %{
- gdPoint *new_points(int npoints) {
- return (gdPoint *) malloc(npoints*sizeof(gdPoint));
- }
- void delete_points(gdPoint *p) {
- free(p);
- }
- void set_point(gdPoint *p, int n, int x, int y) {
- p[n].x = x;
- p[n].y = y;
- }
-%}
-
-</pre></blockquote>
-From Tcl, points can now be created and manipulated as follows :<p>
-<p>
-<blockquote><pre># Create an array of points
-set p [new_points 4]
-set_point $p 0 10 20
-set_point $p 1 150 30
-set_point $p 2 95 150
-set_point $p 3 20 70
-
-# Draw a polygon
-gdImagePolygon $im $p 4 $white
-
-# Delete the points
-delete_points $p
-
-</pre></blockquote>
-<a name="n39"></a><h3> Using the Module</h3>
-With a just a little work, the gd module is now fully functional and ready to be used. From Tcl, you can interactively play with library and test out its various functions. In fact you can even write a simple Tk script to watch the output file and display images in a canvas. For example :<p>
-<p>
-<blockquote><pre># watchgif.tcl : Periodically poll a file and display in the canvas
-set atime ""
-set canvasinit 0
-set current_img ""
-
-proc watchgif {fname} {
- global atime filename
- set filename $fname
- set newatime ""
- catch {set newatime [file mtime $filename]}
- if { $newatime != $atime } {
- set atime $newatime
- update_image
- }
- after 1000 "watchgif $filename"
-}
-
-proc update_image {} {
- global canvasinit canvas current_img filename
- set img [image create photo -file $filename]
- if {$canvasinit == 0 } {
- canvas .img
- pack .img
- set canvasinit 1
- } else {
- image delete $current_img
- }
- .img delete imagedata
- set width [image width $img]
- set height [image height $img]
- .img configure -width $width -height $height
- .img create image 0 0 -image $img -anchor nw -tag imagedata
- set current_img $img
-}
-
-proc write {im} {
- global filename
- set out [fopen $filename wb]
- gdImageGif $im $out
- fclose $out
-}
-
-</pre></blockquote>
-Now an interactive gd session<p>
-<p>
-<blockquote><pre>> wish
-% load ./gd.so
-% source gdfonts.tcl
-% source watchgif.tcl
-% watchgif test.gif ;# Watch a file for changes and display
-% set im [gdImageCreate 300 300]
-_817d108_gdImagePtr
-% set black [gdImageColorAllocate $im 0 0 0]
-0
-% set white [gdImageColorAllocate $im 255 255 255]
-1
-% gdImageLine $im 20 20 250 70 $white
-% gdImageString $im $gdFontLarge 20 70 "Hello World" $white
-% write $im
-% gdImageArc $im 100 100 50 20 0 270 $white
-% write $im
-
-</pre></blockquote>
-Is this example, various gd library functions are issued interactively. Whenever you want to see the current image, simply type `<tt>write $im</tt>' and the image currently displayed in the canvas will be updated. The interface is minimal, but you can use it to play with the library, see how it works, and even write little Tcl scripts to try things out.<p>
-<a name="n40"></a><h3> Writing Test Scripts</h3>
-Where this approach really shines is the ability to write flexible test scripts. When developing C libraries, I always seem to find myself spending a huge amount of time writing test programs to exercise various parts of the library. Although I could write a collection of C programs to do this, using Tcl is often much more flexible. Suppose you wanted to test various aspects of the gd library. To do this, you might write a generic test script such as the following<p>
-<p>
-<blockquote><pre># gdtest.tcl : Generic gd test script
-#
-# This scripts sets up some default values, creates an image
-# and executes a test script.
-#
-# usage : tclsh gdtest.tcl script.tcl
-
-load ./gd.so
-source gdfonts.tcl
-
-# Configuration options
-
-set width 400
-set height 400
-
-# Create an image
-set im [gdImageCreate $width $height]
-
-# Create some colors
-set black [gdImageColorAllocate $im 0 0 0]
-set white [gdImageColorAllocate $im 255 255 255]
-set red [gdImageColorAllocate $im 255 0 0 ]
-set green [gdImageColorAllocate $im 0 255 0 ]
-set blue [gdImageColorAllocate $im 0 0 255]
-set yellow [gdImageColorAllocate $im 255 255 0]
-set cyan [gdImageColorAllocate $im 0 255 255]
-set magenta [gdImageColorAllocate $im 255 0 255]
-
-# Get the filename of the test script
-set filename [lindex $argv 0]
-
-# Run the test script
-source $filename
-
-# Output the image
-append filename ".gif"
-set out [fopen $filename wb]
-gdImageGif $im $out
-fclose $out
-
-puts "Image written to $filename"
-
-</pre></blockquote>
-<p>
-This script simply sets up an image and some default values. To use it, you would write a short test script such as<p>
-<p>
-<blockquote><pre># lines.tcl : Draw some lines
-gdImageLine $im 10 10 300 50 $white
-gdImageLine $im 50 200 290 10 $red
-...
-</pre></blockquote>
-<p>
-and run it as follows :<p>
-<p>
-<blockquote><pre>% tclsh gdtest.tcl lines.tcl
-Image written to lines.tcl.gif
-%
-
-</pre></blockquote>
-Finally, if you wanted to develop an entire testing suite, you can write a collection of scripts to exercise various features along with a simple testing program.<p>
-<p>
-<blockquote><pre># gd testing script
-
-set files { lines.tcl arcs.tcl fonts.tcl fill.tcl polygons.tcl ... }
-
-foreach f $files {
- puts -nonewline "Testing $f ... "
- if [catch {set msg [exec tclsh gdtest.tcl $f ]}] {
- set msg "Failed!"
- }
- puts $msg
-}
-
-</pre></blockquote>
-In the test program, each test is run as a separate process using `exec'. The reason for this is that if a test fails with an internal error (such as a segmentation fault), it won't affect any of the other tests (in other words, testing can proceed even if individual parts fail). When running the test, you will now get output such as the following :<p>
-<p>
-<blockquote><pre>% tclsh test.tcl
-Testing lines.tcl ... Image written to lines.tcl.gif
-Testing arcs.tcl ... Image written to arc.tcl.gif
-Testing fonts.tcl ... Image written to fonts.tcl.gif
-Testing fill.tcl ... Failed!
-Testing polygons.tcl ... Image written to polygons.tcl.gif
-%
-
-</pre></blockquote>
-While simple, you can imagine writing a large collection of test scripts to exercise various features of a library. By writing the test scripts in Tcl, they are easy to write and easy to modify. In fact, a powerful testing suite can be developed without having to write additional programs in C/C++.<p>
-<a name="n41"></a><h3> Building an Object Oriented Interface </h3>
-One of the interesting parts of using SWIG is that there is almost always more than one way to do things. In the gd example, a straightforward Tcl interface has been built to C library. From Tcl, the library works in essentially the same manner as it does in C. However, it's also possible to package libraries in an entirely different manner. Using the SWIG class extension mechanism, the following code can be added to the SWIG interface:<p>
-<p>
-<blockquote><pre>%module gd
-%{
-#include "gd.h"
-%}
-%include gd.h
-...
-%addmethods gdImage {
- gdImage(int w, int h) {
- return gdImageCreate(w,h);
- }
- ~gdImage() {
- gdImageDestroy(self);
- }
- int color(int r, int g, int b) {
- return gdImageColorAllocate(self,r,g,b);
- }
- void plot(int x, int y, int c) {
- gdImageSetPixel(self, x, y, c);
- }
- void line(int x1, int y1, int x2, int y2, int c) {
- gdImageLine(self,x1,y1,x2,y2,c);
- }
- void poly(gdPointPtr pts, int npoints, int c) {
- gdImagePolygon(self,pts, npoints, c);
- }
- void rect(int x1, int y1, int x2, int y2, int c) {
- gdImageRectangle(self,x1,y1,x2,y2,c);
- }
- void string(gdFontPtr font, int x, int y, char *str, int c) {
- gdImageString(self,font,x,y,str,c);
- }
- void write(char *filename) {
- FILE *f = fopen(filename,"wb");
- if (f == NULL) return;
- gdImageGif(self,f);
- fclose(f);
- }
-}
-
-</pre></blockquote>
-Now, images can be manipulated almost like a Tk widget<p>
-<p>
-<blockquote><pre>load ./gd.so
-gdImage img 400 400 ;# Create an image
-set black [img color 0 0 0] ;# Allocate some colors
-set white [img color 255 255 255]
-img line 20 20 300 300 $white ;# Draw some objects
-img rect 40 40 250 250 $white
-img string $gdFontLarge 10 100 "Hello World" $white
-img write "test.gif" ;# Output the image
-rename img "" ;# Destroy the image
-
-</pre></blockquote>
-<a name="n42"></a><h3> Porting to Other Languages</h3>
-Although this chapter has focused exclusively on the use of SWIG and Tcl, nothing prevents us from using other scripting languages. In fact, looking at the example, no Tcl specific code is involved in creating the scripting interface (unless you went overboard with typemaps or Tcl specific helper functions). Because of this, it is trivial to retarget the interface to other environments by simply running SWIG with different command line options<p>
-<blockquote><pre>
-swig -perl5 gd.i # Create Perl5 module
-swig -python gd.i # Create a Python module
-
-</pre></blockquote>
-As a result, it is easy to write scripts in other languages. For example :<p>
-<p>
-<blockquote><pre># A Perl5 Script
-use gd;
-# Create an image
-$im = gd::gdImageCreate(200,200);
-
-# Allocate colors
-$black = gd::gdImageColorAllocate($im,0,0,0);
-$white = gd::gdImageColorAllocate($im,255,255,255);
-
-# Draw a line
-gd::gdImageLine($im,20,50,180,140,$white);
-
-# Write the image
-$out = gd::fopen("test.gif",wb);
-gd::gdImageGif($im,$out);
-gd::fclose($out);
-
-# Clean up
-gd::gdImageDestroy($im);
-
-</pre></blockquote>
-or<p>
-<p>
-<blockquote><pre># A Python script
-import gd
-im = gd.gdImageCreate(200,200)
-
-# Allocate colors
-black = gd.gdImageColorAllocate(im,0,0,0)
-white = gd.gdImageColorAllocate(im,255,255,255)
-
-# Draw a line
-gd.gdImageLine(im,20,50,180,140,white)
-
-# Write the image
-out = gd.fopen("test.gif",wb)
-gd.gdImageGif(im,out)
-gd.fclose(out)
-
-# Clean up
-gd.gdImageDestroy(im)
-
-</pre></blockquote>
-Although you might not consider the use of other scripting languages to be so important, consider the process of upgrading to newer version of Tcl. Tcl 7 was based entirely on strings (the "everything is a string" model) while Tcl 8 uses dual-ported objects. Using objects provides better performance and upgrading a SWIG module from Tcl 7 to Tcl 8 is usually trivial -- just rebuild all of your interfaces by running SWIG with the <tt>-tcl8</tt> option.<p>
-<a name="n5"></a><h2> Summary</h2>
-I hope to have given you a small taste of SWIG and how it can be used with C/C++ applications. From a personal perspective, I have found the combination of SWIG and Tcl to be a powerful development tool. First, SWIG makes it relatively easy to build Tcl interfaces to existing C code--in fact, I rarely have to dig out my Tcl books for this. Second, Tcl is a great way to interact with C libraries. Not only can I interactively tweak parameters, call functions, and try things, I can write testing scripts and short programs without having to write additional C code. Finally, this approach has had a noticeable impact on the quality of the software I have developed. Before having the Tcl interface, it was always a struggle to use the code I had developed. More often than not, I would spend inordinate amounts of time writing bad user interfaces and test programs. However, by having a Tcl interface, I was given an environment that lets me play with libraries, test components, and concentrate on the problem at hand. In many cases, this has allowed me to find design flaws and correct reliability problems much earlier than before.<p>
-<p>
-This chapter has only scratched the surface of SWIG and its use with Tcl. In addition to its use in application development, SWIG can also be used to build general purpose Tcl extension modules and as a tool for building graphical user interfaces to C/C++ applications (using Tk). Readers interested in other SWIG applications should take a look at the web-page (www.swig.org) and the SWIG Users Manual.<p>
-<p>
-SWIG would not be possible without the valuable contributions of its users. Although there are far too many people to thank individually at this point, you know who you are. SWIG would certainly not be in its current state without their feedback.<p>
-<p>
-
-<p><hr>
-
-<address>beazley@cs.uchicago.edu Fri Aug 14 10:25:19 1998</address>
-</body>
-</html>
diff --git a/swigweb/papers/TclTutorial98/TclTutorial98.pdf b/swigweb/papers/TclTutorial98/TclTutorial98.pdf
deleted file mode 100644
index 80a155c..0000000
--- a/swigweb/papers/TclTutorial98/TclTutorial98.pdf
+++ /dev/null
Binary files differ
diff --git a/swigweb/projects.ht b/swigweb/projects.ht
deleted file mode 100644
index fba2523..0000000
--- a/swigweb/projects.ht
+++ /dev/null
@@ -1,447 +0,0 @@
-The SWIG Files
-
-<p><img src="images/projects.png" alt="Projects">
-
-<p>
-SWIG is being used in an increasing number of applications, most of
-which are related to research and development, prototyping, software testing,
-and construction of specialized systems. This page describes
-some of the ways in which SWIG is currently being used.
-
-<p>
-(Note : the
-opinions expressed here do not necessarily reflect those of any
-given employer or organization).
-
-<hr>
-<p>
-David Beazley (dmb@viking.lanl.gov) and Peter Lomdahl (pxl@viking.lanl.gov)<br>
-
-<p>
-SWIG is being used to construct a Python interface to the <a
-href="http://bifrost.lanl.gov/MD/MD.html">SPaSM</a> molecular dynamics
-code at Los Alamos National Laboratory. Currently this code is being
-used to perform large-scale simulations of fracture, shock waves, and
-dislocation dynamics. The system runs in parallel on a 12 processor
-Sun Enterprise 4000 server and is implemented with MPI and Solaris
-multithreading. The Python interface is used to provide users with an
-interactive data analysis, visualization, and prototyping environment.
-Users can also interact with underlying C data structures and "steer"
-computations as needed. One of the advantages of SWIG is that it
-allows interfaces to be easily constructed from existing code. The
-SPaSM system consists of nearly 300 C functions and the Python
-interface is automatically generated during compilation. This work
-was recently featured on the cover of "Computers in Physics" (June,
-1997).
-
-<hr>
-<p>
-John Schmidt (jas@cs.utah.edu) <br>
-
-<p>
-I am using SWIG to integrate four stand alone software packages into a
-unified system controlled by Tcl/Tk scripts. The unified software
-system is used to design and test defibrillation electrodes via
-computer simulations of a human subject. The individual software
-pieces include: a visualization package written in C++ using
-OpenInventor and Motif, an unstructured mesh generator written in C, a
-Finite Element Solver written in C, and a segmentation software
-written in C++ using OpenGL and Motif. SWIG has been crucial to the
-development of this project. With SWIG, the integration of the
-individual pieces was trivial.
-
-<hr>
-<p>
-David Brydon (brydon@lanl.gov) <br>
-
-<p>
-We are using swig with python to retrieve, analyze, and visualize very
-large data sets from ocean model simulations on parallel computers.
-We have written C routines that access our data. Graphics libraries
-and Matlab are used to visualize the data. We are very happy with the
-flexible, programmable, powerful tool that results.
-
-<hr>
-<p>
-Mike Weiblen (mew@paradigmsim.com) <br>
-
-<p>
-Paradigm sells modular C toolkits for developing visual
-simulation/virtual reality graphics applications called Vega and another
-for spatial audio simulation called AudioWorks. I've used SWIG to wrap
-Vega's and AW's APIs with Silicon Graphics' "sgitcl" to create "vgTcl"
-and "awTcl". Exploiting the power of interactive scripting languages,
-they provide the full power of the APIs at runtime, without an
-application developer having to anticipate flexibility a priori. SWIG
-has enabled our customers to interact with our toolkits in fundamentally
-new ways.
-<p>
-Several years ago (I believe we discussed this stuff way back in 1994
-;-), I created a set of C preprocessor macros that did SWIG-like
-things. It was a very tedious process, making it difficult to follow
-changes to an evolving API, but it was useful for proof-of-concept.
-When SWIG 1.1B1 came out in October, I was generously given a R&D budget
-to reimplement my project in SWIG. The project has been a resounding
-success!
-
-<hr>
-<p>
-Jonah Lee (jonah@melab.uafsoe.alaska.edu)
-
-<p>
-[We're using SWIG for] wrapping up engineering applications using
-finite element method including pre- and post-processing. My program
-is somewhat general and is used to solve problems for engineering
-materials--metals, polymers and ice-- undergoing plastic (permanent)
-deformations. It's mainly used for rapid prototyping, development and
-testing. The code runs on workstations, Cray Y-MPs and Cray T3E (when
-I get there... that is).
-
-<hr>
-<p>Jody Winston (jody@sccsi.com)
-
-<p>
-
-I have used SWIG to wrap an API that controlled two stepper motors and
-a CCD camera on a Linux system that gathered real time image data. In
-Windows, I wrapped an application's C++ API and used SWIG to embed a
-Python (pywin) interpreter into the C++ application. I also used SWIG
-to wrap a FORTRAN API that was used to read and write data into a
-custom data base.
-<p>
-SWIG has allowed me to move the time critical code into C, C++, or
-FORTRAN while having the application being controlled by Python. I
-can quickly embed an interpreter into an application.
-
-<hr>
-<p>
-Peter Lister (p.lister@cranfield.ac.uk)<br>
-
-<p>
-I'm using [SWIG] for a Perl scriptable version of Van Jacobson's libpcap
-packet capture library. I can now use Perl regular expressions to
-process packets on the fly. My main reason is to extract information
-from ARP packets and automatically maintain our database of IP/MAC
-address mappings directly from perl rather than hacking the output of
-arpwatch or tcpdump.
-
-<hr>
-<p>
-Harald Singer (singer@itl.atr.co.jp)
-
-<p>
-[We are using SWIG for] wrapping C libraries to Python for speech recognition research
-at ATR Interpreting Telecommunications Laboratories.
-<p>
-We are working in a multi-vendor environment (HP-UX, OSF1, Linux,
-SunOS, Solaris) and writing new applications has become very tedious.
-Therefore, we decided to employ python, but at the same time we would
-like to have access to our signal processing libraries etc. that were
-and are still written in C.
-<p>
-The advantages of using Python become more evident every day. For
-example, it was fairly easy to write a GUI using python/tk. We are
-using this now for interactive error analysis. A typical scenario is
-like this:
-
-<ul>
-<li> audio data is collected via microphone/AD (in Python) and sent to the
-recognizer frame by frame.
-
-<li> the recognizer (C code) makes a decision about speech endpointing and
-once it has discovered end of utterance does a callback to the
-application (python/tk) with a word lattice as result.
-
-<li> this word lattice is now displayed for the user in python/tk.
-
-<li> the user can now interactively rescore part of the lattices, look at
-the detailed acoustic and language model scores, listen to parts of
-the utterance, etc.
-</ul>
-<p>
-SWIG helps us in taking away part of the error-prone task of making
-the C routines accessible from python and has considerably improved
-our efficiency.
-
-<hr>
-<p>
-Dominique Dumont (domi@ss7serv.grenoble.hp.com)
-<p>
-I'm using SWIG to generate a perl5 API on top of HP's OpenCall TCAP
-API. TCAP is the top protocol layer of HP's SS7 stack of telecom
-protocol. The perl5 API developemnt effort is a part of the systematic
-testing approach we're implementing in the division.
-<p>
-The usual way was to write test programs
-in C. The main drawback being that developing and running the tests
-consumes a lot of time.
-<p>
-Now the goal is to write all (or at least most of) the test in perl
-allowing a faster cycle time between modifying the API and testing
-it. (We'll also be able to debug faster the test programs).
-<p>
-Perl's power also enables us to write test using oo methodology
-(although the API is strictly procedural), thus we can easily develop
-complex test scenarios.
-<p>
-Hopefully (i.e. if we have some spare time), the next step will be to
-combine Tk with Perl and SWIG so we'll be able to monitor with a user
-friendly interface the progress of the test suite.
-
-<hr>
-<p>Daniel Michelson (Daniel.Michelson@smhi.se)
-
-<p>
-A collegue and I are using SWIG for two purposes, both of which
-centre around the creation of a Python-based environment for analysis
-and visualization of data from the Swedish national weather radar
-network:
-<ul>
-<li> interfacing old code
-<li> interfacing new, performance critical, code.
-</ul>
-<p>
-We have a couple of other collegues, also at SMHI R&D, who are working
-in satellite-based remote sensing activities and who will be starting to
-use SWIG in the near future for their purposes.
-
-<hr>
-<p>Roger Burnham (rburnham@cri-inc.com)
-
-<p>
-Thanks again for SWIG... Its fun, allows great productivity while
-avoiding much tedium...
-<p>
-The current application (there will be many spin-offs/variations) is
-in polarization microscopy. We manufacture electronically
-controllable retarder plates, and along with a scientist at the
-Marine Biological Lab in Woods Hole have developed an algo/method
-that allows us to visualize a sample's retardance (direction and
-magnitude) over the whole image. Conventional methods allow you to
-see this structure only along one axis at a time... The main tools
-I'm using are Python/Tkinter/PIL/NumPy/SWIG.
-<p>
-So, I've use SWIG to:
-<ul>
-<li> Wrap a commercial serial communications DLL.
-<li> Wrap a commercial frame grabber interface
-<li> After prototyping in Python, I move compute intensive routines
- into DLL's.
-</ul>
-Our apps are running under Win95. I thought it was pretty cool to be
-able to control a frame grabber, display live/acquired images, all
-from within Python, within the same day I received the frame grabber
-SDK, never having dealt with such hardware before!
-
-<hr>
-<p>
-Simon Gibson (gibson@dstc.qut.edu.au)
-<p>
-
-I have been using SWIG to create a Python interface for our
-prototype implementation of GSSAPI. This is being done so
-that we can incorporate security into the Hector project here
-at DSTC. It also means that I can write Python application
-programmes. Also now we have a standard interface to GSSAPI
-and any implementation should be able to be plugged in.
-<p>
-Hector is described in an article in the January/February
-1997 - Distributed Objects <a href="http://www.ddj.com/ddsbk/1997/1997.01/index.htm">Dr. Dobb's Sourcebook</a>.
-
-<hr>
-<p>
-Mark Hammond (MHammond@skippinet.com.au)
-
-<p>
-
-I'm using [SWIG] to write a commericial application, which runs as an NT
-service. It uses the COM extensions to talk native MAPI to exchange
-server, the service extensions to run unattended on NT, and the pipe, file
-and event modules to manage the service control messages and named pipe
-connections from clients. All modules named above were generated by SWIG.
-The COM extensions will allow (once the .i file is up to it :-) any native
-COM interface (ie, not IDispatch (eg, VB/Word/Excel) based) to be supported
-by Python.
-
-<hr>
-<p> Michael Bell (michaelb@gold.net.au)
-
-<p>
-I've used SWIG on a Linux platform to create Python modules for
-graphing and database access.
-<p>
-The PGPLOT Graphics Subroutine Library is a Fortran library by Tim
-Pearson (tjp@astro.caltech.edu). I understand it is often used by
-astronomers. It may also be built into a C library.
-<p>
-I used SWIG to wrap the C library wrapping the Fortran library (!)
-into a Python module, using some straightforward typemaps to convert
-one and two dimensional Python Numeric arrays into the appropriate
-pointers. I haven't methodically tested the full functionality, but
-everything I tried works just fine.
-<p>
-I've also used SWIG to wrap up a library of Fortran subroutines
-developed within the Western Australian Department of Environmental
-Protection to manage databases of time series meteorological and air
-quality data. I used SWIG to generate a simple shadow class which I
-then extended further to make the interface nicer.
-<p>
-The original library provided, for instance, subroutines opendb(),
-writdb(), readdb() and closdb(). My module, epadb.py, provides a
-database class, epadb.DB, which is instantiated, d=epadb.DB(). The
-database instance then provides methods d.open(), d.read(), d.write()
-and d.close(), returning data as Python lists and arrays.
-<p>
-I'm particularly pleased that I managed to do these things with my
-reading only knowledge of C, and lots of cutting and pasting.
-
-<hr>
-<p>
-Soeren Henkel (soeren@hni.uni-paderborn.de)
-<p>
-We are currently in the process of redeveloping OOPUS, a system for
-modeling plant systems and generate plant control software from a model.
-(Don't ask what OOPUS stands for -it's a German acronym.) We decided to
-reimplement its user inteface using Tcl/Tk. OOPUS puts its models
-into an OODBMS, namely POET. So we needed an integration of POET
-(which is tightly coupled to C++) with Tcl/Tk, and we've successfully
-done that with SWIG.
-
-<hr>
-<p>
-Peter A. Tinker (patinker@msmail4.hac.com)
-<p>
-We're using SWIG to "glue" Tcl/Tk to custom and third-party libraries. In
-particular, SWIG provides an elegant means for controlling Sense8
-Corporation's WorldToolKit (WTK) virtual environment development system from a
-Tk GUI. The result is highly portable code that is
-independent of WTK's proprietary GUI yet allows access to virtually all WTK
-functions from a Tcl script and/or a Tk GUI. This approach is
-being used in a variety of projects involving advanced 3D visualization
-on a variety of imcompatible systems.
-
-<hr>
-<p>
-Peter-Pike Sloan (ppsloan@cs.utah.edu)
-<p>
-I have been using SWIG for several projects, mostly to streamline
-working with OpenGL under Tcl/Tk. Examples are a time-critical
-framework for viewing Lumigraphs (basically a digital hologram) and a
-proof of concept application for optimizing texture coordinates based
-on relative importance (determined by analyzing the existing texture
-and user specification.) Using SWIG has dramatically reduced my
-development time allowing me to develop code and debug state in an
-interpreted environment (currently Tcl, but I think I am going to move
-to Python).
-
-<hr>
-<p>
-Chris Myers (myers@beamtech.com)
-<p>
-We at Beam Technologies, Inc. have used SWIG to begin developing an
-interpreted Python interface to our PDESolve library. PDESolve is a
-C++ class library for formulating and solving partial differential
-equations (using either finite difference methods or finite element
-methods), and makes use of OO technology to present a high-level
-symbolic interface to the programmer. This makes the description of
-PDE-based problems concise, and enables the embedding of PDE-based
-models in larger computational frameworks (e.g., to do PDE-based
-design optimization or coupled PDE-based systems). SWIG has allowed
-us very quickly to develop a prototype Python interface to that
-library. Such an interface holds the promise of: (1) allowing even
-more rapid prototyping of models, (2) dynamic formulation of models
-and solution methods, and (3) a method for conveniently integrating
-PDESolve with other packages (i.e., through the Python substrate).
-My hope is to make a Python-enabled PDESolve a tool for PDEs something
-like what Matlab provides for linear algebra, i.e., a high-level,
-interpreted environment for rapid prototyping and interactive
-exploration, with an embedded programming language for scripting
-complex codes.
-
-<p>
-And while I have been looking for a while for a powerful and
-extensible interpreted language for use as a front-end to compile codes
-(which Python is), SWIG has made the interfacing of that code vastly
-easier than it would have been otherwise. While we are still in the
-prototyping stages of this overall approach, SWIG enabled us to get up
-and running quickly with a Python interface to PDESolve, and
-demonstrate the utility of such an approach for a complex C++ library
-(something that SWIG was not originally designed to really tackle).
-
-<hr>
-<p>
-Vladimir I.Ulogov (gandalf@starship.skyport.net)
-<p>
-
-SWIG is being used to create a Python interface to CLIPS expert system shell
-inside my general research job under OODBMS DNET. This extention module
-provide full control from Python environment to expert system: Change a
-global valiables, register a fact, manipulation with agenda, fact lists,
-modules, functions, classes and instances. You can dynamicaly create and
-execute CLIPS commands using clips.RouteCommand function call. Module
-interface are similar to CLIPS Advanced API, who described into CLIPS
-documentation. All additional documentation, Python classes are distributed
-too. Module was be tested on Windows/NT and SUN Solaris 2.4 host platforms,
-CLIPS version: 6.04, Python version 1.4. This module consist about 270
-functions. This job took 3 days of my job at october 1997.
-
-<hr>
-<p>
-Pinhong Chen (phchenb@tsmc.com)
-<p>
-I got a page for
-<a href="http://www-cad.eecs.berkeley.edu/~pinhong/scriptEDA"
->EDA applications</a>
-using SWIG.
-
-<hr>
-<h3> Tools and Modules </h3>
-The following tools and modules have been produced using SWIG
-or are related to SWIG.
-
-<ul>
-<li><p><a href="http://www.thestuff.net/bob/projects/blade">BLADE</a>. A web publishing environment.
-
-<li><p><a href="http://students.cs.byu.edu/~butler/jni/PyJava.html">PyJava</a>. Provides
-Python access to Java methods (Kevin Butler).
-
-<li><p><a href="http://playground.sun.com/~bharat/pilotmgr.html">Pilot Manager</a>. Hook
-your US Robotics PalmPilot up to your Sun workstation (Bharat Mediratta).
-
-<li><p> <a href="http://www.mic.atr.co.jp/~gulliver/WTK/www">PyWTK</a>. A Python
-interface to the WorldToolKit (a virtual reality modeling toolkit). (Roberto Lopez Gulliver)
-
-<li><p> A Python interface to
-<a href="http://starship.python.net/crew/robind/index.html">BSD DB 2.7.x</a> (Robin Dunn).
-
-<li><p><a href="http://alldunn.com/wxPython/index.html">wxPython</a>. A Python extension
-module that encapsulates the wxWindows GUI classes.
-
-<li><p> Net-Pcap. A Perl interface to the libpcap library (Peter Lister).
-
-<li><p> X11::Wcl. A Perl interface to the Widget Creation Library (Joe Buehler).
-
-</ul>
-
-<hr>
-<h3> Other Application Areas </h3>
-
-These are some of the application areas that I've heard about SWIG being
-used (but don't have many details).
-
-<ul>
-<li> Semiconductor CAD.
-<li> Databases.
-<li> Remote sensing.
-<li> Scientific visualization and simulation.
-<li> Financial Modeling.
-<li> Distributed and parallel computing.
-<li> Distributed objects (use with CORBA).
-<li> Software testing.
-</ul>
-
-<hr>
-<h3> How are you using SWIG? </h3>
-
-If you would like to list your project here, please
-send e-mail to beazley@cs.uchicago.edu.
diff --git a/swigweb/propaganda.ht b/swigweb/propaganda.ht
deleted file mode 100644
index c5abb35..0000000
--- a/swigweb/propaganda.ht
+++ /dev/null
@@ -1,170 +0,0 @@
-SWIG Propaganda
-
-<p><img src="images/propaganda.png" alt="Propaganda">
-
-<p>
-The following comments about SWIG were collected by a user survey conducted
-in March, 1998.
-
-<ul>
-
-<li><p>"SWIG has helped us minimize the hassle of writing manual wrappers.
-Since SWIG has proven to be rather easy to use, I find I can carry out the types of wrapping
-activities which would otherwise have been the responsibility of a
-computer scientist."
-
-<li><p>"I really love the fact that the learning curve is short
-and flat. I don't need to use this facility very often,
-but when I absolutely have to link in external C routines,
-or when I have to get the last drop of speed from something
-previously written in Perl, I can count on SWIG to be there.
-When I do use SWIG, I don't need to spend hours learning
-and debugging the system. This is the closest thing to
-cut-and-paste I've ever seen in inter-language library
-creation."
-
-<li><p>"We are a research group that develops medical imaging software.
-We are interested in image processing/visualization research,
-and for our software, we want a simple and portable tool to
-generate user interfaces. For this, we currently use
-Tcl/Tk, and SWIG which provides a nice way to connect our
-software (in C++) to the tcl-scripts."
-
-<li><p>"Very quick first results."
-
-<li><p>"Easy to use, no need to worry about language internals. It is a boon for application developers, like me."
-
-<li><p>"I like the fact that it automates much of the tedious work
-in building an interface C/C++ functions. This makes development easier."
-
-<li><p>"SWIG is by far the easiest way I have found to generate
-scripting interfaces for scientific software. SWIG makes it
-practical to use a single, powerful scripting language for
-all projects rather than writing a custom interface to each.
-It also encourages a consistent and modular form for a program,
-and makes it easier to add contributions to my programs from
-other users/programmers."
-
-<li><p>"I like the ease with which scripting languages can be extended.
-The fact that we could so easily interface with Lotus Notes on NT using Python was just amazing."
-
-<li><p>"SWIG makes linking
-my application to a scripting language easy enough
-that it is worthwhile."
-
-<li><p>"I came, I saw, I wrapped. And it ran. Woo hoo!"
-
-<li><p>"Without SWIG it would have taken much, much longer for
-our group to use Python as an extension language. Our whole
-application was written mostly in C++. We wanted to look
-into using Python for portions of it in order to make it
-easier to extend. Python has a fairly nice interface for
-doing this sort of thing. The trouble was that we needed to
-make hundreds of C++ classes available to Python. This
-would have taken a very long time (to write the wrapper code).
-SWIG allowed us to spend a minimal amount of time with
-the wrapper code and most of our time moving stuff to Python
-(which was the big point in the first place)."
-
-<li><p>"SWIG is a huge time-saver. I have approximately 30,000
-lines of C and Python code that have been generated by
-SWIG that I didn't have to write by hand, don't
-have to fix syntax and fumble-finger errors in, and
-don't have to aggressively test."
-
-<li><p>"SWIG helps us in taking away part of the error-prone task of making
-the C routines accessible from Python and has considerably improved
-our efficiency."
-
-<li><p>"I like all the time I have saved by not writing the interfaces myself."
-
-<li><p>"SWIG saves a lot of my energy in interfacing with many free
-C/C++ libraries in my project."
-
-<li><p>"SWIG handles the gory details and allows me to concentrate on the important things."
-
-<li><p>"Using SWIG is really fun, because it saves you from
-a lot of mechanical work and it takes care of all the
-details you don't want to bother with letting you
-concentrate on the real problem."
-
-<li><p>"Thanks again for SWIG... It's fun and allows great productivity while
-avoiding much tedium."
-
-<li><p>"[I like] the ability to write extensions basically without having to think too
-hard about what I'm doing."
-
-<li><p>"SWIG allows me to get on with scripting
-and writing C++ code without having to worry about the
-(usually considerable) issues involved in extending the
-scripting language with my custom components."
-
-<li><p>"Using a scripting language as glue between C++ components
-is a powerful paradigm for combining flexibility with
-robustness and efficiency. SWIG enables this model by
-providing a solid bridge between the C++ component and
-the scripting language."
-
-<li><p>"The ability to ``follow'' the development of the core
-application without constantly rebuilding the interface
-is very effective. The developments of the kernel and its interface are
-mutually protected to a large degree."
-
-<li><p>"SWIG allows us to recycle a lot of ugly old C code and put
-it into a reasonable module structure and snazzy new user
-interfaces."
-
-<li><p>"It allows us to leverage the advantages of the scripting
-language, especially when so many other scripts are already
-being written to glue programs together and some of our
-other tools have their own scripting language interface.
-Using SWIG will allow us to properly integrate each of the
-parts directly into the language instead of a collection
-of system() calls."
-
-<li><p>"Before I had to use C++ for my ``rapid'' prototyping.
-Now I can script it!"
-
-<li><p>"My code is cleaner and more compact which makes it easier to
-read and understand. SWIG also encourages modularize code--allowing
-one to test/debug modules independently. This makes connecting
-everything together a breeze."
-
-<li><p>"The very idea of scripting programming on the one hand and
-systems programming on the other is quite nice, the most
-important feature of SWIG is to make this approach
-practical on a day-by-day basis."
-
-<li><p>"On the whole, SWIG is my most important development tool
-after gcc!"
-
-<li><p>"SWIG has enabled our customers to interact with our toolkits in fundamentally
-new ways."
-
-<li><p>"We are using Tcl scripts as the data files driving our
-simulations. Once the data is defined using a program
-(which is pretty cool in itself), we can actually run the
-simulation from script commands. In our experimental
-environment, that saves rewriting a lot of "main" programs
-that exercise the same basic objects. This isn't exactly computational steering, but it does give
-our engineers a lot of flexibility."
-
-<li><p>"All (well most) of my C++ code (MC simulations of
-proteins and sequence analysis) is now driven by
-a Python interface thanks to SWIG. Once I have decided on an interface, the
-process of building it is usually trivial."
-
-<li><p>"SWIG is an integral part of a user environment I am creating for a Molecular Dynamics company.
-They have FORTRAN modules that require a steering language (Python) to enable flexible computational
-research."
-
-<li><p>"SWIG plays a critical role to automate the generation of
-Perl client interfaces from the OMG IDLs for a CORBA ORB.
-The Perl client interface is essential in script driven
-testing."
-
-<li><p>"I am enjoying rapidly developing complex projects using OO
-and Python, but coming from a numerical background, I like
-that I can get fast number crunching performance when I
-need it from C modules wrapped up by SWIG. "
-</ul>
diff --git a/swigweb/rants.ht b/swigweb/rants.ht
deleted file mode 100644
index b77ec9c..0000000
--- a/swigweb/rants.ht
+++ /dev/null
@@ -1,8 +0,0 @@
-SWIG Rants
-
-<p>
-<img src="images/rants.png" alt="Rants">
-
-<p>
-Well, there's nothing here yet, but rest assured, there are plenty of things to rant
-about.
diff --git a/swigweb/release.ht b/swigweb/release.ht
deleted file mode 100644
index b1148d2..0000000
--- a/swigweb/release.ht
+++ /dev/null
@@ -1,15 +0,0 @@
-Release Notes
-
-<h2>Release Notes</h2>
-
-The following files are extracted from the SWIG CVS repository.
-
-<ul>
-<li><a href="Release/README">README</a>
-<li><a href="Release/CHANGES">CHANGES</a>
-<li><a href="Release/CHANGES.current">CHANGES.current</a>
-<li><a href="Release/NEW">NEW</a>
-<li><a href="Release/LICENSE">LICENSE</a>
-</ul>
-
-
diff --git a/swigweb/screenshot.ht b/swigweb/screenshot.ht
deleted file mode 100644
index 0c28f24..0000000
--- a/swigweb/screenshot.ht
+++ /dev/null
@@ -1,8 +0,0 @@
-SWIG Screenshot
-
-<p><img src="images/screen.png" alt="Screenshot">
-
-<p><img src="images/screenshot.png" alt="Screenshot image">
-
-<p>
-It is lovely, isn't it?
diff --git a/swigweb/screenshot2.ht b/swigweb/screenshot2.ht
deleted file mode 100644
index c14a17e..0000000
--- a/swigweb/screenshot2.ht
+++ /dev/null
@@ -1,9 +0,0 @@
-SWIG Screenshot
-
-<p><img src="images/screen.png" alt="Screenshot">
-
-<p><img src="images/screenshot2.png" alt="Screenshot image">
-
-<p>
-Much better than before, don't you think?
-
diff --git a/swigweb/subversion.ht b/swigweb/subversion.ht
deleted file mode 100644
index 5d0a090..0000000
--- a/swigweb/subversion.ht
+++ /dev/null
@@ -1,31 +0,0 @@
-SWIG Subversion
-
-<p><img src="images/subversion.png" alt="Subversion">
-
-<ul>
-<li>The newly-revised SWIG mission statement:
-
-<center>
-<em>
-"We are building a wrapper generator of extraordinary magnitude."
-<br>
-</em>
-</center>
-
-<li>Alternative mission statement:
-
-<center>
-<em>
-"You know, for kids." <br>
-</em>
-</center>
-
-<li>The ever-so-impressive SWIG-1.1 <a href="screenshot.html">screenshot</a>.
-<li>An even more impressive <a href="screenshot2.html">screenshot</a> showing the new streamlined interface to SWIG-1.3.
-<li><a href="visual.html">Visual SWIG 2002++ .NET</a>--the version for managers.
-<li>The greatly simplified <a href="copyfun.html">copyright</a>.
-</ul>
-
-
-
-
diff --git a/swigweb/survey.ht b/swigweb/survey.ht
deleted file mode 100644
index 7edbb9a..0000000
--- a/swigweb/survey.ht
+++ /dev/null
@@ -1,58 +0,0 @@
-Survey
-
-<table summary="Before downloading..."> <tr>
-<td bgcolor="#000000" align=center><font color="#ffffff"><b>Before downloading...</b></font></td>
-</tr> </table>
-
-Before downloading, please help us by filling in the simple survey below about your intended SWIG usage.
-<p>
-If you like you can skip it and go straight to the <a href="download.html">Download area</a>.
-
-<table summary="Usage Survey"> <tr>
-<td bgcolor="#000000" align=center><font color="#ffffff"><b>SWIG Usage Survey</b></font></td>
-</tr> </table>
-
-<form method=post action="http://www.swig.org/cgi-bin/surveyresponse.pl">
-<b>
-Which target languages will you be using SWIG for? Please select all that apply.
-</b>
-<blockquote>
-
-<input name="langChicken" type=checkbox align="left" value="1"> Chicken <br>
-<input name="langCSharp" type=checkbox value="1"> C# <br>
-<input name="langGuile" type=checkbox value="1"> Guile <br>
-<input name="langJava" type=checkbox value="1"> Java <br>
-<input name="langMzscheme" type=checkbox value="1"> MzScheme <br>
-<input name="langOcaml" type=checkbox value="1"> Ocaml <br>
-<input name="langPerl" type=checkbox value="1"> Perl <br>
-<input name="langPhp" type=checkbox value="1"> Php <br>
-<input name="langPike" type=checkbox value="1"> Pike <br>
-<input name="langPython" type=checkbox value="1"> Python <br>
-<input name="langRuby" type=checkbox value="1"> Ruby <br>
-<input name="langSexp" type=checkbox value="1"> Lisp S-exp <br>
-<input name="langTcl" type=checkbox value="1"> Tcl <br>
-<input name="langXml" type=checkbox value="1"> Xml <br>
-<input name="langOtherLang" type=checkbox value="1"> Other, please specify: <input name="namedLanguage" size="20"> <br>
-
-</blockquote>
-<p>
-
-<b>
-Which operating systems will you be running SWIG on? Please select all that apply.
-</b>
-<blockquote>
-
-<input name="osBSD" type=checkbox align="left" value="1"> FreeBSD/OpenBSD/NetBSD <br>
-<input name="osHPUX" type=checkbox align="left" value="1"> HP-UX <br>
-<input name="osLinux" type=checkbox align="left" value="1"> Linux <br>
-<input name="osMacOSX" type=checkbox align="left" value="1"> Mac OS X <br>
-<input name="osSolaris" type=checkbox align="left" value="1"> Solaris <br>
-<input name="osWindows" type=checkbox align="left" value="1"> Windows <br>
-<input name="osOtherOS" type=checkbox align="left" value="1"> Other, please specify: <input name="namedOS" size="20"> <br>
-
-</blockquote>
-
-<input type=submit value="Submit">
-
-</form>
-
diff --git a/swigweb/tutorial.ht b/swigweb/tutorial.ht
deleted file mode 100755
index e2ca126..0000000
--- a/swigweb/tutorial.ht
+++ /dev/null
@@ -1,317 +0,0 @@
-SWIG Tutorial
-
-<p>
-<img src="images/tutorial.png" alt="Tutorial">
-
-<p>
-So you want to get going in a hurry? To illustrate the use of SWIG,
-suppose you have some C functions you want added to Tcl, Perl, Python, Java and C#.
-Specifically, let's say you have them in a file 'example.c'
-
-<blockquote><pre>
-/* File : example.c */
-
-#include <time.h>
-double My_variable = 3.0;
-
-int fact(int n) {
- if (n <= 1) return 1;
- else return n*fact(n-1);
-}
-
-int my_mod(int x, int y) {
- return (x%y);
-}
-
-char *get_time()
-{
- time_t ltime;
- time(&ltime);
- return ctime(&ltime);
-}
-
-</pre></blockquote>
-
-<h3>Interface file </h3>
-
-Now, in order to add these files to your favorite language, you need to write an
-"interface file" which is the input to SWIG. An interface file for these
-C functions might look like this :
-
-<blockquote><pre>
-/* example.i */
-%module example
-%{
-/* Put header files here or function declarations like below */
-extern double My_variable;
-extern int fact(int n);
-extern int my_mod(int x, int y);
-extern char *get_time();
-%}
-
-extern double My_variable;
-extern int fact(int n);
-extern int my_mod(int x, int y);
-extern char *get_time();
-</pre></blockquote>
-
-<h3> Building a Tcl module </h3>
-
-At the UNIX prompt, type the following (shown for Linux, see the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl?SwigFaq/SharedLibraries">SWIG Wiki Shared Libraries</a> page for help with other operating systems):
-
-<blockquote>
-<pre>
-unix % swig -tcl example.i
-unix % gcc -fpic -c example.c example_wrap.c \
- -I/usr/local/include
-unix % gcc -shared example.o example_wrap.o -o example.so
-unix % tclsh
-% load ./example.so example
-% puts $My_variable
-3.0
-% fact 5
-120
-% my_mod 7 3
-1
-% get_time
-Sun Feb 11 23:01:07 1996
-
-%
-</pre></blockquote>
-
-The <tt> swig </tt> command produces a file <a href = "tutorial/example_wrap.html">
-<tt> example_wrap.c </tt> </a> that should be compiled and linked with
-the rest of the program. In this case, we have built a dynamically
-loadable extension that can be loaded into the Tcl interpreter using
-the 'load' command.
-
-<h3> Building a Python module </h3>
-
-Turning C code into a Python module is also easy. Simply do the following (shown for Irix, see the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl?SwigFaq/SharedLibraries">SWIG Wiki Shared Libraries</a> page for help with other operating systems):
-
-<blockquote> <pre>
-
-unix % swig -python example.i
-unix % gcc -c example.c example_wrap.c \
- -I/usr/local/include/python2.1
-unix % ld -shared example.o example_wrap.o -o _example.so
-</pre> </blockquote>
-
-We can now use the Python module as follows :
-<blockquote> <pre>
->>> import example
->>> example.fact(5)
-120
->>> example.my_mod(7,3)
-1
->>> example.get_time()
-'Sun Feb 11 23:01:07 1996'
->>>
-</pre>
-</blockquote>
-
-<h3> Building a Perl module </h3>
-You can also build a Perl5 module as follows (shown for Solaris, see the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl?SwigFaq/SharedLibraries">SWIG Wiki Shared Libraries</a> page for help with other operating systems):
-
-<blockquote><pre>
-unix % swig -perl5 example.i
-unix % gcc -c example.c example_wrap.c \
- -I/usr/lib/perl/solaris/5.003/CORE
-unix % ld -G example.o example_wrap.o -o example.so
-unix % perl
-use example;
-print $example::My_variable,"\n";
-print example::fact(5),"\n";
-print example::get_time(),"\n";
-<ctrl-d>
-3.0
-120
-Sun Feb 11 23:01:07 1996
-unix %
-</pre></blockquote>
-
-<h3> Building a Java module </h3>
-SWIG will also generate JNI code for accessing C/C++ code from Java. Here is an example building a Java module (shown for Cygwin, see the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl?SwigFaq/SharedLibraries">SWIG Wiki Shared Libraries</a> page for help with other operating systems):
-
-<blockquote><pre>
-$ swig -java example.i
-$ gcc -c example.c example_wrap.c -I/c/jdk1.3.1/include -I/c/jdk1.3.1/include/win32
-$ gcc -shared example.o example_wrap.o -mno-cygwin -Wl,--add-stdcall-alias -o example.dll
-$ cat main.java
-public class main {
- public static void main(String argv[]) {
- System.loadLibrary("example");
- System.out.println(example.getMy_variable());
- System.out.println(example.fact(5));
- System.out.println(example.get_time());
- }
-}
-$ javac main.java
-$ java main
-3.0
-120
-Mon Mar 4 18:20:31 2002
-$
-</pre></blockquote>
-
-<h3> Building a C# module </h3>
-SWIG will also generate code for accessing C/C++ code from C# using PInvoke. Here is an example building a C# module (shown for Linux, see the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl?SwigFaq/SharedLibraries">SWIG Wiki Shared Libraries</a> page for help with other operating systems). It uses the open source <a href="http://www.southern-storm.com.au/portable_net.html">DotGNU Portable.NET</a> C# compiler which runs on most Unix systems, but works equally well using other C# compilers:
-
-<blockquote><pre>
-$ swig -csharp example.i
-$ gcc -c -fpic example.c example_wrap.c
-$ gcc -shared example.o example_wrap.o -o libexample.so
-$ cscc -o runme *.cs
-$ cat runme.cs
-using System;
-public class runme {
- static void Main() {
- Console.WriteLine(example.My_variable);
- Console.WriteLine(example.fact(5));
- Console.WriteLine(example.get_time());
- }
-}
-$ ilrun runme
-3
-120
-Tue May 13 10:45:45 2003
-
-$
-</pre></blockquote>
-
-<h3> SWIG for the truly lazy </h3>
-
-As it turns out, it is not always necessary to write a special interface
-file. If you have a header file, you can often just include it directly in the
-SWIG interface. For example:
-
-<blockquote>
-<pre>
-%module example
-%{
-/* Includes the header in the wrapper code */
-#include "header.h"
-%}
-
-/* Parse the header file to generate wrappers */
-%include "header.h"
-</pre>
-</blockquote>
-
-Alternatively, some people might just include SWIG directives in a header
-file with conditional compilation. For example:
-
-<blockquote>
-<pre>
-#ifdef SWIG
-%module example
-%{
-#include "header.h"
-%}
-#endif
-
-extern int fact(int n);
-...
-</pre>
-</blockquote>
-
-<h3> Running SWIG under Microsoft Windows </h3>
-
-SWIG also works perfectly well under all known 32 bit versions of
-Windows including 95/98/NT/2000/XP. SWIG is typically invoked from
-the command prompt and can be used with NMAKE. Modules are typically
-compiled in the form of a DLL that can be dynamically loaded into Tcl,
-Python, or whatever language you are using. With a little work, SWIG
-can also be used as a custom build option within MS Developer Studio.
-
-<h3>That's it (well, more or less)</h3>
-
-That's about everything you need to know to get started. Here's the short checklist :
-
-<ul>
-<li> Make sure you specify a module name.
-<li> Use ANSI C/C++ syntax
-<li> Figure out how to compile a shared library module / dynamic link library (may require reading a few man
-pages for your compiler).
-<li> Relax.
-</ul>
-
-<h3>Surely there's more to it...</h3>
-
-The above example is intentionally simple, but the general idea
-extends to more complicated C/C++ programming tasks. In fact, it is
-important to know that SWIG is a fairly complete C++ compiler with
-support for nearly every language feature. This includes
-preprocessing, pointers, classes, inheritance, and even C++ templates.
-SWIG can also be used to package structures and classes into proxy
-classes in the target language---exposing the underlying functionality in a very
-natural manner.
-
-<p>
-To illustrate, suppose you wanted to wrap the following C++ data structure:
-
-<blockquote>
-<pre>
-// pair.h. A pair like the STL
-namespace std {
- template<class T1, class T2> struct pair {
- T1 first;
- T2 second;
- pair() : first(T1()), second(T2()) { };
- pair(const T1 &f, const T2 &s) : first(f), second(s) { }
- };
-}
-</pre>
-</blockquote>
-
-To wrap with SWIG, you might specify the following interface:
-
-<blockquote>
-<pre>
-// pair.i - SWIG interface
-%module pair
-%{
-#include "pair.h"
-%}
-
-// Ignore the default constructor
-%ignore std::pair::pair();
-
-// Parse the original header file
-%include "pair.h"
-
-// Instantiate some templates
-
-%template(pairii) std::pair<int,int>;
-%template(pairdi) std::pair<double,int>;
-</pre>
-</blockquote>
-
-Now, compiling (Python):
-
-<blockquote>
-<pre>
-$ swig -python -c++ pair.i
-$ c++ -c pair_wrap.c -I/usr/local/include/python2.1
-$ c++ -shared pair_wrap.o -o _pair.so
-$ python
-Python 2.1 (#3, Aug 20 2001, 15:41:42)
-[GCC 2.95.2 19991024 (release)] on sunos5
-Type "copyright", "credits" or "license" for more information.
->>> import pair
->>> a = pair.pairii(3,4)
->>> a.first
-3
->>> a.second
-4
->>> a.second = 16
->>> a.second
-16
->>> b = pair.pairdi(3.5,8)
->>> b.first
-3.5
->>> b.second
-8
-</pre>
-</blockquote>
-
diff --git a/swigweb/tutorial/example_wrap.html b/swigweb/tutorial/example_wrap.html
deleted file mode 100755
index 5112002..0000000
--- a/swigweb/tutorial/example_wrap.html
+++ /dev/null
@@ -1,176 +0,0 @@
-<html>
-<head> </head>
-<body BGCOLOR="#FFFFFF">
-<tt> <pre>
-
-/*
- * File : example_wrap.c
- * Thu Apr 4 13:11:45 1996
- *
- * This file was automatically generated by :
- * Simplified Wrapper and Interface Generator (SWIG)
- *
- * Copyright (c) 1995,1996
- * The Regents of the University of California and
- * The University of Utah
- *
- */
-
-/* Implementation : TCL */
-
-#define INCLUDE_TCL <tcl.h>
-#define INCLUDE_TK <tk.h>
-#include INCLUDE_TCL
-#include <string.h>
-#include <stdlib.h>
-static void _swig_make_hex(char *_c, void *_ptr, char *type) {
-static char _hex[16] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
- 'a', 'b', 'c', 'd', 'e', 'f' };
- unsigned long _p,_s;
- char _result[128], *_r;
- _r = _result;
- _p = (unsigned long) _ptr;
- if (_p > 0) {
- while (_p > 0) {
- _s = _p & 0xf;
- *(_r++) = _hex[_s];
- _p = _p >> 4;
- }
- *_r = '_';
- while (_r >= _result) *(_c++) = *(_r--);
- } else {
- strcpy(_c,"NULL");
- }
- if (_ptr) strcpy(_c,type);
-}
-static char *_swig_get_hex(char *_c, void **ptr, char *_t) {
- unsigned long _p;
- char *_tt;
- _p = 0;
- if (*_c == '_') {
- _c++;
- while (*_c) {
- if ((*_c >= '0') && (*_c <= '9')) _p = (_p << 4) + (*_c - '0');
- else if ((*_c >= 'a') && (*_c <= 'f')) _p = (_p << 4) + ((*_c - 'a') + 10);
- else break;
- _c++;
- }
- if (_p == 0) {
- return (char *) _c;
- }
- _tt = _c;
- if (_t) {
- if (strcmp(_c,_t)) return _tt;
- }
- *ptr = (void *) _p;
- return (char *) 0;
- } else {
- if (strcmp(_c,"NULL") == 0) {
- *ptr = (void *) 0;
- return (char *) 0;
- }
- else
- return _c;
- }
-}
-
-#define SWIG_init Wrap_Init
-
-
-
-
-/* A TCL_AppInit() function that lets you build a new copy
- * of tclsh.
- *
- * The macro WG_init contains the name of the initialization
- * function in the wrapper file.
- */
-
-#ifndef SWIG_RcFileName
-char *SWIG_RcFileName = "~/.myapprc";
-#endif
-
-#if TCL_MAJOR_VERSION == 7 && TCL_MINOR_VERSION >= 4
-int main(int argc, char **argv) {
-
- Tcl_Main(argc, argv, Tcl_AppInit);
- return(0);
-
-}
-#else
-extern int main();
-#endif
-
-int Tcl_AppInit(Tcl_Interp *interp){
- int SWIG_init(Tcl_Interp *); /* Forward reference */
-
- if (Tcl_Init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- /* Now initialize our functions */
-
- if (SWIG_init(interp) == TCL_ERROR)
- return TCL_ERROR;
-
- tcl_RcFileName = SWIG_RcFileName;
- return TCL_OK;
-}
-
-extern double My_variable;
-extern int fact(int );
-extern int mod(int ,int );
-extern char * get_time();
-int _wrap_tcl_fact(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
- int _result;
- int _arg0;
-
- if (argc != 2) {
- Tcl_SetResult(interp, "Wrong # args int : fact n ",TCL_STATIC);
- return TCL_ERROR;
- }
- _arg0 = (int ) atol(argv[1]);
- _result = fact(_arg0);
- sprintf(interp->result,"%ld", (long) _result);
- return TCL_OK;
-}
-int _wrap_tcl_mod(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
- int _result;
- int _arg0;
- int _arg1;
-
- if (argc != 3) {
- Tcl_SetResult(interp, "Wrong # args int : mod x y ",TCL_STATIC);
- return TCL_ERROR;
- }
- _arg0 = (int ) atol(argv[1]);
- _arg1 = (int ) atol(argv[2]);
- _result = mod(_arg0,_arg1);
- sprintf(interp->result,"%ld", (long) _result);
- return TCL_OK;
-}
-int _wrap_tcl_get_time(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) {
- char * _result;
-
- if (argc != 1) {
- Tcl_SetResult(interp, "Wrong # args char * : get_time ",TCL_STATIC);
- return TCL_ERROR;
- }
- _result = get_time();
- Tcl_SetResult(interp, _result, TCL_VOLATILE);
- return TCL_OK;
-}
-int Wrap_Init(Tcl_Interp *interp) {
- if (interp == 0)
- return TCL_ERROR;
- Tcl_LinkVar(interp, "My_variable", (char *) &My_variable, TCL_LINK_DOUBLE);
- Tcl_CreateCommand(interp, "fact", _wrap_tcl_fact, (ClientData) NULL, (Tcl_CmdDeleteProc *) NULL);
- Tcl_CreateCommand(interp, "mod", _wrap_tcl_mod, (ClientData) NULL, (Tcl_CmdDeleteProc *) NULL);
- Tcl_CreateCommand(interp, "get_time", _wrap_tcl_get_time, (ClientData) NULL, (Tcl_CmdDeleteProc *) NULL);
- return TCL_OK;
-}
-
-</pre> </tt> </body>
-</html>
-
-
-
diff --git a/swigweb/tutorial/example_wrap_perl5.html b/swigweb/tutorial/example_wrap_perl5.html
deleted file mode 100755
index 29141a1..0000000
--- a/swigweb/tutorial/example_wrap_perl5.html
+++ /dev/null
@@ -1,37 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>
-Simple Example</TITLE>
-<BODY BGCOLOR="#ffffff">
-<H1>Simple Example</H1>
-[ Module : swig, Package : swig ]<BR>
-
-<HR><H1> Contents </H1>
-<UL><LI> <A HREF="#s1_">1. My Commands</A>
-</UL>
-
-<A name="s1_">
-<HR><H2>1. My Commands</H2></A>
-<P><TT><B>$My_variable</B></TT>
-<BLOCKQUOTE>[ Global : double My_variable ]
-<BR> This is an interesting variable
-</BLOCKQUOTE>
-
-<P><TT><B>fact(n);</B></TT>
-<BLOCKQUOTE>[ returns int ]
-<BR> Computes n factorial
-</BLOCKQUOTE>
-
-<P><TT><B>my_mod(x,y);</B></TT>
-<BLOCKQUOTE>[ returns int ]
-<BR> Calculates x % y
-</BLOCKQUOTE>
-
-<P><TT><B>get_time();</B></TT>
-<BLOCKQUOTE>[ returns char * ]
-<BR> Returns the current time as a string
-</BLOCKQUOTE>
-
-
-</BODY>
-</HTML>
diff --git a/swigweb/tutorial/example_wrap_tcl.html b/swigweb/tutorial/example_wrap_tcl.html
deleted file mode 100755
index ad3f4ce..0000000
--- a/swigweb/tutorial/example_wrap_tcl.html
+++ /dev/null
@@ -1,36 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>
-Simple Example</TITLE>
-<BODY BGCOLOR="#ffffff">
-<H1>Simple Example</H1>
-
-<HR><H1> Contents </H1>
-<UL><LI> <A HREF="#s1_">1. My Commands</A>
-</UL>
-
-<A name="s1_">
-<HR><H2>1. My Commands</H2></A>
-<P><TT><B>$My_variable</B></TT>
-<BLOCKQUOTE>[ Global : double My_variable ]
-<BR> This is an interesting variable
-</BLOCKQUOTE>
-
-<P><TT><B>fact n </B></TT>
-<BLOCKQUOTE>[ returns int ]
-<BR> Computes n factorial
-</BLOCKQUOTE>
-
-<P><TT><B>my_mod x y </B></TT>
-<BLOCKQUOTE>[ returns int ]
-<BR> Calculates x % y
-</BLOCKQUOTE>
-
-<P><TT><B>get_time </B></TT>
-<BLOCKQUOTE>[ returns char * ]
-<BR> Returns the current time as a string
-</BLOCKQUOTE>
-
-
-</BODY>
-</HTML>
diff --git a/swigweb/y2k.ht b/swigweb/y2k.ht
deleted file mode 100644
index 1ba6d0e..0000000
--- a/swigweb/y2k.ht
+++ /dev/null
@@ -1,26 +0,0 @@
-SWIG2K
-
-<p><img src="images/y2k.png" alt="Y2K">
-
-<p>
-SWIG does not use the date and should not be affected by Y2K.
-However, like any development tool, SWIG will not prevent you from
-creating a buggy application. SWIG is distributed under the following
-terms :
-
-<pre>
-
-IN NO EVENT SHALL THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, THE
-UNIVERSITY OF UTAH OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
-PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
-EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
-THE POSSIBILITY OF SUCH DAMAGE.
-
-THE AUTHOR, THE UNIVERSITY OF CALIFORNIA, AND THE UNIVERSITY OF UTAH
-SPECIFICALLY DISCLAIM ANY WARRANTIES,INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND
-THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
-SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
-</pre>
