jyapayne/swig
Watch
1
0
Fork
You've already forked swig
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

- Updated documentation to use CSS and <div> instead of blockquotes

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@7003 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz 2005-02-26 02:56:29 +00:00
commit 4737da0be0
35 changed files with 8004 additions and 4090 deletions
Download patch file Download diff file Expand all files Collapse all files

139
SWIG/Doc/Manual/Arguments.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Argument Handling</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Arguments"></a>9 Argument Handling</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Arguments_nn2">The typemaps.i library</a>
<ul>
@ -23,6 +25,7 @@
<li><a href="#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -44,19 +47,23 @@ describes some of the techniques for doing this.
<H2><a name="Arguments_nn2"></a>9.1 The typemaps.i library</H2>
<p>
This section describes the <tt>typemaps.i</tt> library file--commonly used to
change certain properties of argument conversion.
</p>
<H3><a name="Arguments_nn3"></a>9.1.1 Introduction</H3>
<p>
Suppose you had a C function like this:
</p>
<blockquote><pre>
<div class="code"><pre>
void add(double a, double b, double *result) {
*result = a + b;
}
</pre></blockquote>
</pre></div>
<p>
From reading the source code, it is clear that the function is storing
@ -70,14 +77,14 @@ One way to deal with this is to use the
<tt>typemaps.i</tt> library file and write interface code like this:
</p>
<blockquote><pre>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
%apply double *OUTPUT { double *result };
extern void add(double a, double b, double *result);
</pre></blockquote>
</pre></div>
<p>
The <tt>%apply</tt> directive tells SWIG that you are going to apply
@ -91,25 +98,27 @@ When the resulting module is created, you can now use the function
like this (shown for Python):
</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; a = add(3,4)
&gt;&gt;&gt; print a
7
&gt;&gt;&gt;
</pre></blockquote>
</pre></div>
<p>
In this case, you can see how the output value normally returned in
the third argument has magically been transformed into a function
return value. Clearly this makes the function much easier to use
since it is no longer necessary to manufacture a special <tt>double
*</tt> object and pass it to the function somehow.
</p>
<p>
Once a typemap has been applied to a type, it stays in effect for all future occurrences
of the type and name. For example, you could write the following:
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
@ -119,16 +128,18 @@ extern void sub(double a, double b, double *result);
extern void mul(double a, double b, double *result);
extern void div(double a, double b, double *result);
...
</pre></blockquote>
</pre></div>
<p>
In this case, the <tt>double *OUTPUT</tt> rule is applied to all of the functions that follow.
</p>
<p>
Typemap transformations can even be extended to multiple return values.
For example, consider this code:
</p>
<blockquote>
<div class="code">
<pre>
%include "typemaps.i"
%apply int *OUTPUT { int *width, int *height };
@ -136,11 +147,13 @@ For example, consider this code:
// Returns a pair (width,height)
void getwinsize(int winid, int *width, int *height);
</pre>
</blockquote>
</div>
<p>
In this case, the function returns multiple values, allowing it to be used like this:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt;&gt;&gt; w,h = genwinsize(wid)
&gt;&gt;&gt; print w
400
@ -148,7 +161,7 @@ In this case, the function returns multiple values, allowing it to be used like
300
&gt;&gt;&gt;
</pre>
</blockquote>
</div>
<p>
It should also be noted that although the <tt>%apply</tt> directive is
@ -156,22 +169,24 @@ used to associate typemap rules to datatypes, you can also use the
rule names directly in arguments. For example, you could write this:
</p>
<blockquote><pre>
<div class="code"><pre>
// Simple example using typemaps
%module example
%include "typemaps.i"
extern void add(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
Typemaps stay in effect until they are explicitly deleted or redefined to something
else. To clear a typemap, the <tt>%clear</tt> directive should be used. For example:
</p>
<blockquote>
<div class="code">
<pre>
%clear double *result; // Remove all typemaps for double *result
</pre>
</blockquote>
</div>
<H3><a name="Arguments_nn4"></a>9.1.2 Input parameters</H3>
@ -181,7 +196,7 @@ The following typemaps instruct SWIG that a pointer really only holds a single
input value:
</p>
<blockquote><pre>
<div class="code"><pre>
int *INPUT
short *INPUT
long *INPUT
@ -190,34 +205,38 @@ unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT
</pre></blockquote>
</pre></div>
<p>
When used, it allows values to be passed instead of pointers. For example, consider this
function:
</p>
<blockquote><pre>
<div class="code"><pre>
double add(double *a, double *b) {
return *a+*b;
}
</pre></blockquote>
</pre></div>
<p>
Now, consider this SWIG interface:
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
extern double add(double *INPUT, double *INPUT);
</pre></blockquote>
</pre></div>
<p>
When the function is used in the scripting language interpreter, it will work like this:
</p>
<blockquote><pre>
<div class="code"><pre>
result = add(3,4)
</pre></blockquote>
</pre></div>
<H3><a name="Arguments_nn5"></a>9.1.3 Output parameters</H3>
@ -228,7 +247,7 @@ function. When used, you do not need to supply the argument when
calling the function. Instead, one or more output values are returned.
</p>
<blockquote><pre>
<div class="code"><pre>
int *OUTPUT
short *OUTPUT
long *OUTPUT
@ -238,47 +257,51 @@ unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT
</pre></blockquote>
</pre></div>
<p>
These methods can be used as shown in an earlier example. For example, if you have this C function :</p>
<blockquote><pre>
<div class="code"><pre>
void add(double a, double b, double *c) {
*c = a+b;
}
</pre></blockquote>
</pre></div>
<p>
A SWIG interface file might look like this :</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include "typemaps.i"
...
extern void add(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
In this case, only a single output value is returned, but this is not
a restriction. An arbitrary number of output values can be returned by applying
the output rules to more than one argument (as shown previously).
</p>
<p>
If the function also returns a value, it is returned along with the argument. For example,
if you had this:
</p>
<blockquote><pre>
<div class="code"><pre>
extern int foo(double a, double b, double *OUTPUT);
</pre></blockquote>
</pre></div>
<p>
The function will return two values like this:
</p>
<blockquote>
<div class="code">
<pre>
iresult, dresult = foo(3.5, 2)
</pre>
</blockquote>
</div>
<H3><a name="Arguments_nn6"></a>9.1.4 Input/Output parameters</H3>
@ -287,7 +310,7 @@ iresult, dresult = foo(3.5, 2)
When a pointer serves as both an input and output value you can use
the following typemaps :</p>
<blockquote><pre>
<div class="code"><pre>
int *INOUT
short *INOUT
long *INOUT
@ -297,43 +320,45 @@ unsigned long *INOUT
double *INOUT
float *INOUT
</pre></blockquote>
</pre></div>
<p>
A C function that uses this might be something like this:</p>
<blockquote><pre>
<div class="code"><pre>
void negate(double *x) {
*x = -(*x);
}
</pre></blockquote>
</pre></div>
<p>
To make x function as both and input and output value, declare the
function like this in an interface file :</p>
<blockquote><pre>
<div class="code"><pre>
%module example
%include typemaps.i
...
extern void negate(double *INOUT);
</pre></blockquote>
</pre></div>
<p>
Now within a script, you can simply call the function normally :</p>
<blockquote><pre>
<div class="code"><pre>
a = negate(3); # a = -3 after calling this
</pre></blockquote>
</pre></div>
<p>
One subtle point of the <tt>INOUT</tt> rule is that many scripting languages
enforce mutability constraints on primitive objects (meaning that simple objects
like integers and strings aren't supposed to change). Because of this, you can't
just modify the object's value in place as the underlying C function does in this example.
Therefore, the <tt>INOUT</tt> rule returns the modified value as a new object
rather than directly overwriting the value of the original input object.
</p>
<p>
<b>Compatibility note :</b> The <tt>INOUT</tt> rule used to be known as <tt>BOTH</tt> in earlier versions of
@ -348,7 +373,7 @@ As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>
<tt>INOUT</tt> typemaps to different argument names. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
// Make double *result an output value
%apply double *OUTPUT { double *result };
@ -358,25 +383,31 @@ As previously shown, the <tt>%apply</tt> directive can be used to apply the <tt>
// Make long *x inout
%apply long *INOUT {long *x};
</pre></blockquote>
</pre></div>
<p>
To clear a rule, the <tt>%clear</tt> directive is used:
</p>
<blockquote><pre>
<div class="code"><pre>
%clear double *result;
%clear Int32 *in, long *x;
</pre></blockquote>
</pre></div>
<p>
Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the
file or a matching <tt>%clear</tt> declaration.
</p>
<H2><a name="Arguments_nn8"></a>9.2 Applying constraints to input values</H2>
<p>
In addition to changing the handling of various input values, it is
also possible to use typemaps 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.
</p>
<H3><a name="Arguments_nn9"></a>9.2.1 Simple constraint example</H3>
@ -385,7 +416,7 @@ can be accomplished including the <tt>constraints.i</tt> library file.
The constraints library is best illustrated by the following interface
file :</p>
<blockquote><pre>
<div class="code"><pre>
// Interface file with constraints
%module example
%include "constraints.i"
@ -396,7 +427,7 @@ 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>
</pre></div>
<p>
The behavior of this file is exactly as you would expect. If any of
@ -410,7 +441,7 @@ values, prevent mysterious program crashes and so on.</p>
<p>
The following constraints are currently available</p>
<blockquote><pre>
<div class="code"><pre>
POSITIVE Any number &gt; 0 (not zero)
NEGATIVE Any number &lt; 0 (not zero)
NONNEGATIVE Any number &gt;= 0
@ -418,7 +449,7 @@ NONPOSITIVE Any number &lt;= 0
NONZERO Nonzero number
NONNULL Non-NULL pointer (pointers only).
</pre></blockquote>
</pre></div>
<H3><a name="Arguments_nn11"></a>9.2.3 Applying constraints to new datatypes</H3>
@ -428,24 +459,24 @@ The constraints library only supports the primitive C datatypes, but it
is easy to apply it to new datatypes using <tt>%apply</tt>. For
example :</p>
<blockquote><pre>
<div class="code"><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>
</pre></div>
<p>
The special types of "Number" and "Pointer" can be applied to any
numeric and pointer variable type respectively. To later remove a
constraint, the <tt>%clear</tt> directive can be used :</p>
<blockquote><pre>
<div class="code"><pre>
%clear Real in;
%clear Vector *;
</pre></blockquote>
</pre></div>
</body>
</html>

37
SWIG/Doc/Manual/CSharp.html
View file

@ -2,19 +2,24 @@
<html>
<head>
<title>SWIG and C#</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#FFFFFF">
<H1><a name="CSharp"></a>16 SWIG and C#</H1>
<!-- INDEX -->
<div class="sectiontoc">
</div>
<!-- INDEX -->
<p>
The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages.
The wrapper code implementation uses the Platform Invoke (PINVOKE) interface to access natively compiled C/C++ code.
The PINVOKE interface has been chosen over Microsoft's Managed C++ interface as it is portable to both Microsoft Windows and non-Microsoft platforms.
PINVOKE is part of the ECMA/ISO C# specification.
Swig C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using Mono and Portable.NET.
</p>
<p>
The C# module is very similar to the Java module, so until some documentation has been written,
@ -75,9 +80,9 @@ Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
</li>
<li>
Typemap equivalent names:
<p>Typemap equivalent names:</p>
<blockquote><pre>
<div class="code"><pre>
jni -&gt; ctype
jtype -&gt; imtype
jstype -&gt; cstype
@ -92,48 +97,48 @@ javabody -&gt; csbody
javafinalize -&gt; csfinalize
javadestruct -&gt; csdestruct
javadestruct_derived -&gt; csdestruct_derived
</pre></blockquote>
</pre></div>
</li>
<li>
Additional typemaps:
<p>Additional typemaps:</p>
<blockquote><pre>
<div class="code"><pre>
csvarin C# code property set typemap
csvarout C# code property get typemap
</pre></blockquote>
</pre></div>
</li>
<li>
Feature equivalent names:
<blockquote><pre>
<p>Feature equivalent names:</p>
<div class="code"><pre>
%javaconst -&gt; %csconst
%javaconstvalue -&gt; %csconstvalue
%javamethodmodifiers -&gt; %csmethodmodifiers
</pre></blockquote>
</pre></div>
</li>
<li>
Pragma equivalent names:
<blockquote><pre>
<p>Pragma equivalent names:</p>
<div class="code"><pre>
%pragma(java) -&gt; %pragma(csharp)
jniclassbase -&gt; imclassbase
jniclassclassmodifiers -&gt; imclassclassmodifiers
jniclasscode -&gt; imclasscode
jniclassimports -&gt; imclassimports
jniclassinterfaces -&gt; imclassinterfaces
</pre></blockquote>
</pre></div>
</li>
<li>
Special variable equivalent names:
<blockquote><pre>
<p>Special variable equivalent names:</p>
<div class="code"><pre>
$javaclassname -&gt; $csclassname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
</pre></blockquote>
</pre></div>
</li>
</ul>
@ -145,7 +150,9 @@ The special variable will get translated into the value specified by the <tt>-dl
if specified, otherwise it is equivalent to the <b>$module</b> special variable.
</p>
<p>
The intermediary classname has <tt>PINVOKE</tt> appended after the module name instead of <tt>JNI</tt>, for example <tt>modulenamePINVOKE</tt>.
</p>
<p>
The directory <tt>Examples/csharp</tt> has a number of simple examples.

34
SWIG/Doc/Manual/Chicken.html
View file

@ -3,12 +3,14 @@
<html>
<head>
<title>SWIG and Chicken</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Chicken"></a>17 SWIG and Chicken</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Chicken_nn2">Preliminaries</a>
<ul>
@ -33,6 +35,7 @@
<li><a href="#Chicken_nn16">Pointers</a>
<li><a href="#Chicken_nn17">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->
@ -90,9 +93,9 @@
the -chicken option.
</p>
<blockquote>
<div class="code">
<pre>% swig -chicken example.i</pre>
</blockquote>
</div>
<p>
To allow the wrapper to take advantage of future CHICKEN code
@ -102,9 +105,9 @@
be compiled to C using your system's CHICKEN compiler.
</p>
<blockquote>
<div class="code">
<pre>% chicken example.scm -output-file oexample.c</pre>
</blockquote>
</div>
<p>
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
@ -120,9 +123,9 @@
the -chicken -c++ option.
</p>
<blockquote>
<div class="code">
<pre>% swig -chicken -c++ example.i</pre>
</blockquote>
</div>
<p>
This will generate <tt>example_wrap.cxx</tt> and
@ -130,9 +133,9 @@
compiled to C using your system's CHICKEN compiler.
</p>
<blockquote>
<div class="code">
<pre>% chicken example.scm -output-file oexample.c</pre>
</blockquote>
</div>
<p>
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
@ -163,6 +166,7 @@
<H3><a name="Chicken_nn7"></a>17.2.2 Modules</H3>
<p>
The name of the module must be declared one of two ways:
<ul>
<li>Placing <tt>%module example</tt> in the SWIG interface
@ -170,6 +174,8 @@
<li>Using <tt>-module example</tt> on the SWIG command
line.</li>
</ul>
<p>
The generated example.scm file then exports <code>(declare (unit modulename))</code>.
If you do not want SWIG to export the <code>(declare (unit modulename))</code>, pass
the -nounit option to SWIG.
@ -230,13 +236,13 @@
<p>
The author of TinyCLOS, Gregor Kiczales, describes TinyCLOS as:
</p>
<blockquote>
<div class="code">
Tiny CLOS is a Scheme implementation of a `kernelized' CLOS, with a
metaobject protocol. The implementation is even simpler than
the simple CLOS found in `The Art of the Metaobject Protocol,'
weighing in at around 850 lines of code, including (some)
comments and documentation.
</blockquote>
</div>
<p>
Almost all good Scheme books describe how to use metaobjects and
@ -306,13 +312,13 @@
in example.i and the C functions being wrapped are in example_impl.c.
</p>
<blockquote>
<div class="code">
<pre>
$ swig -chicken example.i
$ csc -svk example.scm example_impl.c example_wrap.c
$ csi example.so test_script.scm
</pre>
</blockquote>
</div>
<p>
You must be careful not to name the example_impl.c file example.c because
@ -330,13 +336,13 @@
<p>Again, we can easily use csc to build a binary.</p>
<blockquote>
<div class="code">
<pre>
$ swig -chicken example.i
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
$ ./example
</pre>
</blockquote>
</div>
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2>

71
SWIG/Doc/Manual/Contents.html
View file

@ -12,6 +12,7 @@
<h3><a href="Preface.html#Preface">1 Preface</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Preface.html#Preface_nn2">Introduction</a>
<li><a href="Preface.html#Preface_nn3">Special Introduction for Version 1.3</a>
@ -24,11 +25,13 @@
<li><a href="Preface.html#Preface_nn10">Credits</a>
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Introduction.html#Introduction">2 Introduction</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Introduction.html#Introduction_nn2">What is SWIG?</a>
<li><a href="Introduction.html#Introduction_nn3">Why use SWIG?</a>
@ -46,11 +49,13 @@
<li><a href="Introduction.html#Introduction_nn12">Hands off code generation</a>
<li><a href="Introduction.html#Introduction_nn13">SWIG and freedom</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Windows.html#Windows">3 Getting started on Windows </a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Windows.html#Windows_nn2">Installation on Windows</a>
<ul>
@ -80,11 +85,13 @@
<li><a href="Windows.html#examples_cygwin">Running the examples on Windows using Cygwin</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Scripting.html#Scripting">4 Scripting Languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Scripting.html#Scripting_nn2">The two language view of the world</a>
<li><a href="Scripting.html#Scripting_nn3">How does a scripting language talk to C?</a>
@ -102,11 +109,13 @@
<li><a href="Scripting.html#Scripting_nn12">Static linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="SWIG.html#SWIG">5 SWIG Basics</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="SWIG.html#SWIG_nn2">Running SWIG</a>
<ul>
@ -172,11 +181,13 @@
<li><a href="SWIG.html#SWIG_nn50">What to do with main()</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="SWIGPlus.html#SWIGPlus">6 SWIG and C++</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn2">Comments on C++ Wrapping</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn3">Approach</a>
@ -226,11 +237,13 @@
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Preprocessor.html#Preprocessor">7 Preprocessing</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Preprocessor.html#Preprocessor_nn2">File inclusion</a>
<li><a href="Preprocessor.html#Preprocessor_nn3">File imports</a>
@ -242,11 +255,13 @@
<li><a href="Preprocessor.html#Preprocessor_nn9">Preprocessing and { ... }</a>
<li><a href="Preprocessor.html#Preprocessor_nn10">Viewing preprocessor output</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Library.html#Library">8 SWIG library</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Library.html#Library_nn2">The %include directive and library search path</a>
<li><a href="Library.html#Library_nn3">C Arrays and Pointers</a>
@ -273,11 +288,13 @@
<li><a href="Library.html#Library_nn17">exception.i</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Arguments.html#Arguments">9 Argument Handling</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Arguments.html#Arguments_nn2">The typemaps.i library</a>
<ul>
@ -294,11 +311,13 @@
<li><a href="Arguments.html#Arguments_nn11">Applying constraints to new datatypes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Typemaps.html#Typemaps">10 Typemaps</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Typemaps.html#Typemaps_nn2">Introduction</a>
<ul>
@ -355,17 +374,23 @@
</ul>
<li><a href="Typemaps.html#Typemaps_nn42">Multi-argument typemaps</a>
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn45">Implementation</a>
<li><a href="Typemaps.html#Typemaps_nn46">Usage</a>
</ul>
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="Typemaps.html#Typemaps_nn45">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="Typemaps.html#Typemaps_nn46">Reducing wrapper code size</a>
<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn48">Where to go for more information?</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Customization.html#Customization">11 Customization Features</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Customization.html#exception">Exception handling with %exception</a>
<ul>
@ -382,22 +407,26 @@
<li><a href="Customization.html#features_example">Feature example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Contract.html#Contract">12 Contracts</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Contract.html#Contract_nn2">The %contract directive</a>
<li><a href="Contract.html#Contract_nn3">%contract and classes</a>
<li><a href="Contract.html#Contract_nn4">Constant aggregation and %aggregate_check</a>
<li><a href="Contract.html#Contract_nn5">Notes</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Varargs.html#Varargs">13 Variable Length Arguments</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Varargs.html#Varargs_nn2">Introduction</a>
<li><a href="Varargs.html#Varargs_nn3">The Problem</a>
@ -409,11 +438,13 @@
<li><a href="Varargs.html#Varargs_nn9">C++ Issues</a>
<li><a href="Varargs.html#Varargs_nn10">Discussion</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Warnings.html#Warnings">14 Warning Messages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Warnings.html#Warnings_nn2">Introduction</a>
<li><a href="Warnings.html#Warnings_nn3">Warning message suppression</a>
@ -434,27 +465,34 @@
</ul>
<li><a href="Warnings.html#Warnings_nn17">History</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Modules.html#Modules">15 Working with Modules</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
<li><a href="Modules.html#Modules_nn3">A word of caution about static libraries</a>
<li><a href="Modules.html#Modules_nn4">References</a>
<li><a href="Modules.html#Modules_nn5">Reducing the wrapper file size</a>
<li><a href="Modules.html#external_run_time">External access to the runtime</a>
<li><a href="Modules.html#Modules_nn4">A word of caution about static libraries</a>
<li><a href="Modules.html#Modules_nn5">References</a>
<li><a href="Modules.html#Modules_nn6">Reducing the wrapper file size</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="CSharp.html#CSharp">16 SWIG and C#</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
</div>
<!-- INDEX -->
<h3><a href="Chicken.html#Chicken">17 SWIG and Chicken</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Chicken.html#Chicken_nn2">Preliminaries</a>
<ul>
@ -479,11 +517,13 @@
<li><a href="Chicken.html#Chicken_nn16">Pointers</a>
<li><a href="Chicken.html#Chicken_nn17">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">18 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Guile.html#Guile_nn2">Meaning of "Module"</a>
<li><a href="Guile.html#Guile_nn3">Using the SCM or GH Guile API</a>
@ -512,11 +552,13 @@
<li><a href="Guile.html#Guile_nn21">Linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">19 SWIG and Java</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Java.html#java_overview">Overview</a>
<li><a href="Java.html#java_preliminaries">Preliminaries</a>
@ -641,11 +683,13 @@
</ul>
<li><a href="Java.html#java_examples">Examples</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Modula3.html#Modula3">20 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modula3.html#modula3_overview">Overview</a>
<ul>
@ -680,19 +724,23 @@
</ul>
<li><a href="Modula3.html#remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">21 SWIG and MzScheme</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Mzscheme.html#MzScheme_nn2">Creating native MzScheme structures</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">22 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Ocaml.html#Ocaml_nn2">Preliminaries</a>
<ul>
@ -737,11 +785,13 @@
<li><a href="Ocaml.html#Ocaml_nn31">Exceptions</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">23 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Perl5.html#Perl5_nn2">Overview</a>
<li><a href="Perl5.html#Perl5_nn3">Preliminaries</a>
@ -801,11 +851,13 @@
<li><a href="Perl5.html#Perl5_nn46">Modifying the proxy methods</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">24 SWIG and PHP4</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Php.html#Php_nn2">Preliminaries</a>
<li><a href="Php.html#Php_nn3">Building PHP4 Extensions</a>
@ -825,11 +877,13 @@
<li><a href="Php.html#Php_nn16">To be furthered...</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">25 SWIG and Pike</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Pike.html#Pike_nn2">Preliminaries</a>
<ul>
@ -847,11 +901,13 @@
<li><a href="Pike.html#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">26 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Python.html#Python_nn2">Overview</a>
<li><a href="Python.html#Python_nn3">Preliminaries</a>
@ -889,7 +945,7 @@
<li><a href="Python.html#Python_nn30">Memory management</a>
<li><a href="Python.html#Python_nn31">Python 2.2 and classic classes</a>
</ul>
<li><a href="Python.html#directors">Cross language polymorphism (experimental)</a>
<li><a href="Python.html#directors">Cross language polymorphism</a>
<ul>
<li><a href="Python.html#Python_nn33">Enabling directors</a>
<li><a href="Python.html#Python_nn34">Director classes</a>
@ -945,11 +1001,13 @@
</ul>
<li><a href="Python.html#Python_nn72">Python Packages</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">27 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Ruby.html#Ruby_nn2">Preliminaries</a>
<ul>
@ -1020,11 +1078,13 @@
<li><a href="Ruby.html#Ruby_nn51">Interacting with Ruby's Garbage Collector</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">28 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Tcl.html#Tcl_nn2">Preliminaries</a>
<ul>
@ -1083,11 +1143,13 @@
<li><a href="Tcl.html#Tcl_nn45">Proxy classes</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">29 Extending SWIG</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Extending.html#Extending_nn2">Introduction</a>
<li><a href="Extending.html#Extending_nn3">Prerequisites</a>
@ -1145,6 +1207,7 @@
</ul>
<li><a href="Extending.html#Extending_nn46">Guide to parse tree nodes</a>
</ul>
</div>
<!-- INDEX -->

72
SWIG/Doc/Manual/Contract.html
View file

@ -2,27 +2,32 @@
<html>
<head>
<title>Contract Checking</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Contract"></a>12 Contracts</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Contract_nn2">The %contract directive</a>
<li><a href="#Contract_nn3">%contract and classes</a>
<li><a href="#Contract_nn4">Constant aggregation and %aggregate_check</a>
<li><a href="#Contract_nn5">Notes</a>
</ul>
</div>
<!-- INDEX -->
<p>
A common problem that arises when wrapping C libraries is that of maintaining
reliability and checking for errors. The fact of the matter is that many
C programs are notorious for not providing error checks. Not only that,
when you expose the internals of an application as a library, it
often becomes possible to crash it simply by providing bad inputs or
using it in a way that wasn't intended.
</p>
<p>
This chapter describes SWIG's support for software contracts. In the context
@ -36,10 +41,12 @@ generated rather than having the program continue to execute.
<H2><a name="Contract_nn2"></a>12.1 The %contract directive</H2>
<p>
Contracts are added to a declaration using the %contract directive. Here
is a simple example:
</p>
<blockquote>
<div class="code">
<pre>
%contract sqrt(double x) {
require:
@ -51,8 +58,9 @@ ensure:
...
double sqrt(double);
</pre>
</blockquote>
</div>
<p>
In this case, a contract is being added to the <tt>sqrt()</tt> function.
The <tt>%contract</tt> directive must always appear before the declaration
in question. Within the contract there are two sections, both of which
@ -62,6 +70,7 @@ Typically, this is used to check argument values. The <tt>ensure:</tt> section
specifies conditions that must hold after the function is called. This is
often used to check return values or the state of the program. In both
cases, the conditions that must hold must be specified as boolean expressions.
</p>
<p>
In the above example, we're simply making sure that sqrt() returns a non-negative
@ -73,7 +82,7 @@ Once a contract has been specified, it modifies the behavior of the
resulting module. For example:
</p>
<blockquote>
<div class="code">
<pre>
&gt;&gt;&gt; example.sqrt(2)
1.4142135623730951
@ -83,14 +92,16 @@ Traceback (most recent call last):
RuntimeError: Contract violation: require: (arg1&gt;=0)
&gt;&gt;&gt;
</pre>
</blockquote>
</div>
<H2><a name="Contract_nn3"></a>12.2 %contract and classes</H2>
<p>
The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example:
</p>
<blockquote>
<div class="code">
<pre>
%contract Foo::bar(int x, int y) {
require:
@ -110,23 +121,27 @@ public:
int bar(int, int);
};
</pre>
</blockquote>
</div>
<p>
The way in which <tt>%contract</tt> is applied is exactly the same as the <tt>%feature</tt> directive.
Thus, any contract that you specified for a base class will also be attached to inherited methods. For example:
</p>
<blockquote>
<div class="code">
<pre>
class Spam : public Foo {
public:
int bar(int,int); // Gets contract defined for Foo::bar(int,int)
};
</pre>
</blockquote>
</div>
<p>
In addition to this, separate contracts can be applied to both the base class and a derived class. For example:
</p>
<blockquote>
<div class="code">
<pre>
%contract Foo::bar(int x, int) {
require:
@ -148,20 +163,24 @@ public:
int bar(int,int); // Gets Foo::bar and Spam::bar contract
};
</pre>
</blockquote>
</div>
<p>
When more than one contract is applied, the conditions specified in a
"require:" section are combined together using a logical-AND operation.
In other words conditions specified for the base class and conditions
specified for the derived class all must hold. In the above example,
this means that both the arguments to <tt>Spam::bar</tt> must be positive.
</p>
<H2><a name="Contract_nn4"></a>12.3 Constant aggregation and %aggregate_check</H2>
<p>
Consider an interface file that contains the following code:
</p>
<blockquote>
<div class="code">
<pre>
#define UP 1
#define DOWN 2
@ -170,30 +189,36 @@ Consider an interface file that contains the following code:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
One thing you might want to do is impose a constraint on the direction parameter to
make sure it's one of a few accepted values. To do that, SWIG provides an easy to
use macro %aggregate_check() that works like this:
</p>
<blockquote>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
</pre>
</blockquote>
</div>
<p>
This merely defines a utility function of the form
</p>
<blockquote>
<div class="code">
<pre>
int check_direction(int x);
</pre>
</blockquote>
</div>
<p>
That checks the argument x to see if it is one of the values listed. This utility
function can be used in contracts. For example:
</p>
<blockquote>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
@ -209,10 +234,13 @@ require:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
Alternatively, it can be used in typemaps and other directives. For example:
<blockquote>
</p>
<div class="code">
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
@ -227,16 +255,20 @@ Alternatively, it can be used in typemaps and other directives. For example:
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
</div>
<p>
Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future
release.
</p>
<H2><a name="Contract_nn5"></a>12.4 Notes</H2>
<p>
Contract support was implemented by Songyan (Tiger) Feng and first appeared
in SWIG-1.3.20.
</p>
</body>
</html>

191
SWIG/Doc/Manual/Customization.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Customization Features</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Customization"></a>11 Customization Features</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#exception">Exception handling with %exception</a>
<ul>
@ -23,10 +25,12 @@
<li><a href="#features_example">Feature example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
In many cases, it is desirable to change the default wrapping of
particular declarations in an interface. For example, you might want
to provide hooks for catching C++ exceptions, add assertions, or
@ -34,6 +38,7 @@ provide hints to the underlying code generator. This chapter
describes some of these customization techniques. First, a discussion
of exception handling is presented. Then, a more general-purpose
customization mechanism known as "features" is described.
</p>
<H2><a name="exception"></a>11.1 Exception handling with %exception</H2>
@ -43,7 +48,7 @@ The <tt>%exception</tt> directive allows you to define a general purpose excepti
handler. For example, you can specify the following:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
try {
$action
@ -53,7 +58,7 @@ handler. For example, you can specify the following:
return NULL;
}
}
</pre></blockquote>
</pre></div>
<p>
When defined, the code enclosed in braces is inserted directly into the low-level wrapper
@ -63,9 +68,9 @@ remains in effect until it is explicitly deleted. This is done by using either
or <tt>%noexception</tt> with no code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception; // Deletes any previously defined handler
</pre></blockquote>
</pre></div>
<p>
<b>Compatibility note:</b> Previous versions of SWIG used a special directive <tt>%except</tt>
@ -81,7 +86,7 @@ C has no formal exception handling mechanism so there are several approaches tha
used. A somewhat common technique is to simply set a special error code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : except.c */
static char error_message[256];
@ -100,14 +105,14 @@ char *check_exception() {
else return NULL;
}
</pre></blockquote>
</pre></div>
<p>
To use these functions, functions simply call
<tt>throw_exception()</tt> to indicate an error occurred. For example
:</p>
<blockquote><pre>
<div class="code"><pre>
double inv(double x) {
if (x != 0) return 1.0/x;
else {
@ -116,13 +121,13 @@ double inv(double x) {
}
}
</pre></blockquote>
</pre></div>
<p>
To catch the exception, you can write a simple exception handler such
as the following (shown for Perl5) :</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
char *err;
clear_exception();
@ -131,7 +136,7 @@ as the following (shown for Perl5) :</p>
croak(err);
}
}
</pre></blockquote>
</pre></div>
<p>
In this case, when an error occurs, it is translated into a Perl error.
@ -140,11 +145,13 @@ In this case, when an error occurs, it is translated into a Perl error.
<H3><a name="Customization_nn4"></a>11.1.2 Exception handling with longjmp()</H3>
<p>
Exception handling can also be added to C code using the
<tt>&lt;setjmp.h&gt;</tt> library. Here is a minimalistic implementation that
relies on the C preprocessor :
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : except.c
Just the declaration of a few global variables we're going to use */
@ -168,23 +175,23 @@ extern int exception_status;
#define DivisionByZero 2
#define OutOfMemory 3
</pre></blockquote>
</pre></div>
<p>
Now, within a C program, you can do the following :</p>
<blockquote><pre>
<div class="code"><pre>
double inv(double x) {
if (x) return 1.0/x;
else throw(DivisionByZero);
}
</pre></blockquote>
</pre></div>
<p>
Finally, to create a SWIG exception handler, write the following :</p>
<blockquote><pre>
<div class="code"><pre>
%{
#include "except.h"
%}
@ -202,10 +209,12 @@ Finally, to create a SWIG exception handler, write the following :</p>
croak("Unknown exception");
}
}
</pre></blockquote>
</pre></div>
<p>
Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to
modify it to handle nested <tt>try</tt> declarations.
</p>
<H3><a name="Customization_nn5"></a>11.1.3 Handling C++ exceptions</H3>
@ -214,7 +223,7 @@ modify it to handle nested <tt>try</tt> declarations.
Handling C++ exceptions is also straightforward. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
try {
$action
@ -229,27 +238,29 @@ Handling C++ exceptions is also straightforward. For example:
}
}
</pre></blockquote>
</pre></div>
<p>
The exception types need to be declared as classes elsewhere, possibly
in a header file :</p>
<blockquote><pre>
<div class="code"><pre>
class RangeError {};
class DivisionByZero {};
class OutOfMemory {};
</pre>
</blockquote>
</div>
<H3><a name="Customization_nn6"></a>11.1.4 Defining different exception handlers</H3>
<p>
By default, the <tt>%exception</tt> directive creates an exception
handler that is used for all wrapper functions that follow it. Unless
there is a well-defined (and simple) error handling mechanism in place,
defining one universal exception handler may be unwieldy and result
in excessive code bloat since the handler is inlined into each wrapper function.
</p>
<p>
To fix this, you can be more selective about how you use the
@ -257,7 +268,7 @@ To fix this, you can be more selective about how you use the
critical pieces of code. For example:
</p>
<blockquote><pre>
<div class="code"><pre>
%exception {
... your exception handler ...
}
@ -266,12 +277,14 @@ critical pieces of code. For example:
%exception;
/* Define non-critical operations that don't throw exceptions */
</pre></blockquote>
</pre></div>
<p>
More precise control over exception handling can be obtained by attaching an exception handler
to specific declaration name. For example:
</p>
<blockquote>
<div class="code">
<pre>
%exception allocate {
try {
@ -282,8 +295,9 @@ to specific declaration name. For example:
}
}
</pre>
</blockquote>
</div>
<p>
In this case, the exception handler is only attached to declarations
named "allocate". This would include both global and member
functions. The names supplied to <tt>%exception</tt> follow the same
@ -291,8 +305,9 @@ rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
For example, if you wanted to define
an exception handler for a specific class, you might write this:
</p>
<blockquote>
<div class="code">
<pre>
%exception Object::allocate {
try {
@ -303,16 +318,18 @@ an exception handler for a specific class, you might write this:
}
}
</pre>
</blockquote>
</div>
<p>
When a class prefix is supplied, the exception handler is applied to the corresponding declaration
in the specified class as well as for identically named functions appearing in derived classes.
</p>
<p>
<tt>%exception</tt> can even be used to pinpoint a precise declaration when overloading is used. For example:
</p>
<blockquote>
<div class="code">
<pre>
%exception Object::allocate(int) {
try {
@ -323,12 +340,14 @@ in the specified class as well as for identically named functions appearing in d
}
}
</pre>
</blockquote>
</div>
<p>
Attaching exceptions to specific declarations is a good way to reduce code bloat. It can also be a useful way
to attach exceptions to specific parts of a header file. For example:
</p>
<blockquote>
<div class="code">
<pre>
%module example
%{
@ -357,8 +376,9 @@ to attach exceptions to specific parts of a header file. For example:
// Read a raw header file
%include "someheader.h"
</pre>
</blockquote>
</div>
<p>
<b>Compatibility note:</b> The <tt>%exception</tt> directive replaces
the functionality provided by the deprecated "except" typemap.
The typemap would allow exceptions to be thrown in the target
@ -366,6 +386,7 @@ language based on the return type of a function and
was intended to be a mechanism for pinpointing specific
declarations. However, it never really worked that well and the new
%exception directive is much better.
</p>
<H3><a name="Customization_nn7"></a>11.1.5 Using The SWIG exception library</H3>
@ -377,7 +398,7 @@ 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
common scripting language exceptions in a portable manner. For example :</p>
<blockquote><pre>
<div class="code"><pre>
// Language independent exception handler
%include exception.i
@ -395,14 +416,14 @@ common scripting language exceptions in a portable manner. For example :</p>
}
}
</pre></blockquote>
</pre></div>
<p>
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>
<blockquote><pre>
<div class="code"><pre>
SWIG_MemoryError
SWIG_IOError
SWIG_RuntimeError
@ -414,7 +435,7 @@ SWIG_SyntaxError
SWIG_ValueError
SWIG_SystemError
SWIG_UnknownError
</pre></blockquote>
</pre></div>
<p>
Since the <tt>SWIG_exception()</tt> function is defined at the C-level
@ -425,53 +446,61 @@ functions.
<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2>
<p>
A common problem in some applications is managing proper ownership of objects. For
example, consider a function like this:
</p>
<blockquote>
<div class="code">
<pre>
Foo *blah() {
Foo *f = new Foo();
return f;
}
</pre>
</blockquote>
</div>
<p>
If you wrap the function <tt>blah()</tt>, SWIG has no idea that the
return value is a newly allocated object. As a result, the resulting
extension module may produce a memory leak (SWIG is conservative and
will never delete objects unless it knows for certain that the
returned object was newly created).
</p>
<p>
To fix this, you can provide an extra hint to the code generator using
the <tt>%newobject</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%newobject blah;
Foo *blah();
</pre>
</blockquote>
</div>
<p>
<tt>%newobject</tt> works exactly like <tt>%rename</tt> and <tt>%exception</tt>. In other words,
you can attach it to class members and parameterized declarations as before. For example:
</p>
<blockquote>
<div class="code">
<pre>
%newobject ::blah(); // Only applies to global blah
%newobject Object::blah(int,double); // Only blah(int,double) in Object
%newobject *::copy; // Copy method in all classes
...
</pre>
</blockquote>
</div>
<p>
When <tt>%newobject</tt> is supplied, many language modules will
arrange to take ownership of the return value. This allows the value
to be automatically garbage-collected when it is no longer in use. However,
this depends entirely on the target language (a language module may also choose to ignore
the <tt>%newobject</tt> directive).
</p>
<p>
Closely related to <tt>%newobject</tt> is a special typemap. The "newfree" typemap
@ -480,7 +509,7 @@ methods for which <tt>%newobject</tt> has been applied and is commonly used to c
results. For example:
</p>
<blockquote>
<div class="code">
<pre>
%typemap(newfree) char * "free($1);";
...
@ -488,48 +517,54 @@ results. For example:
...
char *strdup(const char *s);
</pre>
</blockquote>
</div>
<p>
In this case, the result of the function is a string in the target language. Since this string
is a copy of the original result, the data returned by <tt>strdup()</tt> is no longer needed.
The "newfree" typemap in the example simply releases this memory.
</p>
<p>
<b>Compatibility note:</b> Previous versions of SWIG had a special <tt>%new</tt> directive. However, unlike <tt>%newobject</tt>,
it only applied to the next declaration. For example:
</p>
<blockquote>
<div class="code">
<pre>
%new char *strdup(const char *s);
</pre>
</blockquote>
</div>
<p>
For now this is still supported but is deprecated.
</p>
<p>
<b>How to shoot yourself in the foot:</b> The <tt>%newobject</tt> directive is not a declaration modifier like the old
<tt>%new</tt> directive. Don't write code like this:
</p>
<blockquote>
<div class="code">
<pre>
%newobject
char *strdup(const char *s);
</pre>
</blockquote>
</div>
The results might not be what you expect.
<H2><a name="features"></a>11.3 Features and the %feature directive</H2>
<p>
Both <tt>%exception</tt> and <tt>%newobject</tt> are examples of a
more general purpose customization mechanism known as "features." A
feature is simply a user-definable property that is attached to
specific declarations in an interface file. Features are attached
using the <tt>%feature</tt> directive. For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::allocate {
try {
@ -542,22 +577,26 @@ using the <tt>%feature</tt> directive. For example:
%feature("new","1") *::copy;
</pre>
</blockquote>
</div>
<p>
In fact, the <tt>%exception</tt> and <tt>%newobject</tt> directives are really nothing more than macros
involving <tt>%feature</tt>:
</p>
<blockquote>
<div class="code">
<pre>
#define %exception %feature("except")
#define %newobject %feature("new","1")
</pre>
</blockquote>
</div>
<p>
The <tt>%feature</tt> directive follows the same name matching rules
as the <tt>%rename</tt> directive (which is in fact just a special
form of <tt>%feature</tt>). This means that features can be applied with
pinpoint accuracy to specific declarations if needed.
</p>
<p>
When a feature is defined, it is given a name and a value. Most commonly, the
@ -571,11 +610,11 @@ A feature stays in effect until it is explicitly disabled. A feature is disable
supplying a <tt>%feature</tt> directive with no value. For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::allocate; // Removes any previously defined feature
</pre>
</blockquote>
</div>
<p>
If no declaration name is given, a global feature is defined. This feature is then
@ -583,7 +622,7 @@ attached to <em>every</em> declaration that follows. This is how global excepti
are defined. For example:
</p>
<blockquote>
<div class="code">
<pre>
/* Define a global exception handler */
%feature("except") {
@ -598,40 +637,46 @@ are defined. For example:
/* Disable the exception handler */
%feature("except");
</pre>
</blockquote>
</div>
<p>
The <tt>%feature</tt> directive can be used with different syntax.
The following are all equivalent:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") Object::method { $action };
%feature("except") Object::method %{ $action %};
%feature("except") Object::method " $action ";
%feature("except","$action") Object::method;
</pre>
</blockquote>
</div>
<p>
The syntax in the first variation will generate the <tt>{ }</tt> delimeters used whereas the other variations will not.
The <tt>%feature</tt> directive also accepts XML style attributes in the same way that typemaps will.
Any number of attributes can be specified.
The following is the generic syntax for features:
</p>
<blockquote>
<div class="code">
<pre>
%feature("name","value", attribute1="AttibuteValue1") symbol;
%feature("name", attribute1="AttibuteValue1") symbol {value};
%feature("name", attribute1="AttibuteValue1") symbol %{value%};
%feature("name", attribute1="AttibuteValue1") symbol "value";
</pre>
</blockquote>
</div>
<p>
More than one attribute can be specified using a comma separated list.
The Java module is an example that uses attributes in <tt>%feature("except")</tt>.
The <tt>throws</tt> attribute specifies the name of a Java class to add to a proxy method's throws clause.
In the following example, <tt>MyExceptionClass</tt> is the name of the Java class for adding to the throws clause.
</p>
<blockquote>
<div class="code">
<pre>
%feature("except", throws="MyExceptionClass") Object::method {
try {
@ -641,7 +686,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
}
};
</pre>
</blockquote>
</div>
<p>
Further details can be obtained from the <a href="Java.html#exception_handling">Java exception handling</a> section.
@ -661,56 +706,56 @@ wrapper method only and not the extra overloaded methods that SWIG generates.
For example:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") void hello(int i=0, double d=0.0);
void hello(int i=0, double d=0.0);
</pre>
</blockquote>
</div>
<p>
will apply the feature to all three wrapper methods, that is:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i, double d);
void hello(int i);
void hello();
</pre>
</blockquote>
</div>
<p>
If the default arguments are not specified in the feature:
</p>
<blockquote>
<div class="code">
<pre>
%feature("except") void hello(int i, double d);
void hello(int i=0, double d=0.0);
</pre>
</blockquote>
</div>
<p>
then the feature will only apply to this wrapper method:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i, double d);
</pre>
</blockquote>
</div>
<p>
and not these wrapper methods:
</p>
<blockquote>
<div class="code">
<pre>
void hello(int i);
void hello();
</pre>
</blockquote>
</div>
<p>
If <a href="SWIGPlus.html#SWIGPlus_default_args">compactdefaultargs</a> are being used, then the difference between
@ -731,7 +776,7 @@ declarations with additional information for use by specific target language mod
in the Python module. You might use <tt>%feature</tt> to rewrite proxy/shadow class code as follows:
</p>
<blockquote>
<div class="code">
<pre>
%module example
%rename(bar_id) bar(int,double);
@ -751,9 +796,11 @@ public:
int bar(int x, double y);
}
</pre>
</blockquote>
</div>
<p>
Further details of <tt>%feature</tt> usage is described in the documentation for specific language modules.
</p>
</body>
</html>

891
SWIG/Doc/Manual/Extending.html
View file

File diff suppressed because it is too large Load diff

198
SWIG/Doc/Manual/Guile.html
View file

@ -3,12 +3,14 @@
<html>
<head>
<title>SWIG and Guile</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>18 SWIG and Guile</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Guile_nn2">Meaning of "Module"</a>
<li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
@ -37,6 +39,7 @@
<li><a href="#Guile_nn21">Linking</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -80,7 +83,7 @@ whatever custom API the language uses. This is currently implemented by the gui
the SCM guile API rather than the GH guile API.
For example, here are some of the current mapping file for the SCM API</p>
<blockquote><pre>
<div class="code"><pre>
#define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
#define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
@ -91,7 +94,7 @@ For example, here are some of the current mapping file for the SCM API</p>
#define gh_cons scm_cons
#define gh_double2scm scm_make_real
...
</pre></blockquote>
</pre></div>
<p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
@ -111,9 +114,11 @@ policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5"></a>18.3.1 Simple Linkage</H3>
<p>
The default linkage is the simplest; nothing special is done. In this
case the function <code>SWIG_init()</code> is exported. Simple linkage
can be used in several ways:
</p>
<ul>
<li><b>Embedded Guile, no modules.</b> You want to embed a Guile
@ -122,42 +127,54 @@ in the root module. Then call <code>SWIG_init()</code> in the
<code>inner_main()</code> function. See the "simple" and "matrix" examples under
<code>Examples/guile</code>.
<li><b>Dynamic module mix-in.</b> You want to create a Guile module
<li><p><b>Dynamic module mix-in.</b> You want to create a Guile module
using <code>define-module</code>, containing both Scheme code and
bindings made by SWIG; you want to load the SWIG modules as shared
libraries into Guile.
<blockquote>
libraries into Guile.</p>
<div class="targetlang">
<pre>
(define-module (my module))
(define my-so (dynamic-link "./example.so"))
(dynamic-call "SWIG_init" my-so) ; make SWIG bindings
;; Scheme definitions can go here
</pre>
</blockquote>
</div>
<p>
Newer Guile versions provide a shorthand for <code>dynamic-link</code>
and <code>dynamic-call</code>:
<blockquote>
</p>
<div class="targetlang">
<pre>
(load-extension "./example.so" "SWIG_init")
</pre>
</blockquote>
</div>
<p>
You need to explicitly export those bindings made by SWIG that you
want to import into other modules:
<blockquote>
</p>
<div class="targetlang">
<pre>
(export foo bar)
</pre>
</blockquote>
</div>
<p>
In this example, the procedures <code>foo</code> and <code>bar</code>
would be exported. Alternatively, you can export all bindings with the
following module-system hack:
<blockquote>
</p>
<div class="targetlang">
<pre>
(module-map (lambda (sym var)
(module-export! (current-module) (list sym)))
(current-module))
</pre>
</blockquote>
</div>
<p>SWIG can also generate this Scheme stub (from
<code>define-module</code> up to <code>export</code>)
@ -171,15 +188,18 @@ to load your extension module (with <code>dynamic-link</code> or
information by including a directive like this in the interface file:
</p>
<blockquote>
<div class="code">
<pre>
%scheme %{ (load-extension "./example.so" "SWIG_init") %}
</pre>
</blockquote>
</div>
<p>
(The <code>%scheme</code> directive allows to insert arbitrary Scheme
code into the generated file <code><var>module.scm</var></code>; it is
placed between the <code>define-module</code> form and the
<code>export</code> form.)
</p>
</ul>
<p>If you want to include several SWIG modules, you would need to rename
@ -222,19 +242,19 @@ in the <code>inner_main()</code> function.
<li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
shared libraries into Guile; all bindings are automatically put in
newly created Guile modules.
<blockquote>
<div class="targetlang">
<pre>
(define my-so (dynamic-link "./foo.so"))
;; create new module and put bindings there:
(dynamic-call "scm_init_my_modules_foo_module" my-so)
</pre>
</blockquote>
</div>
Newer Guile versions have a shorthand procedure for this:
<blockquote>
<div class="targetlang">
<pre>
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
</pre>
</blockquote>
</div>
</ul>
<H3><a name="Guile_nn8"></a>18.3.4 Old Auto-Loading Guile Module Linkage</H3>
@ -274,12 +294,12 @@ using the "-package" command line option to set the part of the module
name before the last symbol. For example, both command lines:
</p>
<blockquote>
<div class="shell">
<pre>
swig -guile -package my/lib foo.i
swig -guile -package my/lib -module foo foo.i
</pre>
</blockquote>
</div>
<p>
would create module <code>(my lib foo)</code> (assuming in the first
@ -326,45 +346,65 @@ a value to the list of function return values.
<p>Multiple values can be passed up to Scheme in one of three ways:
<ul>
<li><em>Multiple values as lists.</em>
<li><p><em>Multiple values as lists.</em>
By default, if more than one value is to
be returned, a list of the values is created and returned; to switch
back to this behavior, use
<blockquote>
back to this behavior, use</p>
<div class="code">
<pre>
%values_as_list;</pre>
</blockquote>
</div>
<p>
<li><em>Multiple values as vectors.</em>
By issuing
<blockquote>
</p>
<div class="code">
<pre>
%values_as_vector;</pre>
</blockquote>
</div>
<p>
vectors instead of lists will be used.
<li><em>Multiple values for multiple-value continuations.</em>
<strong>This is the most elegant way.</strong> By issuing
<blockquote>
</p>
<div class="code">
<pre>
%multiple_values;</pre>
</blockquote>
</div>
<p>
multiple values are passed to the multiple-value
continuation, as created by <code>call-with-values</code> or the
convenience macro <code>receive</code>. The latter is available if you
issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
<code>divide</code> function
wants to return two values, a quotient and a remainder, you can write:
<blockquote>
</p>
<div class="targetlang">
<pre>
(receive (quotient remainder)
(divide 35 17)
<var>body</var>...)
</pre>
</blockquote>
</div>
<p>
In <code><var>body</var></code>, the first result of
<code>divide</code> will be bound to the variable
<code>quotient</code>, and the second result to <code>remainder</code>.
</p>
</ul>
<p>
See also the "multivalue" example.
</p>
<H2><a name="Guile_nn12"></a>18.6 Representation of pointers as smobs</H2>
@ -388,6 +428,8 @@ If the Scheme object passed was not a SWIG smob representing a compatible
pointer, a <code>wrong-type-arg</code> exception is raised.
<H3><a name="Guile_nn13"></a>18.6.1 GH Smobs</H3>
<p>
In earlier versions of SWIG, C pointers were represented as Scheme
strings containing a hexadecimal rendering of the pointer value and a
@ -450,6 +492,7 @@ the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
SWIG code calls <code>scm_error</code> on exception, using the following
mapping:
<div class="code">
<pre>
MAP(SWIG_MemoryError, "swig-memory-error");
MAP(SWIG_IOError, "swig-io-error");
@ -462,6 +505,7 @@ mapping:
MAP(SWIG_ValueError, "swig-value-error");
MAP(SWIG_SystemError, "swig-system-error");
</pre>
</div>
<p>
The default when not specified here is to use "swig-error".
@ -490,11 +534,14 @@ later.
<p>You need to register the generated documentation file with Guile
like this:
<div class="targetlang">
<pre>
(use-modules (ice-9 documentation))
(set! documentation-files
(cons "<var>file</var>" documentation-files))
</pre>
</div>
<p>Documentation strings can be configured using the Guile-specific
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
@ -550,7 +597,7 @@ current directory. GOOPS support requires either passive or module linkage.</p>
<p>If <code>-emit-slot-accessors</code> is also passed as an argument,
then the generated file will contain accessor methods for all the
slots in the classes and for global variables. The input class</p>
<blockquote><pre>
<div class="code"><pre>
class Foo {
public:
Foo(int i) : a(i) {}
@ -559,9 +606,13 @@ slots in the classes and for global variables. The input class</p>
Foo getFooMultBy(int i) { return Foo(a * i); }
};
Foo getFooPlus(int i) { return Foo(a + i); }
</pre></blockquote>
</pre></div>
<p>
will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get
@ -578,9 +629,13 @@ will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
(make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; getMultBy getFooMultBy getFooPlus )
</pre></blockquote>
</pre></div>
<p>
and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-class &lt;Foo&gt; (&lt;swig&gt;)
(a #:allocation #:swig-virtual
#:slot-ref primitive:Foo-a-get
@ -598,9 +653,13 @@ and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
(make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
(export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus )
</pre></blockquote>
</pre></div>
<p>
which can then be used by this code
<blockquote><pre>
</p>
<div class="targetlang"><pre>
;; not using getters and setters
(define foo (make &lt;Foo&gt; #:args '(45)))
(slot-ref foo 'a)
@ -616,13 +675,15 @@ which can then be used by this code
(set! (a foo) 5)
(getMultBy foo 4)
(a (getFooMultBy foo 7))
</pre></blockquote>
</pre></div>
<p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword. Hopefully in
the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</code></p>
<p>Also note that the order the declarations occur in the .i file make a difference. For example,
</p><blockquote><pre>
</p>
<div class="code"><pre>
%module test
%{ #include "foo.h" %}
@ -634,12 +695,16 @@ the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</cod
%}
%include "foo.h"
</pre></blockquote>
</pre></div>
<p>
This is a valid SWIG file it will work as you think it will for primitive support, but the generated
GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the
declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code>
before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
<blockquote><pre>
</p>
<div class="targetlang"><pre>
;;...
(define-method (someFunc (swig_smob &lt;Foo&gt;))
@ -652,9 +717,12 @@ before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
)
;;...
</pre></blockquote>
</pre></div>
<p>
Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put the
<code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>18.10.1 Naming Issues</H3>
@ -688,10 +756,10 @@ In the previous example, the GOOPS definitions will be in a file named Test.scm.
<p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS
guile-modules at the same time. To do this, you need to rename the exported symbols from one or both
guile-modules. For example,</p>
<blockquote><pre>
<div class="targetlang"><pre>
(use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></blockquote>
</pre></div>
<p>TODO: Renaming class name prefixes?</p>
@ -717,31 +785,35 @@ argument to solve this problem. If the <code>-exportprimitive</code> option is
of the generated GOOPS guile-module.
The <code>%goops</code> directive should contain code to load the .so library.
<blockquote><pre>
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
(with the <code>-package my/modules -module foo</code> command line arguments)
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here
(load-extension "./foo.so" "scm_init_my_modules_foo_module")
(use-modules (oop goops) (Swig common))
</pre></blockquote>
</pre></div>
</li>
<li><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
<li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
<code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
which will then be added to the scmstub file.
Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
<code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.
whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
<blockquote><pre>
<div class="targetlang"><pre>
%scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
// only include the following definition if (my modules foo) cannot
// be loaded automatically
@ -749,9 +821,13 @@ whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.
(primitive-load "/path/to/foo-primitive.scm")
(primitive-load "/path/to/Swig/common.scm")
%}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
<blockquote><pre>
</p>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here (if any)
@ -762,21 +838,23 @@ Produces the following code at the top of the generated GOOPS guile-module
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:)))
</pre></blockquote>
</pre></div>
</li>
<li><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
<li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
Swig will also automatically generate the line <code>(use-modules
(<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
directive should contain whatever code is needed to get that module loaded into guile.
directive should contain whatever code is needed to get that module loaded into guile.</p>
<blockquote><pre>
<div class="code"><pre>
%goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
</pre></blockquote>
</pre></div>
<p>
Produces the following code at the top of the generated GOOPS guile-module
</p>
<blockquote><pre>
<div class="targetlang"><pre>
(define-module (my modules foo))
;; %goops directive goes here (if any)
@ -786,7 +864,7 @@ Produces the following code at the top of the generated GOOPS guile-module
(use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
'primitive:)))
</pre></blockquote>
</pre></div>
</li>
</ul>

66
SWIG/Doc/Manual/Introduction.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Introduction</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Introduction"></a>2 Introduction</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Introduction_nn2">What is SWIG?</a>
<li><a href="#Introduction_nn3">Why use SWIG?</a>
@ -24,6 +26,7 @@
<li><a href="#Introduction_nn12">Hands off code generation</a>
<li><a href="#Introduction_nn13">SWIG and freedom</a>
</ul>
</div>
<!-- INDEX -->
@ -31,6 +34,7 @@
<H2><a name="Introduction_nn2"></a>2.1 What is SWIG?</H2>
<p>
SWIG is a software development tool that simplifies the task of
interfacing different languages to C and C++ programs. In a
nutshell, SWIG is a compiler that takes C declarations and creates
@ -39,6 +43,7 @@ including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
build a usable interface in only a few minutes. Possible applications
of SWIG include:
</p>
<ul>
<li>Building interpreted interfaces to existing C programs.
@ -68,10 +73,12 @@ in scientific and engineering projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
<p>
As stated in the previous section, the primary purpose of SWIG is to simplify
the task of integrating C/C++ with other programming languages. However, why would
anyone want to do that? To answer that question, it is useful to list a few strengths
of C/C++ programming:
</p>
<ul>
<li>Excellent support for writing programming libraries.
@ -80,7 +87,9 @@ of C/C++ programming:
<li>Large user community and software base.
</ul>
<p>
Next, let's list a few problems with C/C++ programming
</p>
<ul>
<li>Writing a user interface is rather painful (i.e., consider programming with MFC, X11, GTK, or any number
@ -90,7 +99,7 @@ of other libraries).
<li>Modularization can be tricky.
<li>Security concerns (buffer overflow for instance).
</ul>
<p>
To address these limitations, many programmers have arrived at the
conclusion that it is much easier to use different programming
languages for different tasks. For instance, writing a graphical user
@ -104,6 +113,7 @@ strengths and weaknesses. Moreover, it is extremely unlikely that any
programming is ever going to be perfect. Therefore, by combining
languages together, you can utilize the best features of each language
and greatly simplify certain aspects of software development.
</p>
<p>
From the standpoint of C/C++, a lot of people use SWIG because they want to break
@ -116,10 +126,11 @@ in programs that resemble this:
<li>A horrible collection of hacks that form some kind of user interface (but
which no-one really wants to touch).
</ul>
<p>
Instead of going down that route, incorporating C/C++ into a higher level language
often results in a more modular design, less code, better flexibility, and increased
programmer productivity.
</p>
<p>
SWIG tries to make the problem of C/C++ integration as painless as possible.
@ -134,10 +145,12 @@ user manual ;-).
<H2><a name="Introduction_nn4"></a>2.3 A SWIG example</H2>
<p>
The best way to illustrate SWIG is with a simple example. Consider the
following C code:
</p>
<blockquote><pre>
<div class="code"><pre>
/* File : example.c */
double My_variable = 3.0;
@ -152,7 +165,7 @@ int fact(int n) {
int my_mod(int n, int m) {
return(n % m);
}
</pre></blockquote>
</pre></div>
<p>
Suppose that you wanted to access these functions and the global
@ -163,7 +176,7 @@ suffix) :
<H3><a name="Introduction_nn5"></a>2.3.1 SWIG interface file</H3>
<blockquote><pre>
<div class="code"><pre>
/* File : example.i */
%module example
%{
@ -173,7 +186,7 @@ suffix) :
extern double My_variable;
extern int fact(int);
extern int my_mod(int n, int m);
</pre></blockquote>
</pre></div>
<p>
The interface file contains ANSI C function prototypes and variable
@ -185,10 +198,12 @@ files or additional C declarations.
<H3><a name="Introduction_nn6"></a>2.3.2 The swig command</H3>
<p>
SWIG is invoked using the <tt>swig</tt> command. We can use this to
build a Tcl module (under Linux) as follows :
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -tcl example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o example.so</b>
@ -201,7 +216,7 @@ unix &gt; <b>tclsh</b>
% <b>expr $My_variable + 4.5</b>
7.5
%
</pre></blockquote>
</pre></div>
<p>
The <tt>swig</tt> command produced a new file called
@ -217,10 +232,12 @@ almost never need to worry about it.
<H3><a name="Introduction_nn7"></a>2.3.3 Building a Perl5 module</H3>
<p>
Now, let's turn these functions into a Perl5 module. Without making
any changes type the following (shown for Solaris):
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -perl5 example.i</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -235,15 +252,17 @@ print $example::My_variable + 4.5, "\n";
2
7.5
unix &gt;
</pre></blockquote>
</pre></div>
<H3><a name="Introduction_nn8"></a>2.3.4 Building a Python module</H3>
<p>
Finally, let's build a module for Python (shown for Irix).
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -python example.i</b>
unix &gt; <b>gcc -c -fpic example.c example_wrap.c -I/usr/local/include/python2.0</b>
unix &gt; <b>gcc -shared example.o example_wrap.o -o _example.so</b>
@ -258,17 +277,19 @@ Type "copyright", "credits" or "license" for more information.
2
&gt;&gt;&gt; <b>example.cvar.My_variable + 4.5</b>
7.5
</pre></blockquote>
</pre></div>
<H3><a name="Introduction_nn9"></a>2.3.5 Shortcuts</H3>
<p>
To the truly lazy programmer, one may wonder why we needed the extra
interface file at all. As it turns out, you can often do without
it. For example, you could also build a Perl5 module by just running
SWIG on the C header file and specifying a module name as follows
</p>
<blockquote><pre>
<div class="code"><pre>
unix &gt; <b>swig -perl5 -module example example.h</b>
unix &gt; <b>gcc -c example.c example_wrap.c \
-I/usr/local/lib/perl5/sun4-solaris/5.003/CORE</b>
@ -282,15 +303,17 @@ print $example::My_variable + 4.5, "\n";
24
2
7.5
</pre></blockquote>
</pre></div>
<H2><a name="Introduction_nn10"></a>2.4 Supported C/C++ language features</H2>
<p>
A primary goal of the SWIG project is to make the language binding
process extremely easy. Although a few simple examples have been shown,
SWIG is quite capable in supporting most of C++. Some of the
major features include:
</p>
<ul>
<li>Full C99 preprocessing.
@ -306,8 +329,10 @@ major features include:
<li>C++ smart pointers.
</ul>
<p>
Currently, the only major C++ feature not supported is nested classes--a limitation
that will be removed in a future release.
</p>
<p>
It is important to stress that SWIG is not a simplistic C++ lexing
@ -323,12 +348,14 @@ stresses the very limits of many C++ compilers.
<H2><a name="Introduction_nn11"></a>2.5 Non-intrusive interface building</H2>
<p>
When used as intended, SWIG requires minimal (if any) modification to
existing C or C++ code. This makes SWIG extremely easy to use with existing
packages and promotes software reuse and modularity. By making
the C/C++ code independent of the high level interface, you can change the
interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application.
</p>
<H2><a name="Introduction_build_system"></a>2.6 Incorporating SWIG into a build system</H2>
@ -362,7 +389,7 @@ driving SWIG from IDE's and makefiles. All of this can be done from a single cr
The following example is a CMake input file for creating a python wrapper for the SWIG interface file, example.i:
</p>
<blockquote><pre>
<div class="code"><pre>
# This is a CMake example for Python
@ -381,14 +408,16 @@ SET_SOURCE_FILES_PROPERTIES(example.i PROPERTIES SWIG_FLAGS "-includeall")
SWIG_ADD_MODULE(example python example.i example.cxx)
SWIG_LINK_LIBRARIES(example ${PYTHON_LIBRARIES})
</pre></blockquote>
</pre></div>
<p>
The above example will generate native build files such as makefiles, nmake files and Visual Studio projects
which will invoke SWIG and compile the generated C++ files into _example.so (UNIX) or _example.dll (Windows).
</p>
<H2><a name="Introduction_nn12"></a>2.7 Hands off code generation</H2>
<p>
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). You should think of your target language interface being
@ -396,10 +425,12 @@ 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.
</p>
<H2><a name="Introduction_nn13"></a>2.8 SWIG and freedom</H2>
<p>
No, this isn't a special section on the sorry state of world politics.
However, it may be useful to know that SWIG was written with a
certain "philosophy" about programming---namely that programmers are
@ -409,6 +440,7 @@ you get away with. In fact, you can use SWIG to go well beyond
"shooting yourself in the foot" if dangerous programming is your goal.
On the other hand, this kind of freedoom may be exactly what is needed
to work with complicated and unusual C/C++ applications.
</p>
<p>
Ironically, the freedom that SWIG provides is countered by an

1775
SWIG/Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

608
SWIG/Doc/Manual/Library.html
View file

File diff suppressed because it is too large Load diff

3
SWIG/Doc/Manual/Makefile
View file

@ -26,8 +26,9 @@ check:
all=`sed '/^#/d' chapters`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book
htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book
python fixstyle.py SWIGDocumentation.html
swightml.book:
echo "#HTMLDOC 1.8.23" > swightml.book

49
SWIG/Doc/Manual/Modula3.html
View file

@ -2,10 +2,12 @@
<html>
<head>
<title>SWIG and Modula-3</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>20 SWIG and Modula-3</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#modula3_overview">Overview</a>
<ul>
@ -40,10 +42,12 @@
</ul>
<li><a href="#remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
You should be familiar with the
@ -51,6 +55,7 @@ You should be familiar with the
of SWIG,
especially
<a href="Typemaps.html">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>20.1 Overview</H2>
@ -78,9 +83,11 @@ FFTW
</ol>
<p>
I took some more time to explain
why I think it's right what I'm doing.
So the introduction got a bit longer than it should ... ;-)
</p>
<H3><a name="whyscripting"></a>20.1.1 Why not scripting ?</H3>
@ -141,12 +148,14 @@ Modula-3 is made in one go
and the language definition is really compact.
</p>
<p>
On the one hand Modula-3 can be safe
(but probably less efficient) in normal modules
while providing much static and dynamic safety.
On the other hand you can write efficient
but less safe code in the style of C
within <tt>UNSAFE</tt> modules.
</p>
<p>
Unfortunately Modula's safety and strength
@ -337,8 +346,11 @@ generates several files:
</tr>
</table>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
are redirected to C library functions:
</p>
<table summary="Modula-3 C library">
<tr>
<td align=center>
@ -403,8 +415,11 @@ but C++ compilers should support generating C++ functions
with a C interface.
</p>
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
<tr>
<td align=center>
@ -496,6 +511,7 @@ so I'm not sure if this is possible or sensible, yet.
<H3><a name="compilers"></a>20.3.1 Compilers</H3>
<p>
There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code
@ -503,15 +519,18 @@ but the library file
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
may do so.
For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>20.3.2 Additional Commandline Options</H3>
<p>
There are some experimental command line options
that prevent SWIG from generating interface files.
Instead files are emitted that may assist you
when writing SWIG interface files.
</p>
<table border summary="Modula-3 specific options">
<tr>
@ -802,9 +821,12 @@ consist of the following parts:
<H3><a name="ordinals"></a>20.4.2 Subranges, Enumerations, Sets</H3>
<p>
Subranges, enumerations, and sets are machine oriented types
that make Modula very strong and expressive compared
with the type systems of many other languages.
</p>
<ul>
<li>
Subranges are used for statically restricted choices of integers.
@ -816,8 +838,12 @@ Enumerations are used for named choices.
Sets are commonly used for flag (option) sets.
</li>
</ul>
Using them extensively makes Modula code very safe and readable.
<p>
Using them extensively makes Modula code very safe and readable.
</p>
<p>
C supports enumerations, too, but they are not as safe as the ones of Modula.
Thus they are abused for many things:
For named choices, for integer constant definitions, for sets.
@ -826,7 +852,9 @@ To make it complete every way of defining a value in C
is somewhere used for defining something
that must be handled completely different in Modula-3
(<tt>INTEGER</tt>, enumeration, <tt>SET</tt>).
</p>
<p>
I played around with several <tt>%feature</tt>s and <tt>%pragma</tt>s
that split the task up into converting
the C bit patterns (integer or bit set)
@ -839,17 +867,20 @@ So the best what you can currently do is
to rewrite constant definitions manually.
Though this is a tedious work
that I'd like to automate.
</p>
<H3><a name="class"></a>20.4.3 Objects</H3>
<p>
Declarations of C++ classes are mapped to <tt>OBJECT</tt> types
while it is tried to retain the access hierarchy
"public - protected - private" using partial revelation.
Though the
<a href="../../Examples/modula3/class/example.i">implementation</a>
is not really useful, yet.
</p>
<H3><a name="imports"></a>20.4.4 Imports</H3>
@ -878,40 +909,50 @@ for the typemap library
For a monolithic module you might be better off
if you add the imports directly:
</p>
<div class="code">
<pre>
%insert(m3rawintf) %{
IMPORT M3toC;
%}
</pre>
</pre></div>
<H3><a name="exceptions"></a>20.4.5 Exceptions</H3>
<p>
Modula-3 provides another possibility
of an output of a function: exceptions.
</p>
<p>
Any piece of Modula-3 code that SWIG inserts
due to a typemap can raise an exception.
This way you can also convert an error code
from a C function into a Modula-3 exception.
</p>
<p>
The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>throws</tt> extension.
If the typemap <tt>m3wrapinconv</tt> for <tt>blah *</tt>
contains code that may raise the exceptions <tt>OSError.E</tt>
you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>20.4.6 Example</H3>
<p>
The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features.
Here is an example of a generated wrapper
where almost everything is generated by a typemap:
</p>
<blockquote><pre>
<div class="code"><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I>
@ -945,7 +986,7 @@ where almost everything is generated by a typemap:
M3toC.FreeSharedS(str,arg1); <I>(* m3wrapfreearg *)</I>
END;
END Name;
</pre></blockquote>
</pre></div>
<H2><a name="hints"></a>20.5 More hints to the generator</H2>

29
SWIG/Doc/Manual/Modules.html
View file

@ -2,22 +2,26 @@
<html>
<head>
<title>Working with Modules</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Modules"></a>15 Working with Modules</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to runtime system</a>
<li><a href="#external_run_time">External access to the runtime</a>
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
<li><a href="#Modules_nn5">References</a>
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
</ul>
</div>
<!-- INDEX -->
<p>
When first working with SWIG, users commonly start by creating a
single module. That is, you might define a single SWIG interface that
wraps some set of C/C++ code. You then compile all of the generated
@ -25,6 +29,7 @@ wrapper code into a module and use it. For large applications, however,
this approach is problematic---the size of the generated wrapper code
can be rather large. Moreover, it is probably easier to manage the
target language interface when it is broken up into smaller pieces.
</p>
<p>
This chapter describes the problem of using SWIG in programs
@ -34,6 +39,7 @@ where you want to create a collection of modules.
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
<p>
Many of SWIG's target languages generate a set of functions
commonly known as the "SWIG runtime." These functions are
primarily related to the runtime type system which checks pointer
@ -42,6 +48,7 @@ values in C++. As a general rule, the statically typed target languages,
such as Java, use the language's built in static type checking and
have no need for a SWIG runtime. All the dynamically typed / interpreted
languages rely on the SWIG runtime.
</p>
<p>
The runtime functions are private to each SWIG-generated
@ -69,7 +76,8 @@ Be careful if you use threads and the automatic module loading that some scripti
languages provide. One solution is to load all modules before spawning any threads.
</p>
<H2><a name="external_run_time"></a>15.2 External access to the run-time system</a></H2>
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
@ -78,9 +86,9 @@ is embedded into the <tt>_wrap.c</tt> file, which has those declerations availab
to call the SWIG run-time functions from another C file, there is one header you need
to include. To generate the header that needs to be included, run the following command:
<blockquote><pre>
<div class="code"><pre>
$ swig -python -external-runtime &lt;filename&gt;
</pre></blockquote>
</pre></div>
<p>The filename argument is optional and if it is not passed, then the default filename will
be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should
@ -101,17 +109,21 @@ because the header file is self contained, and does not need to link with anythi
<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2>
<p>
When working with multiple SWIG modules, you should take care not to use static
libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
of SWIG modules with that library, each module will get its own private copy of the library code inserted
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
</p>
<H2><a name="Modules_nn5"></a>15.4 References</H2>
<p>
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2>
@ -122,10 +134,12 @@ In this way a number of different wrapper files can be generated, thereby avoidi
There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
</p>
<p>
<b>-fcompact</b><br>
This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
It simply removes blank lines and joins lines of code together.
This is useful for compilers that have a maximum file size that can be handled.
</p>
<p>
<b>-fvirtual</b><br>
@ -133,7 +147,7 @@ This command line option will remove the generation of superfluous virtual metho
Consider the following inheritance hierarchy:
</p>
<blockquote>
<div class="code">
<pre>
struct Base {
virtual void method();
@ -145,10 +159,13 @@ struct Derived : Base {
...
};
</pre>
</blockquote>
</div>
<p>
Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
</p>
<p>
<b>%feature("compactdefaultargs")</b><br>

19
SWIG/Doc/Manual/Mzscheme.html
View file

@ -3,15 +3,18 @@
<html>
<head>
<title>SWIG and MzScheme</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="MzScheme"></a>21 SWIG and MzScheme</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#MzScheme_nn2">Creating native MzScheme structures</a>
</ul>
</div>
<!-- INDEX -->
@ -22,8 +25,11 @@ This section contains information on SWIG's support of MzScheme.
<H2><a name="MzScheme_nn2"></a>21.1 Creating native MzScheme structures</H2>
<p>
Example interface file:
<blockquote>
</p>
<div class="code">
<pre>
/* define a macro for the struct creation */
%define handle_ptr(TYPE,NAME)
@ -40,10 +46,13 @@ Example interface file:
/* setup the typemaps for the pointer to an output parameter cntrs */
handle_ptr(struct diag_cntrs, cntrs);
</pre>
</blockquote>
</div>
<p>
Then in scheme, you can use regular struct access procedures like
<blockquote>
</p>
<div class="code">
<pre>
; suppose a function created a struct foo as
; (define foo (make-diag-cntrs (#x1 #x2 #x3) (make-inspector))
@ -52,9 +61,11 @@ Then in scheme, you can use regular struct access procedures like
(format "0x~x" (diag-cntrs-field2 foo))
;etc...
</pre>
</blockquote>
</div>
<p>
That's pretty much it. It works with nested structs as well.
</p>
</body>
</html>

83
SWIG/Doc/Manual/Ocaml.html
View file

@ -2,12 +2,13 @@
<html>
<head>
<title>SWIG and Ocaml</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>22 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Ocaml_nn2">Preliminaries</a>
<ul>
@ -52,10 +53,12 @@
<li><a href="#Ocaml_nn31">Exceptions</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's
support of Ocaml. Ocaml is a relatively recent addition to the ML family,
and is a recent addition to SWIG. It's the second compiled, typed
@ -70,6 +73,7 @@ way with Ocaml, by providing the necessary, but repetetive glue code
which creates and uses Ocaml values to communicate with C and C++ code.
In addition, SWIG also produces the needed Ocaml source that binds
variants, functions, classes, etc.
</p>
<p>
If you're not familiar with the Objective Caml language, you can visit
@ -79,6 +83,7 @@ If you're not familiar with the Objective Caml language, you can visit
<H2><a name="Ocaml_nn2"></a>22.1 Preliminaries</H2>
<p>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice,
you should use the latest stable release. The SWIG Ocaml module has
been tested on Linux (x86,PPC,Sparc) and Cygwin on Windows. The
@ -92,20 +97,23 @@ usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
</a>. The ocaml_dynamic and ocaml_dynamic_cpp targets in the
file Examples/Makefile illustrate how to compile and link SWIG modules that
will be loaded dynamically. This has only been tested on Linux so far.
</p>
<H3><a name="Ocaml_nn3"></a>22.1.1 Running SWIG</H3>
<p>
The basics of getting a SWIG Ocaml module up and running
can be seen from one of SWIG's example Makefiles, but is also described
here. To build an Ocaml module, run SWIG using the <tt>-ocaml</tt>
option.
</p>
<blockquote>
<div class="code">
<pre>
%swig -ocaml example.i
</pre>
</blockquote>
</div>
<p> This will produce 3 files. The file <tt>example_wrap.c</tt> contains
all of the C code needed to build an Ocaml module. To build the module,
@ -130,7 +138,7 @@ the user more freedom with respect to custom typing.
SWIG interface like:
</p>
<blockquote>
<div class="code">
<pre>
% swig -ocaml -co swig.mli ; swig -ocaml co swig.ml
% ocamlc -c swig.mli ; ocamlc -c swig.ml
@ -138,17 +146,17 @@ the user more freedom with respect to custom typing.
% ocamlc -c example.mli
% ocamlc -c example.ml
</pre>
</blockquote>
</div>
<p> <tt>ocamlc</tt> is aware of .c files and knows how to handle them. Unfortunately,
it does not know about .cxx, .cc, or .cpp files, so when SWIG is invoked
in C++ mode, you must: </p>
<blockquote>
<div class="code">
<pre>
% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br>
</pre>
</blockquote>
</div>
<H3><a name="Ocaml_nn5"></a>22.1.3 The camlp4 module</H3>
@ -268,7 +276,7 @@ caml_list_append function, or with functions and macros provided by
objective caml.<br>
</p>
<blockquote><pre>
<div class="code"><pre>
type c_obj =
C_void
| C_bool of bool
@ -288,8 +296,11 @@ type c_obj =
| C_obj of (string -&gt; c_obj -&gt; c_obj)
| C_string of string
| C_enum of c_enum_t
</pre></blockquote>
A few functions exist which generate and return these:<br>
</pre></div>
<p>
A few functions exist which generate and return these:
</p>
<ul>
<li>caml_ptr_val receives a c_obj and returns a void *. &nbsp;This
@ -397,19 +408,19 @@ enum_to_int and int_to_enum functions take an enum type label as an
argument. Example:
</p>
<blockquote><pre>
<div class="code"><pre>
%module enum_test
%{
enum c_enum_type { a = 1, b, c = 4, d = 8 };
%}
enum c_enum_type { a = 1, b, c = 4, d = 8 };
</pre></blockquote>
</pre></div>
<p>
The output mli contains:
</p>
<blockquote><pre>
<div class="code"><pre>
type c_enum_type = [
`unknown
| `c_enum_type
@ -424,9 +435,13 @@ type c_enum_tag = [
val int_to_enum c_enum_type -&gt; int -&gt; c_obj
val enum_to_int c_enum_type -&gt; c_obj -&gt; c_obj
</pre>
</blockquote>
</div>
<p>
So it's possible to do this:
<blockquote>
</p>
<div class="code">
<pre>
bash-2.05a$ ocamlmktop -custom enum_test_wrap.o enum_test.cmo -o enum_test_top
bash-2.05a$ ./enum_test_top
@ -440,11 +455,12 @@ val x : Enum_test.c_obj = C_enum `a
# int_to_enum `c_enum_type 4 ;;
- : Enum_test.c_obj = C_enum `c
</pre>
</blockquote>
</div>
<H4><a name="Ocaml_nn11"></a>22.2.2.1 Enum typing in Ocaml</H4>
<p>
The ocaml SWIG module now has support for loading and using multiple SWIG
modules at the same time. This enhances modularity, but presents problems
when used with a language which assumes that each module's types are complete
@ -452,6 +468,7 @@ at compile time. In order to achieve total soundness enum types are now
isolated per-module. The type issue matters when values are shared between
functions imported from different modules. You must convert values to master
values using the swig_val function before sharing them with another module.
</p>
<H3><a name="Ocaml_nn12"></a>22.2.3 Arrays</H3>
@ -558,6 +575,7 @@ void printfloats( float *tab, int len );
<H3><a name="Ocaml_nn17"></a>22.2.4 C++ Classes</H3>
<p>
C++ classes, along with structs and unions are represented by C_obj
(string -&gt; c_obj -&gt; c_obj) wrapped closures. &nbsp;These objects
contain a method list, and a type, which allow them to be used like
@ -567,6 +585,7 @@ an object has is represented as a string in the object's method table,
and each method table exists in memory only once. &nbsp;In addition
to any other operators an object might have, certain builtin ones are
provided by SWIG: (all of these take no arguments (C_void))
</p>
<table summary="SWIG provided operators">
<tr><td>"~"</td><td>Delete this object</td></tr>
@ -589,18 +608,23 @@ Called with one argument, the member variable is set to the value of the
argument. With zero arguments, the value is returned.
</td></tr>
</table>
<p>
Note that this string belongs to the wrapper object, and not
the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>22.2.4.1 STL vector and string Example</H4>
<p>
Standard typemaps are now provided for STL vector and string. More are in
the works. STL strings are passed just like normal strings, and returned
as strings. STL string references don't mutate the original string, (which
might be surprising), because Ocaml strings are mutable but have fixed
length. Instead, use multiple returns, as in the argout_ref example.
</p>
<table border="1" bgcolor="#dddddd" summary="STL vector and string example">
<tr><th><center>example.i</center></th></tr>
@ -632,7 +656,7 @@ after making a toplevel (make toplevel). This example uses the camlp4
module.
</p>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ ./example_top
Objective Caml version 3.06
@ -669,12 +693,14 @@ bar
baz
- : unit = ()
#
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn19"></a>22.2.4.2 C++ Class Example</H4>
<p>
Here's a simple example using Trolltech's Qt Library:
</p>
<table border="1" bgcolor="#dddddd" summary="Qt Library example">
<tr><th><center>qt.i</center></th></tr>
@ -702,7 +728,7 @@ public:
<H4><a name="Ocaml_nn20"></a>22.2.4.3 Compiling the example</H4>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ QTPATH=/your/qt/path
bash-2.05a$ for file in swig.mli swig.ml swigp4.ml ; do swig -ocaml -co $file ; done
bash-2.05a$ ocamlc -c swig.mli ; ocamlc -c swig.ml
@ -715,12 +741,12 @@ bash-2.05a$ ocamlc -c qt.ml
bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
camlp4o.cma swigp4.cmo qt_wrap.o qt.cmo -o qt_top -cclib \
-L$QTPATH/lib -cclib -lqt
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn21"></a>22.2.4.4 Sample Session</H4>
<blockquote><pre>
<div class="code"><pre>
bash-2.05a$ ./qt_top
Objective Caml version 3.06
@ -737,7 +763,7 @@ val hello : Qt.c_obj = C_obj &lt;fun&gt;
# hello -&gt; show () ;;
- : Qt.c_obj = C_void
# a -&gt; exec () ;;
</pre></blockquote>
</pre></div>
<p>
Assuming you have a working installation of QT, you will see a window
@ -762,7 +788,7 @@ You can turn on director classes by using an optional module argument like
this:
</p>
<blockquote><pre>
<div class="code"><pre>
%module(directors="1")
...
@ -772,7 +798,7 @@ this:
class foo {
...
};
</pre></blockquote>
</pre></div>
<H4><a name="Ocaml_nn24"></a>22.2.5.2 Overriding Methods in Ocaml</H4>
@ -864,14 +890,17 @@ program in C++.
<H4><a name="Ocaml_nn26"></a>22.2.5.4 Creating director objects</H4>
<p>
The definition of the actual object triangle can be described this way:
<blockquote><pre>
</p>
<div class="code"><pre>
let triangle =
new_derived_object
new_shape
(triangle_class ((0.0,0.0),(0.5,1.0),(1.0,0.0)))
'()
</pre></blockquote>
</pre></div>
<p>
The first argument to <tt>new_derived_object</tt>, new_shape is the method
@ -952,9 +981,11 @@ values will read zero, and struct or object returns have undefined results.
<H3><a name="Ocaml_nn31"></a>22.2.6 Exceptions</H3>
<p>
Catching exceptions is now supported using SWIG's %exception feature. A simple
but not too useful example is provided by the throw_exception testcase in
Examples/test-suite. You can provide your own exceptions, too.
</p>
</body>
</html>

725
SWIG/Doc/Manual/Perl5.html
View file

File diff suppressed because it is too large Load diff

115
SWIG/Doc/Manual/Php.html
View file

@ -3,11 +3,13 @@
<html>
<head>
<title>SWIG and PHP4</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>24 SWIG and PHP4</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Php_nn2">Preliminaries</a>
<li><a href="#Php_nn3">Building PHP4 Extensions</a>
@ -27,6 +29,7 @@
<li><a href="#Php_nn16">To be furthered...</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -52,12 +55,14 @@ of in the generated .php file in php.
<H2><a name="Php_nn2"></a>24.1 Preliminaries</H2>
<p>
In order to use this module, you will need to have a copy of the PHP 4.0 (or
above) include files to compile the SWIG generated files. You can find these
files by running <tt>'php-config --includes'</tt>. To test the modules you will
need either the php binary or the Apache php module. If you want to build your
extension into php directly (without having the overhead of loading it into
each script), you will need the complete PHP source tree available.
</p>
<H2><a name="Php_nn3"></a>24.2 Building PHP4 Extensions</H2>
@ -66,9 +71,9 @@ each script), you will need the complete PHP source tree available.
To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows :
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 example.i
</pre></blockquote>
</pre></div>
<p>
This will produce 3 files by default. The first file, <tt>example_wrap.c</tt>
@ -112,10 +117,10 @@ To build a dynamic module for PHP, you have two options. You can use the
To build manually, use a compile string similar to this (different for each
OS):
</p>
<blockquote><pre>
<div class="code"><pre>
cc -I.. $(PHPINC) -fpic -c example_wrap.c
cc -shared example_wrap.o -o libexample.so
</pre></blockquote>
</pre></div>
<p>
To build with phpize, after you have run swig you will need
@ -132,9 +137,9 @@ If you like SWIG can generate simple extra tests for libraries and header
files for you.
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote>
</pre></div>
<p>
Will include in the config.m4 search for libxapian.a or libxapian.so and
@ -164,17 +169,23 @@ To test the extension from a PHP script, you need to load it first. You do
this by putting the line,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("/path/to/modulename.so"); // Load the module
</pre></blockquote>
</pre></div>
<p>
at the start of each PHP file. SWIG also generates a php module, which
attempts to do the <tt>dl()</tt> call for you:
<blockquote><pre>
include("example.php");
</pre></blockquote>
</p>
<div class="code"><pre>
include("example.php");
</pre></div>
<p>
A more complicated method which builds the module directly into the <tt>php</tt>
executable is described <a href="n12">below</a>.
</p>
<H3><a name="Php_nn5"></a>24.2.2 Basic PHP4 interface</H3>
@ -187,23 +198,23 @@ C functions are converted into PHP functions. Default/optional arguments are
also allowed. An interface file like this :
</p>
<blockquote><pre>
<div class="code"><pre>
%module default
int foo(int a);
double bar(double, double b = 3.0);
...
</pre></blockquote>
</pre></div>
<p>
Will be accessed in PHP like this :
</p>
<blockquote><pre>
<div class="code"><pre>
dl("default.so"); $a = foo(2);
$b = bar(3.5, -1.5);
$c = bar(3.5); # Use default argument for 2nd parameter
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn7"></a>24.2.4 Global Variables</H3>
@ -217,24 +228,24 @@ ensuring changes made in PHP are updated in C ( and vice versa. ) Because this
is handled for you, you can modify the variables in PHP as normal, e.g.
</p>
<blockquote><pre>
<div class="code"><pre>
%module example;
...
double seki = 2;
...
int example_func(void);
</pre></blockquote>
</pre></div>
<p>
is accessed as follow :
</p>
<blockquote><pre>
<div class="code"><pre>
dl("example.so");
print $seki;
$seki = $seki * 2; # Does not affect C variable, still equal to 2
example_func(); # Syncs C variable to PHP Variable, now both 4
</pre></blockquote>
</pre></div>
<p>
SWIG supports global variables of all C datatypes including pointers and complex
@ -262,7 +273,7 @@ or by passing a null or empty value.
For structures and classes, SWIG produces accessor fuction for each member function and data. For example :
</p>
<blockquote><pre>
<div class="code"><pre>
%module vector
class Vector {
@ -273,13 +284,13 @@ public:
double magnitude();
};
</pre></blockquote>
</pre></div>
<p>
This gets turned into the following collection of PHP functions :
</p>
<blockquote><pre>
<div class="code"><pre>
Vector_x_set($obj);
Vector_x_get($obj);
Vector_y_set($obj);
@ -290,10 +301,13 @@ new_Vector();
delete_Vector($obj);
Vector_magnitude($obj);
</pre></blockquote>
</pre></div>
<p>
To use the class, simply use these functions. However, SWIG also has a mechanism
for creating proxy classes that hides these functions and uses an object
oriented interface instead - see <a href="n7">below</a>
</p>
<H3><a name="Php_nn10"></a>24.2.7 Constants</H3>
@ -305,20 +319,20 @@ directive. These will then be available from your PHP script as a PHP constant,
(e.g. no dollar sign is needed to access them. ) For example, with a swig file like this,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
#define PI 3.14159
%constant int E = 2.71828
</pre>
</blockquote>
</div>
<p>
you can access from in your php script like this,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("libexample.so");
echo "PI = " . PI . "\n";
@ -326,7 +340,7 @@ echo "PI = " . PI . "\n";
echo "E = " . E . "\n";
</pre>
</blockquote>
</div>
<p>
There are two peculiarities with using constants in PHP4. The first is that
@ -334,18 +348,18 @@ if you try to use an undeclared constant, it will evaulate to a string
set to the constants name. For example,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
#define EASY_TO_MISPELL 0
</pre>
</blockquote>
</div>
<p>
accessed incorrectly in PHP,
</p>
<blockquote>
<div class="code">
<pre>
dl("libexample.so");
@ -356,7 +370,7 @@ if(EASY_TO_MISPEL) {
}
</pre>
</blockquote>
</div>
<p>
will issue a warning about the undeclared constant, but will then evalute
@ -369,26 +383,26 @@ The second 'feature' is that although constants are case sensitive (by default),
you cannot declare a constant twice with alternative cases. E.g.,
</p>
<blockquote>
<div class="code">
<pre>
%module example
#define TEST Hello
#define Test World
</pre>
</blockquote>
</div>
<p>
accessed from PHP,
</p>
<blockquote>
<div class="code">
<pre>
dl("libexample.so");
echo TEST, Test;
</pre>
</blockquote>
</div>
<p>
will output "Hello Test" rather than "Hello World". This is because internally,
@ -417,9 +431,9 @@ can be be used directly in PHP scripts as objects and object methods. This is do
To have SWIG create proxy classes, use the <tt>-proxy</tt> option :
</p>
<blockquote><pre>
<div class="code"><pre>
% swig -php4 -proxy tbc.i
</pre></blockquote>
</pre></div>
<p>
This will produce the same files as before except that the final module
@ -473,11 +487,13 @@ when they each go out of scope.
<H3><a name="Php_nn13"></a>24.2.10 Static Member Variables</H3>
<p>
Class variables are not supported in PHP, however class functions are, using
'::' syntax. Static member variables are therefore accessed using a class
function with the same name, which returns the current value of the class variable. For example
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
class Ko {
@ -485,38 +501,43 @@ class Ko {
...
};
</pre></blockquote>
</pre></div>
<p>
would be accessed in PHP as,
</p>
<blockquote><pre>
<div class="code"><pre>
dl("libexample.so");
echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
</pre></div>
<p>
To set the static member variable, pass the value as the argument to the class function, e.g.
<blockquote><pre>
</p>
<div class="code"><pre>
Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn14"></a>24.2.11 PHP4 Pragmas</H3>
<p>
There are a few pragmas understood by the PHP4 module. The first,
<b>include</b> adds a file to be included by the generated PHP module. The
second, <b>code</b> adds literal code to the generated PHP module. The third,
<b>phpinfo</b> inserts code to the function called when PHP's phpinfo()
function is called.
</p>
<blockquote><pre>
<div class="code"><pre>
/* example.i */
%pragma(php4) include="foo.php"
@ -534,7 +555,7 @@ function is called.
"
%include "example.h"
</pre></blockquote>
</pre></div>
<H3><a name="Php_nn15"></a>24.2.12 Building extensions into php</H3>
@ -568,9 +589,9 @@ In most cases <tt>Makefile.in</tt> will be complete, especially if you
make use of <tt>-withlibs</tt> and <tt>-withincs</tt>
</p>
<blockquote><pre>
<div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></blockquote>
</pre></div>
<p>
Will include in the config.m4 and Makefile.in search for libxapian.a or

78
SWIG/Doc/Manual/Pike.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>SWIG and Pike</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>25 SWIG and Pike</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Pike_nn2">Preliminaries</a>
<ul>
@ -24,6 +26,7 @@
<li><a href="#Pike_nn12">Static Members</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -49,18 +52,29 @@ chapter.<br>
<H3><a name="Pike_nn3"></a>25.1.1 Running SWIG</H3>
<p>
Suppose that you defined a SWIG module such as the following:
<blockquote>
</p>
<div class="code">
<pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre>
</blockquote>
</div>
<p>
To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option :
<blockquote>
</p>
<div class="code">
<pre>$ <b>swig -pike example.i</b><br></pre>
</blockquote>
</div>
<p>
If you're building a C++ extension, be sure to add the <tt>-c++</tt> option:
<blockquote>
</p>
<div class="code">
<pre>$ <b>swig -c++ -pike example.i</b><br></pre>
</blockquote>
</div>
<p>
This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you
@ -77,9 +91,9 @@ of the wrapper file is <tt>example_wrap.c</tt>. To change this, you
can use the <tt>-o</tt> option:
</p>
<blockquote>
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</blockquote>
</div>
<H3><a name="Pike_nn4"></a>25.1.2 Getting the right header files</H3>
@ -89,9 +103,9 @@ path to the Pike header files. These files are usually contained in a
directory such as
</p>
<blockquote>
<div class="code">
<pre>/usr/local/pike/7.4.10/include/pike<br></pre>
</blockquote>
</div>
<p>
There doesn't seem to be any way to get Pike itself to reveal the
@ -103,15 +117,17 @@ and so on.
<H3><a name="Pike_nn5"></a>25.1.3 Using your module</H3>
<p>
To use your module, simply use Pike's <tt>import</tt> statement:
</p>
<blockquote><pre>
<div class="code"><pre>
$ <b>pike</b>
Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></blockquote>
</pre></div>
<H2><a name="Pike_nn6"></a>25.2 Basic C/C++ Mapping</H2>
@ -119,49 +135,59 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
<H3><a name="Pike_nn7"></a>25.2.1 Modules</H3>
<p>
All of the code for a given SWIG module is wrapped into a single Pike
module. Since the name of the shared library that implements your
module ultimately determines the module's name (as far as Pike is
concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>25.2.2 Functions</H3>
<p>
Global functions are wrapped as new Pike built-in functions. For
example,
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
int fact(int n);
</pre></blockquote>
</pre></div>
<p>
creates a new built-in function <tt>example.fact(n)</tt> that works
exactly as you'd expect it to:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>fact(4);</b>
(1) Result: 24
</pre></blockquote>
</pre></div>
<H3><a name="Pike_nn9"></a>25.2.3 Global variables</H3>
<p>
Global variables are currently wrapped as a pair of of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
<blockquote><pre>
<div class="code"><pre>
%module example
double Foo;
</pre></blockquote>
</pre></div>
<p>
will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
</p>
<blockquote><pre>
<div class="code"><pre>
&gt; <b>import example;</b>
&gt; <b>Foo_get();</b>
(1) Result: 3.000000
@ -169,43 +195,51 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(2) Result: 0
&gt; <b>Foo_get();</b>
(3) Result: 3.141590
</pre></blockquote>
</pre></div>
<H3><a name="Pike_nn10"></a>25.2.4 Constants and enumerated types</H3>
<p>
Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>25.2.5 Constructors and Destructors</H3>
<p>
Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
</p>
<H3><a name="Pike_nn12"></a>25.2.6 Static Members</H3>
<p>
Since Pike doesn't support static methods or data for Pike classes, static
member functions in your C++ classes are wrapped as regular functions and
static member variables are wrapped as pairs of functions (one to get the
value of the static member variable, and another to set it). The names of
these functions are prepended with the name of the class.
For example, given this C++ class declaration:
</p>
<blockquote><pre>
<div class="code"><pre>
class Shape
{
public:
static void print();
static int nshapes;
};
</pre></blockquote>
</pre></div>
<p>
SWIG will generate a <tt>Shape_print()</tt> method that invokes the static
<tt>Shape::print()</tt> member function, as well as a pair of methods,
<tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set
the value of <tt>Shape::nshapes</tt>.
</p>
</body>
</html>

35
SWIG/Doc/Manual/Preface.html
View file

@ -2,11 +2,13 @@
<html>
<head>
<title>Preface</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Preface"></a>1 Preface</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
@ -19,6 +21,7 @@
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
</ul>
</div>
<!-- INDEX -->
@ -26,6 +29,7 @@
<H2><a name="Preface_nn2"></a>1.1 Introduction</H2>
<p>
SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language
interfaces to C and C++ programs. Originally developed in 1995, SWIG was
first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for
@ -37,6 +41,7 @@ interface provided a simple yet highly flexible foundation for solving these
types of problems. SWIG simplifies development by largely automating
the task of scripting language integration--allowing developers and users
to focus on more important problems.
</p>
<p>
Although SWIG was originally developed for scientific applications, it
@ -47,6 +52,7 @@ is involved.
<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2>
<p>
Since SWIG was released in 1996, its user base and applicability has
continued to grow. Although its rate of development has varied, an
active development effort has continued to make improvements to the
@ -55,10 +61,12 @@ SWIG-2.0---a system that aims to provide wrapping support for nearly
all of the ANSI C++ standard and approximately ten target languages
including Guile, Java, Mzscheme, Ocaml, Perl, Pike, PHP, Python, Ruby,
and Tcl.
</p>
<H2><a name="Preface_nn4"></a>1.3 SWIG Versions</H2>
<p>
For several years, the most stable version of SWIG has been release
1.1p5. Starting with version 1.3, a new version numbering scheme has
been adopted. Odd version numbers (1.3, 1.5, etc.) represent
@ -66,15 +74,18 @@ development versions of SWIG. Even version numbers (1.4, 1.6, etc.)
represent stable releases. Currently, developers are working to
create a stable SWIG-2.0 release. Don't let the development status
of SWIG-1.3 scare you---it is much more stable (and capable) than SWIG-1.1p5.
</p>
<H2><a name="Preface_nn5"></a>1.4 SWIG resources</H2>
<p>
The official location of SWIG related material is
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org">http://www.swig.org</a>
</pre></blockquote>
</pre></div>
<p>
This site contains the latest version of the software, users guide,
@ -85,9 +96,9 @@ implementation tricks.
You can also subscribe to the SWIG mailing list by visiting the page
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org/mail.html">http://www.swig.org/mail.html</a>
</pre></blockquote>
</pre></div>
<p>
The mailing list often discusses some of the more technical aspects of
@ -99,9 +110,9 @@ CVS access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
<blockquote><pre>
<div class="code"><pre>
<a href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</a>
</pre></blockquote>
</pre></div>
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
@ -132,6 +143,7 @@ in C++, you may just want to skip those parts of the manual.
<H2><a name="Preface_nn7"></a>1.6 Organization of this manual</H2>
<p>
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
@ -139,16 +151,19 @@ contained. Thus, if you are using SWIG to build Python interfaces, you
can probably skip to that chapter and find almost everything you need
to know. Caveat: we are currently working on a documentation rewrite and many
of the older language module chapters are still somewhat out of date.
</p>
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
<p>
If you hate reading manuals, glance at the "Introduction" which
contains a few simple examples. These
examples contain about 95% of everything you need to know to use
SWIG. After that, simply use the language-specific chapters as a reference.
The SWIG distribution also comes with a large directory of
examples that illustrate different topics.
</p>
<H2><a name="Preface_nn9"></a>1.8 Backwards Compatibility</H2>
@ -180,11 +195,11 @@ This can be used in an interface file to define different typemaps, take
advantage of different features etc:
</p>
<blockquote><pre>
<div class="code"><pre>
#if SWIG_VERSION &gt;= 0x010311
/* Use some fancy new feature */
#endif
</pre></blockquote>
</pre></div>
<p>
Note: The version symbol is not defined in the generated SWIG
@ -194,12 +209,14 @@ wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
<H2><a name="Preface_nn10"></a>1.9 Credits</H2>
<p>
SWIG is an unfunded project that would not be possible without the
contributions of many people. Most recent SWIG development has been
supported by Matthias K&ouml;ppe, William Fulton, Lyle Johnson,
Richard Palmer, Thien-Thi Nguyen, Jason Stewart, Loic Dachary, Masaki
Fukushima, Luigi Ballabio, Sam Liddicott, Art Yerkes, Marcelo Matus,
Harco de Hilster, and John Lenz.
</p>
<p>
Historically, the following people contributed to early versions of SWIG.
@ -218,6 +235,7 @@ port.
<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
<p>
Although every attempt has been made to make SWIG bug-free, we are also trying
to make feature improvements that may introduce bugs.
To report a bug, either send mail to the SWIG developer
@ -227,6 +245,7 @@ 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. We
can only fix bugs if we know about them.
</p>
</body>
</html>

Some files were not shown because too many files have changed in this diff Show more