jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

merge revisions 11877-12162 from trunk to gsoc2009-matevz

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-matevz@12164 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2010-07-20 23:35:40 +00:00
commit 25ff4e4927
563 changed files with 22912 additions and 17189 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Devel/cmdopt.html
View file

@ -36,7 +36,7 @@ functions to mark whether or not a particular command line option was used. Thi
<h2>Argument Marking</h2>
As command line options are are processed by language modules, the following functions are used
As command line options are processed by language modules, the following functions are used
to mark the arguments as used:
<p>

17
Doc/Devel/engineering.html
View file

@ -119,22 +119,25 @@ are case-insensitive on Windows so this convention will prevent you from inadver
creating two files that differ in case-only.
<p>
Each file should include a short abstract, author information, copyright information, and
Each file should include a short abstract, license information and
a SVN revision tag like this:
<blockquote>
<pre>
/* -----------------------------------------------------------------------------
* See the LICENSE file for information on copyright, usage and redistribution
* of SWIG, and the README file for authors - http://www.swig.org/release.html.
* This file is part of SWIG, which is licensed as a whole under version 3
* (or any later version) of the GNU General Public License. Some additional
* terms also apply to certain portions of SWIG. The full details of the SWIG
* license and copyrights can be found in the LICENSE and COPYRIGHT files
* included with the SWIG source code as distributed by the SWIG developers
* and at http://www.swig.org/legal.html.
*
* cwrap.c
* xxx.c
*
* This file defines a variety of wrapping rules for C/C++ handling including
* the naming of local variables, calling conventions, and so forth.
* This file defines ...
* ----------------------------------------------------------------------------- */
char cvsroot_cwrap_c[] = "$Id$";
static char cvs[] = "&#36Id&#36 xxx.c";
#include "swig.h"

92
Doc/Devel/internals.html
View file

@ -42,11 +42,9 @@ David M. Beazley <br>
</ul>
<li><a name="i3" href="#3">3. Types and Typemaps</a>
<li><a name="i4" href="#4">4. Parsing</a>
<li><a name="i5" href="#5">5. Difference Between SWIG 1.1 and SWIG 1.3</a>
<li><a name="i6" href="#6">6. Plans for SWIG 2.0</a>
<li><a name="i7" href="#7">7. C/C++ Wrapper Support Functions</a>
<li><a name="i8" href="#8">8. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i9" href="#9">9. Debugging SWIG</a>
<li><a name="i5" href="#5">5. C/C++ Wrapper Support Functions</a>
<li><a name="i6" href="#6">6. Symbol Naming Guidelines for Generated C/C++ Code</a>
<li><a name="i7" href="#7">7. Debugging SWIG</a>
</ul>
<a name="1" href="#i1">
@ -76,9 +74,8 @@ to code).
<tr><td>Examples</td>
<td>This subdir tree contains examples of using SWIG w/ different
scripting languages, including makefiles. Typically, there are the
"simple" and "matrix" examples, w/ some languages offering additional
examples. The GIFPlot example has its own set of per-language
subdirectories. See the README more index.html file in each directory
"simple" and "class" examples, w/ some languages offering additional
examples. See the README more index.html file in each directory
for more info. [FIXME: Ref SWIG user manual.]</td>
</tr>
@ -97,55 +94,35 @@ info.</td>
</tr>
<tr><td>Source</td>
<td>SWIG source code is in this subdir tree. Directories marked w/ "(*)"
are used in building the <tt>swig</tt> executable.
<td>The C and C++ source code for the <tt>swig</tt> executable is in this
subdir tree.</td>
<table border=1>
<tr><td>DOH (*)</td>
<tr><td>DOH</td>
<td>C library providing memory allocation, file access and generic
containers. Result: libdoh.a</td>
containers.</td>
</tr>
<tr><td>Experiment</td>
<td>[TODO]</td>
</tr>
<tr><td>Include (*)</td>
<tr><td>Include</td>
<td>Configuration .h files</td>
</tr>
<tr><td>LParse</td>
<td>Parser (lex / yacc) files and support [why not (*)?!]</td>
<tr><td>CParse</td>
<td>Parser (lex / yacc) files and support</td>
</tr>
<tr><td>Modules</td>
<td>[TODO]</td>
</tr>
<tr><td>Modules1.1 (*)</td>
<td>Language-specific callbacks that does actual code generation (each
language has a .cxx and a .h file). Result: libmodules11.a</td>
language has a .cxx and a .h file).</td>
</tr>
<tr><td>Preprocessor (*)</td>
<td>SWIG-specialized C/C++ preprocessor. Result: libcpp.a</td>
<tr><td>Preprocessor</td>
<td>SWIG-specialized C/C++ preprocessor.</td>
</tr>
<tr><td>SWIG1.1 (*)</td>
<td>Parts of SWIG that are not language-specific, including option
processing and the type-mapping system. Result: libswig11.a.
Note: This directory is currently being phased out. </td>
</tr>
<tr><td>SWIG1.3</td>
<td>[TODO] [funny, nothing here is presently used for swig-1.3].
This directory might turn into a compatibility interface between
SWIG1.3 and the SWIG1.1 modules.</td>
</tr>
<tr><td>Swig (*)</td>
<td>This directory contains the new ANSI C core of the system
<tr><td>Swig</td>
<td>This directory contains the ANSI C core of the system
and contains generic functions related to types, file handling,
scanning, and so forth.</td>
</tr>
@ -154,7 +131,7 @@ are used in building the <tt>swig</tt> executable.
</tr>
<tr><td>Tools</td>
<td>Libtool support and the mkdist.py script.</td>
<td>The mkdist.py script and other tools.</td>
</tr>
<tr><td>Win</td>
@ -173,14 +150,14 @@ to look for code:
<ul>
<li> <tt>Modules1.1/swigmain.cxx:main()</tt> is the program entry
<li> <tt>Modules/swigmain.cxx:main()</tt> is the program entry
point. It parses the language-specifying command-line option (for
example, <tt>-java</tt>), creating a new language-specific wrapping
object (each language is a C++ class derived from base class
<tt>Language</tt>). This object and the command-line is passed to
<tt>SWIG_main()</tt>, whose return value is the program exit value.
<li> <tt>SWIG1.1/main.cxx:SWIG_main()</tt> is the "real" main. It
<li> <tt>Modules/main.cxx:SWIG_main()</tt> is the "real" main. It
initializes the preprocessor and typemap machinery, defines some
preprocessor symbols, locates the SWIG library, processes common
command-line options, and then calls the language-specific command-line
@ -203,7 +180,7 @@ included <tt>-freeze</tt>, go into an infinite loop; otherwise return the
error count.
<li> The language-specific <tt>parse()</tt> (and all other
language-specific code) lives in <tt>Modules1.1/foo.{h,cxx}</tt> for
language-specific code) lives in <tt>Modules/foo.{h,cxx}</tt> for
language Foo. Typically, <tt>FOO::parse()</tt> calls
<tt>FOO::headers()</tt> and then the global function <tt>yyparse()</tt>,
which uses the callbacks registered by <tt>SWIG_main()</tt> above.
@ -553,8 +530,7 @@ list item: listval5
The representation and manipulation of types is currently in the
process of being reorganized and (hopefully) simplified. The
following list describes the current set of functions that are used to
manipulate datatypes. These functions are different than in
SWIG1.1 and may change names in the final SWIG1.3 release.
manipulate datatypes.
<ul>
<li><tt>SwigType_str(SwigType *t, char *name)</tt>.<br>
@ -710,19 +686,7 @@ repeated calls without making any copies.
[TODO]
<a name="5" href="#i5">
<h2>5. Difference Between SWIG 1.1 and SWIG 1.3</h2>
</a>
[TODO]
<a name="6" href="#i6">
<h2>6. Plans for SWIG 2.0</h2>
</a>
[TODO]
<a name="7" href="#i7">
<h2>7. The C/C++ Wrapping Layer</h2>
<h2>5. The C/C++ Wrapping Layer</h2>
</a>
Added: Dave Beazley (July 22, 2000)
@ -1001,8 +965,8 @@ for specifying local variable declarations and argument conversions.
<a name="8" href="#i8">
<h2>8. Symbol Naming Guidelines for Generated C/C++ Code</h2>
<a name="6" href="#i6">
<h2>6. Symbol Naming Guidelines for Generated C/C++ Code</h2>
</a>
The C++ standard (ISO/IEC 14882:1998(E)) states:
<blockquote>
@ -1048,8 +1012,8 @@ For code compiled as C or C++ that attempts to mangle a wrapped symbol:
In the past SWIG has generated many symbols which flout the standard especially double underscores. In fact they may not all be rooted out yet, so please fix them when you see them.
<a name="9" href="#i9">
<h2>9. Debugging SWIG</h2>
<a name="7" href="#i7">
<h2>7. Debugging SWIG</h2>
</a>
Warning. Debugging SWIG is for the very patient.
<p>
@ -1100,7 +1064,7 @@ Please also read the Debugging Functions section in <a href="tree.html">SWIG Par
</p>
<hr>
Copyright (C) 1999-2004 SWIG Development Team.
Copyright (C) 1999-2010 SWIG Development Team.
</body>
</html>

9
Doc/Devel/scanner.html
View file

@ -77,7 +77,7 @@ string prior to using this function.
Pushes a token into the scanner. This exact token will be returned by the next call to <tt>Scanner_token()</tt>.
<tt>tokvalue</tt> is the integer token value to return and <tt>val</tt> is the token text to return. This
function is only used to handle very special parsing cases. For instance, if you need the scanner to
return a ficticious token into order to enter a special parsing case.
return a fictitious token into order to enter a special parsing case.
</blockquote>
<p>
@ -238,7 +238,7 @@ SWIG_TOKEN_PERIOD .
SWIG_TOKEN_AT @
SWIG_TOKEN_DOLLAR $
SWIG_TOKEN_ENDLINE Literal newline
SWIG_TOKEN_ID identifer
SWIG_TOKEN_ID identifier
SWIG_TOKEN_FLOAT Floating point with F suffix (e.g., 3.1415F)
SWIG_TOKEN_DOUBLE Floating point (e.g., 3.1415 )
SWIG_TOKEN_INT Integer (e.g., 314)
@ -281,8 +281,3 @@ using these functions to write a yacc-compatible lexer.
</body>
</html>

4
Doc/Manual/Allegrocl.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Allegrocl_nn1"></a>17 SWIG and Allegro Common Lisp</H1>
<H1><a name="Allegrocl"></a>17 SWIG and Allegro Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -1777,7 +1777,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN)
</div>
<p>
These three typemaps are specifically employed by the the
These three typemaps are specifically employed by the
Allegro CL interface generator. SWIG also implements a number of
other typemaps that can be used for generating code in the C/C++
wrappers. You can read about

2
Doc/Manual/Arguments.html
View file

@ -81,7 +81,7 @@ One way to deal with this is to use the
%include "typemaps.i"
%apply double *OUTPUT { double *result };
%inlne %{
%inline %{
extern void add(double a, double b, double *result);
%}
</pre></div>

143
Doc/Manual/CSharp.html
View file

@ -9,35 +9,36 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#csharp_introduction">Introduction</a>
<li><a href="#csharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_introduction">Introduction</a>
<li><a href="#CSharp_differences_java">Differences to the Java module</a>
<li><a href="#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="#CSharp_arrays_swig_library">The SWIG C arrays library</a>
<li><a href="#CSharp_arrays_pinvoke_default_array_marshalling">Managed arrays using P/Invoke default array marshalling</a>
<li><a href="#CSharp_arrays_pinning">Managed arrays using pinning</a>
</ul>
<li><a href="#csharp_exceptions">C# Exceptions</a>
<li><a href="#CSharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#csharp_custom_application_exception">Custom C# ApplicationException example</a>
<li><a href="#CSharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#CSharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#CSharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#CSharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
<li><a href="#csharp_directors">C# Directors</a>
<li><a href="#CSharp_directors">C# Directors</a>
<ul>
<li><a href="#csharp_directors_example">Directors example</a>
<li><a href="#csharp_directors_implementation">Directors implementation</a>
<li><a href="#csharp_director_caveats">Director caveats</a>
<li><a href="#CSharp_directors_example">Directors example</a>
<li><a href="#CSharp_directors_implementation">Directors implementation</a>
<li><a href="#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="#csharp_typemap_examples">C# Typemap examples</a>
<li><a href="#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#csharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="#csharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="#csharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#csharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="#CSharp_enum_underlying_type">Underlying type for enums</a>
</ul>
</ul>
</div>
@ -45,7 +46,7 @@
<H2><a name="csharp_introduction"></a>18.1 Introduction</H2>
<H2><a name="CSharp_introduction"></a>18.1 Introduction</H2>
<p>
@ -54,7 +55,7 @@ The wrapper code implementation uses C# and the Platform Invoke (PInvoke) interf
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.
It is also better suited for robust production environments due to the Managed C++ flaw called the
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vcconMixedDLLLoadingProblem.asp">Mixed DLL Loading Problem</a>.
<a href="http://msdn.microsoft.com/en-us/library/aa290048(VS.71).aspx">Mixed DLL Loading Problem</a>.
SWIG C# works equally well on non-Microsoft operating systems such as Linux, Solaris and Apple Mac using
<a href="http://www.mono-project.com/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
</p>
@ -65,7 +66,7 @@ The <a href="http://msdn.microsoft.com">Microsoft Developer Network (MSDN)</a> h
Monodoc, available from the Mono project, has a very useful section titled <a href="http://www.mono-project.com/Interop_with_Native_Libraries">Interop with native libraries</a>.
</p>
<H2><a name="csharp_differences_java"></a>18.2 Differences to the Java module</H2>
<H2><a name="CSharp_differences_java"></a>18.2 Differences to the Java module</H2>
<p>
@ -102,6 +103,11 @@ namespace com.bloggs.widget {
Note that by default, the generated C# classes have no namespace and the module name is unrelated to namespaces. The module name is just like in Java and is merely used to name some of the generated classes.
</li>
<li>
The <a href="SWIGPlus.html#SWIGPlus_nspace">nspace feature</a> is also supported as described in this general section with a C# example.
Unlike Java which requires the use of the -package option when using the <tt>nspace</tt> feature, the -namespace option is not mandatory for C#.
</li>
<li>
The <tt>-dllimport &lt;name&gt;</tt> commandline option specifies the name of the DLL for the <tt>DllImport</tt> attribute for every PInvoke method. If this commandline option is not given, the <tt>DllImport</tt> DLL name is the same as the module name. This option is useful for when one wants to invoke SWIG multiple times on different modules, yet compile all the resulting code into a single DLL.
</li>
@ -132,7 +138,7 @@ If it was used, it would generate an illegal runtime initialisation via a PInvok
C# doesn't support the notion of throws clauses.
Therefore there is no 'throws' typemap attribute support for adding exception classes to a throws clause.
Likewise there is no need for an equivalent to <tt>%javaexception</tt>.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#csharp_exceptions">C# Exceptions</a> below.
In fact, throwing C# exceptions works quite differently, see <a href="CSharp.html#CSharp_exceptions">C# Exceptions</a> below.
</li>
<li>
@ -201,6 +207,7 @@ jniclassinterfaces -&gt; imclassinterfaces
$javaclassname -&gt; $csclassname
$&amp;javaclassname -&gt; $&amp;csclassname
$*javaclassname -&gt; $*csclassname
$javaclazzname -&gt; $csclazzname
$javainput -&gt; $csinput
$jnicall -&gt; $imcall
</pre></div>
@ -210,10 +217,10 @@ $jnicall -&gt; $imcall
<p>
Unlike the "javain" typemap, the "csin" typemap does not support the 'pgcpp' attribute as the C# module does not have a premature garbage collection prevention parameter.
The "csin" typemap supports additional optional attributes called 'cshin' and 'terminator'.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'cshin' attribute should contain the parameter type and name whenever a <a href="Java.html#Java_constructor_helper_function">constructor helper function</a> is generated due to the 'pre' or 'post' attributes.
The 'terminator' attribute normally just contains a closing brace for when the 'pre' attribute contains an opening brace, such as when a C# <tt>using</tt> or <tt>fixed</tt> block is started.
Note that 'pre', 'post', 'terminator' and 'cshin' attributes are not used for marshalling the property set.
Please see the <a href="#csharp_date_marshalling">Date marshalling example</a> and <a href="#csharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
Please see the <a href="#CSharp_date_marshalling">Date marshalling example</a> and <a href="#CSharp_date_properties">Date marshalling of properties example</a> for further understanding of these "csin" applicable attributes.
</p>
</li>
@ -250,7 +257,7 @@ public static extern IntPtr function(string jarg1);
Support for type attributes.
The 'imtype' and 'cstype' typemaps can have an optional <tt>inattributes</tt> and <tt>outattributes</tt> typemap attribute.
The 'imtype' typemap can also have an optional <tt>directorinattributes</tt> and <tt>directoroutattributes</tt>
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#csharp_directors_implementation">directors implementation</a>.
typemap attribute which attaches to director delegates, an implementation detail of directors, see <a href="#CSharp_directors_implementation">directors implementation</a>.
Note that there are C# attributes and typemap attributes, don't get confused between the two!!
The C# attributes specified in these typemap attributes are generated wherever the type is used in the C# wrappers.
These can be used to specify any C# attribute associated with a C/C++ type, but are more typically used for the C# <tt>MarshalAs</tt> attribute.
@ -305,7 +312,7 @@ The <tt>directorinattributes</tt> and <tt>directoroutattributes</tt> typemap att
<li>
<p>
Support for attaching C# attributes to wrapped methods, variables and enum values.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#features">%feature directives</a>.
This is done using the <tt>%csattributes</tt> feature, see <a href="Customization.html#Customization_features">%feature directives</a>.
Note that C# attributes are attached to proxy classes and enums using the <tt>csattributes</tt> typemap.
For example, imagine we have a custom attribute class, <tt>ThreadSafeAttribute</tt>, for labelling thread safety.
The following SWIG code shows how to attach this C# attribute to some methods and the class declaration itself:
@ -401,7 +408,7 @@ This feature is useful for some obscure cases where SWIG might get the <tt>virtu
</li>
<li>
<a name="csharp_module_directive"></a>
<a name="CSharp_module_directive"></a>
<p>
The name of the intermediary class can be changed from its default, that is, the module name with PINVOKE appended after it.
The module directive attribute <tt>imclassname</tt> is used to achieve this:
@ -436,7 +443,7 @@ if specified, otherwise it is equivalent to the <b>$module</b> special variable.
<p>
<b><tt>$imclassname</tt></b><br>
This special variable expands to the intermediary class name. For C# this is usually the same as '$modulePINVOKE' ('$moduleJNI' for Java),
unless the imclassname attribute is specified in the <a href="CSharp.html#csharp_module_directive">%module directive</a>.
unless the imclassname attribute is specified in the <a href="CSharp.html#CSharp_module_directive">%module directive</a>.
</p>
<p>
@ -505,7 +512,7 @@ In the P/Invoke default marshalling scheme, one needs to designate whether the i
array parameter as input, output, or both. When the function is invoked, the CLR allocates a separate chunk of memory as big as the given managed array,
which is automatically released at the end of the function call. If the array parameter is marked as being input, the content of the managed array is copied
into this buffer when the call is made. Correspondingly, if the array parameter is marked as being output, the contents of the reserved buffer are copied
back into the managed array after the call returns. A pointer to to this buffer
back into the managed array after the call returns. A pointer to this buffer
is passed to the native function.
</p>
@ -716,7 +723,7 @@ public static extern void myArrayCopy(IntPtr jarg1, IntPtr jarg2, int jarg3);
<H2><a name="csharp_exceptions"></a>18.4 C# Exceptions</H2>
<H2><a name="CSharp_exceptions"></a>18.4 C# Exceptions</H2>
<p>
@ -724,7 +731,7 @@ It is possible to throw a C# Exception from C/C++ code.
SWIG already provides the framework for throwing C# exceptions if it is able to detect that a C++ exception could be thrown.
Automatically detecting that a C++ exception could be thrown is only possible when a C++ exception specification is used,
see <a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>.
The <a href="Customization.html#exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
The <a href="Customization.html#Customization_exception">Exception handling with %exception</a> section details the <tt>%exception</tt> feature.
Customised code for handling exceptions with or without a C++ exception specification is possible and the details follow.
However anyone wishing to do this should be familiar with the contents of the sections referred to above.
</p>
@ -813,7 +820,7 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="csharp_exception_example_check_typemap"></a>18.4.1 C# exception example using "check" typemap</H3>
<H3><a name="CSharp_exception_example_check_typemap"></a>18.4.1 C# exception example using "check" typemap</H3>
<p>
@ -995,12 +1002,12 @@ method and C# code does not handle pending exceptions via the canthrow attribute
Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
</P>
<H3><a name="csharp_exception_example_percent_exception"></a>18.4.2 C# exception example using %exception</H3>
<H3><a name="CSharp_exception_example_percent_exception"></a>18.4.2 C# exception example using %exception</H3>
<p>
Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#exception">Exception handling with %exception</a>.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#Customization_exception">Exception handling with %exception</a>.
</p>
<div class="code">
@ -1060,7 +1067,7 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="csharp_exception_example_exception_specifications"></a>18.4.3 C# exception example using exception specifications</H3>
<H3><a name="CSharp_exception_example_exception_specifications"></a>18.4.3 C# exception example using exception specifications</H3>
<p>
@ -1117,7 +1124,7 @@ SWIGEXPORT void SWIGSTDCALL CSharp_evensonly(int jarg1) {
Multiple catch handlers are generated should there be more than one exception specifications declared.
</p>
<H3><a name="csharp_custom_application_exception"></a>18.4.4 Custom C# ApplicationException example</H3>
<H3><a name="CSharp_custom_application_exception"></a>18.4.4 Custom C# ApplicationException example</H3>
<p>
@ -1251,7 +1258,7 @@ try {
</pre>
</div>
<H2><a name="csharp_directors"></a>18.5 C# Directors</H2>
<H2><a name="CSharp_directors"></a>18.5 C# Directors</H2>
<p>
@ -1261,10 +1268,10 @@ Essentially, it enables unmanaged C++ code to call back into managed code for vi
<p>
The following sections provide information on the C# director implementation and contain most of the information required to use the C# directors.
However, the <a href="Java.html#java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
However, the <a href="Java.html#Java_directors">Java directors</a> section should also be read in order to gain more insight into directors.
</p>
<H3><a name="csharp_directors_example"></a>18.5.1 Directors example</H3>
<H3><a name="CSharp_directors_example"></a>18.5.1 Directors example</H3>
<p>
@ -1385,7 +1392,7 @@ CSharpDerived - UIntMethod(123)
</pre>
</div>
<H3><a name="csharp_directors_implementation"></a>18.5.2 Directors implementation</H3>
<H3><a name="CSharp_directors_implementation"></a>18.5.2 Directors implementation</H3>
<p>
@ -1571,7 +1578,7 @@ void SwigDirector_Base::BaseBoolMethod(Base const &amp;b, bool flag) {
</pre>
</div>
<H3><a name="csharp_director_caveats"></a>18.5.3 Director caveats</H3>
<H3><a name="CSharp_director_caveats"></a>18.5.3 Director caveats</H3>
<p>
@ -1619,7 +1626,7 @@ However, a call from C# to <tt>CSharpDefaults.DefaultMethod()</tt> will of cours
should pass the call on to <tt>CSharpDefaults.DefaultMethod(int)</tt>using the C++ default value, as shown above.
</p>
<H2><a name="csharp_typemap_examples"></a>18.6 C# Typemap examples</H2>
<H2><a name="CSharp_typemap_examples"></a>18.6 C# Typemap examples</H2>
This section includes a few examples of typemaps. For more examples, you
@ -1627,12 +1634,12 @@ might look at the files "<tt>csharp.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<H3><a name="csharp_memory_management_member_variables"></a>18.6.1 Memory management when returning references to member variables</H3>
<H3><a name="CSharp_memory_management_member_variables"></a>18.6.1 Memory management when returning references to member variables</H3>
<p>
This example shows how to prevent premature garbage collection of objects when the underlying C++ class returns a pointer or reference to a member variable.
The example is a direct equivalent to this <a href="Java.html#java_memory_management_objects">Java equivalent</a>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
</p>
<p>
@ -1751,11 +1758,11 @@ public class Bike : IDisposable {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="csharp_memory_management_objects"></a>18.6.2 Memory management for objects passed to the C++ layer</H3>
<H3><a name="CSharp_memory_management_objects"></a>18.6.2 Memory management for objects passed to the C++ layer</H3>
<p>
The example is a direct equivalent to this <a href="Java.html#java_memory_management_objects">Java equivalent</a>.
The example is a direct equivalent to this <a href="Java.html#Java_memory_management_objects">Java equivalent</a>.
Managing memory can be tricky when using C++ and C# proxy classes.
The previous example shows one such case and this example looks at memory management for a class passed to a C++ method which expects the object to remain in scope
after the function has returned. Consider the following two C++ classes:
@ -1870,14 +1877,14 @@ The 'cscode' typemap simply adds in the specified code into the C# proxy class.
</div>
<H3><a name="csharp_date_marshalling"></a>18.6.3 Date marshalling using the csin typemap and associated attributes</H3>
<H3><a name="CSharp_date_marshalling"></a>18.6.3 Date marshalling using the csin typemap and associated attributes</H3>
<p>
The <a href="Java.html#nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
The <a href="Java.html#Java_nan_exception_typemap">NaN Exception example</a> is a simple example of the "javain" typemap and its 'pre' attribute.
This example demonstrates how a C++ date class, say <tt>CDate</tt>, can be mapped onto the standard .NET date class,
<tt>System.DateTime</tt> by using the 'pre', 'post' and 'pgcppname' attributes of the "csin" typemap (the C# equivalent to the "javain" typemap).
The example is an equivalent to the <a href="Java.html#java_date_marshalling">Java Date marshalling example</a>.
The example is an equivalent to the <a href="Java.html#Java_date_marshalling">Java Date marshalling example</a>.
The idea is that the <tt>System.DateTime</tt> is used wherever the C++ API uses a <tt>CDate</tt>.
Let's assume the code being wrapped is as follows:
</p>
@ -2154,7 +2161,7 @@ public class example {
</pre>
</div>
<H3><a name="csharp_date_properties"></a>18.6.4 A date example demonstrating marshalling of C# properties</H3>
<H3><a name="CSharp_date_properties"></a>18.6.4 A date example demonstrating marshalling of C# properties</H3>
<p>
@ -2255,7 +2262,7 @@ Some points to note:
</ul>
<H3><a name="csharp_partial_classes"></a>18.6.5 Turning wrapped classes into partial classes</H3>
<H3><a name="CSharp_partial_classes"></a>18.6.5 Turning wrapped classes into partial classes</H3>
<p>
@ -2355,7 +2362,7 @@ demonstrating that the class contains methods calling both unmanaged code - <tt>
The following example is an alternative approach to adding managed code to the generated proxy class.
</p>
<H3><a name="csharp_extending_proxy_class"></a>18.6.6 Extending proxy classes with additional C# code</H3>
<H3><a name="CSharp_extending_proxy_class"></a>18.6.6 Extending proxy classes with additional C# code</H3>
<p>
@ -2394,6 +2401,38 @@ public class ExtendMe : IDisposable {
</pre>
</div>
<H3><a name="CSharp_enum_underlying_type"></a>18.6.7 Underlying type for enums</H3>
<P>
C# enums use int as the underlying type for each enum item.
If you wish to change the underlying type to something else, then use the <tt>csbase</tt> typemap.
For example when your C++ code uses a value larget than int, this is necessary as the C# compiler will not compile values which are too large to fit into an int.
Here is an example:
</p>
<div class="code">
<pre>
%typemap(csbase) BigNumbers "uint"
%inline %{
enum BigNumbers { big=0x80000000, bigger };
%}
</pre>
</div>
<p>
The generated enum will then use the given underlying type and compile correctly:
</p>
<div class="code">
<pre>
public enum BigNumbers : uint {
big = 0x80000000,
bigger
}
</pre>
</div>
</body>
</html>

23
Doc/Manual/Chicken.html
View file

@ -35,7 +35,7 @@
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#collection">Garbage collection</a>
<li><a href="#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
<ul>
@ -80,14 +80,13 @@
relies on some recent additions to CHICKEN, which are only
present in releases of CHICKEN with version number
<strong>greater than or equal to 1.89</strong>.
To use a chicken version between 1.40 and 1.89, see the <a href="#collection">Garbage collection</a>
To use a chicken version between 1.40 and 1.89, see the <a href="#Chicken_collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
or Examples/GIFPlot/Chicken for the basic steps to run SWIG
CHICKEN.
directory for the basic steps to run SWIG CHICKEN.
</p>
<H3><a name="Chicken_nn3"></a>19.1.1 Running SWIG in C mode</H3>
@ -226,7 +225,7 @@
a function that must be called, the constant will appear as a
scheme variable. This causes the generated .scm file to just contain the code
<tt>(set! MYCONSTANT1 (MYCONSTANT1))</tt>. See
<a href="Customization.html#features">Features and the %feature directive</a>
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.
</p>
@ -254,7 +253,7 @@
<p>The SWIG chicken module has support for exceptions thrown from
C or C++ code to be caught in scheme.
See <a href="Customization.html#exception">Exception handling with %exception</a>
See <a href="Customization.html#Customization_exception">Exception handling with %exception</a>
for more information about declaring exceptions in the interface file.
</p>
@ -263,7 +262,7 @@
inside the %exception blocks. <code>SWIG_exception</code> will throw a list consisting of the code
(as an integer) and the message. Both of these will throw an exception using <code>(abort)</code>,
which can be handled by <code>(handle-exceptions)</code>. See
<a href="http://www.call-with-current-continuation.org/manual/Exceptions.html#Exceptions">Chicken manual on Exceptions</a>
the Chicken manual on Exceptions
and <a href="http://srfi.schemers.org/srfi-12/srfi-12.html">SFRI-12</a>. Since the exception values are thrown
directly, if <code>(condition-case)</code> is used to catch an exception the exception will come through in the <code>val ()</code> case.
</p>
@ -417,8 +416,8 @@ $ csc -sv modname.scm modname_wrap.c modname_impl.c -o modname.so
</div>
<p>This library can then be loaded by scheme code with the <code>(require 'modname)</code> function.
See <a href="http://www.call-with-current-continuation.org/manual/Loading-extension-libraries.html">
Loading-extension-libraries</a> in the eval unit inside the CHICKEN manual for more information.</p>
See the
Loading-extension-libraries in the eval unit inside the CHICKEN manual for more information.</p>
<p>Another alternative is to run SWIG normally and create a scheme file that contains <code>(declare (uses <i>modname</i>))</code>
and then compile that file into the shared library as well. For example, inside the <tt>mod_load.scm</tt> file,</p>
@ -520,7 +519,7 @@ all the modules.</p>
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="collection"></a>19.6.1 Garbage collection</H3>
<H3><a name="Chicken_collection"></a>19.6.1 Garbage collection</H3>
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
@ -531,12 +530,12 @@ all the modules.</p>
be garbage collected, SWIG will automatically set the owner flag to 1. For other functions,
the <code>%newobject</code> directive must be specified for functions whose return values
should be garbage collected. See
<a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
<a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more information.
</p>
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
After applying this typemap (see the <a href="Typemaps.html#Typemaps">Typemaps chapter</a> for more information on how to apply typemaps),
any pointer that gets passed in will no longer be garbage collected.
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might

395
Doc/Manual/Contents.html
View file

@ -15,13 +15,12 @@
<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>
<li><a href="Preface.html#Preface_nn4">SWIG Versions</a>
<li><a href="Preface.html#Preface_nn5">SWIG resources</a>
<li><a href="Preface.html#Preface_nn6">Prerequisites</a>
<li><a href="Preface.html#Preface_nn7">Organization of this manual</a>
<li><a href="Preface.html#Preface_nn8">How to avoid reading the manual</a>
<li><a href="Preface.html#Preface_nn9">Backwards Compatibility</a>
<li><a href="Preface.html#Preface_nn9">Backwards compatibility</a>
<li><a href="Preface.html#Preface_nn10">Credits</a>
<li><a href="Preface.html#Preface_nn11">Bug reports</a>
</ul>
@ -122,7 +121,7 @@
<li><a href="SWIG.html#SWIG_nn2">Running SWIG</a>
<ul>
<li><a href="SWIG.html#SWIG_nn3">Input format</a>
<li><a href="SWIG.html#output">SWIG Output</a>
<li><a href="SWIG.html#SWIG_output">SWIG Output</a>
<li><a href="SWIG.html#SWIG_nn5">Comments</a>
<li><a href="SWIG.html#SWIG_nn6">C Preprocessor</a>
<li><a href="SWIG.html#SWIG_nn7">SWIG Directives</a>
@ -223,21 +222,24 @@
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="SWIGPlus.html#SWIGPlus_class_extension">Class extension</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn30">Templates</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn31">Namespaces</a>
<li><a href="SWIGPlus.html#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="SWIGPlus.html#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="SWIGPlus.html#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="SWIGPlus.html#SWIGPlus_smart_pointers">Smart pointers and operator-&gt;()</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn35">Using declarations and inheritance</a>
<li><a href="SWIGPlus.html#SWIGPlus_nested_classes">Nested classes</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn37">A brief rant about const-correctness</a>
<li><a href="SWIGPlus.html#SWIGPlus_const">A brief rant about const-correctness</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn42">Where to go for more information</a>
</ul>
</div>
@ -285,9 +287,10 @@
</ul>
<li><a href="Library.html#Library_stl_cpp_library">STL/C++ Library</a>
<ul>
<li><a href="Library.html#Library_nn14">std_string.i</a>
<li><a href="Library.html#Library_nn15">std_vector.i</a>
<li><a href="Library.html#Library_std_string">std::string</a>
<li><a href="Library.html#Library_std_vector">std::vector</a>
<li><a href="Library.html#Library_stl_exceptions">STL exceptions</a>
<li><a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a>
</ul>
<li><a href="Library.html#Library_nn16">Utility Libraries</a>
<ul>
@ -333,6 +336,7 @@
<li><a href="Typemaps.html#Typemaps_nn6">Reusing typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn7">What can be done with typemaps?</a>
<li><a href="Typemaps.html#Typemaps_nn8">What can't be done with typemaps?</a>
<li><a href="Typemaps.html#Typemaps_aspects">Similarities to Aspect Oriented Programming</a>
<li><a href="Typemaps.html#Typemaps_nn9">The rest of this chapter</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn10">Typemap specifications</a>
@ -346,10 +350,10 @@
<li><a href="Typemaps.html#Typemaps_pattern_matching">Pattern matching rules</a>
<ul>
<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</a>
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions</a>
<li><a href="Typemaps.html#Typemaps_nn19">Default typemaps</a>
<li><a href="Typemaps.html#Typemaps_mixed_default">Mixed default typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn20">Multi-arguments typemaps</a>
<li><a href="Typemaps.html#Typemaps_typedef_reductions">Typedef reductions matching</a>
<li><a href="Typemaps.html#Typemaps_nn19">Default typemap matching rules</a>
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps_patterns">Multi-arguments typemaps</a>
<li><a href="Typemaps.html#Typemaps_matching_template_comparison">Matching rules compared to C++ templates</a>
<li><a href="Typemaps.html#Typemaps_debugging_search">Debugging typemap pattern matching</a>
</ul>
<li><a href="Typemaps.html#Typemaps_nn21">Code generation rules</a>
@ -387,14 +391,18 @@
<li><a href="Typemaps.html#Typemaps_nn43">Typemaps for multiple target languages</a>
<li><a href="Typemaps.html#Typemaps_optimal">Optimal code generation when returning by value</a>
<li><a href="Typemaps.html#Typemaps_multi_argument_typemaps">Multi-argument typemaps</a>
<li><a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>
<li><a href="Typemaps.html#Typemaps_fragments">Typemap fragments</a>
<ul>
<li><a href="Typemaps.html#Typemaps_fragment_type_specialization">Fragment type specialization</a>
<li><a href="Typemaps.html#Typemaps_automatic_specialization">Fragments and automatic typemap specialization</a>
</ul>
<li><a href="Typemaps.html#Typemaps_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_runtime_type_checker_usage">Usage</a>
</ul>
<li><a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a>
<li><a href="Typemaps.html#Typemaps_nn48">More about <tt>%apply</tt> and <tt>%clear</tt></a>
<li><a href="Typemaps.html#Typemaps_nn49">Reducing wrapper code size</a>
<li><a href="Typemaps.html#Typemaps_nn47">Passing data between typemaps</a>
<li><a href="Typemaps.html#Typemaps_nn52">C++ "this" pointer</a>
<li><a href="Typemaps.html#Typemaps_nn51">Where to go for more information?</a>
@ -407,7 +415,7 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Customization.html#exception">Exception handling with %exception</a>
<li><a href="Customization.html#Customization_exception">Exception handling with %exception</a>
<ul>
<li><a href="Customization.html#Customization_nn3">Handling exceptions in C code</a>
<li><a href="Customization.html#Customization_nn4">Exception handling with longjmp()</a>
@ -417,14 +425,14 @@
<li><a href="Customization.html#Customization_exception_special_variables">Special variables for %exception</a>
<li><a href="Customization.html#Customization_nn7">Using The SWIG exception library</a>
</ul>
<li><a href="Customization.html#ownership">Object ownership and %newobject</a>
<li><a href="Customization.html#features">Features and the %feature directive</a>
<li><a href="Customization.html#Customization_ownership">Object ownership and %newobject</a>
<li><a href="Customization.html#Customization_features">Features and the %feature directive</a>
<ul>
<li><a href="Customization.html#Customization_feature_attributes">Feature attributes</a>
<li><a href="Customization.html#Customization_feature_flags">Feature flags</a>
<li><a href="Customization.html#Customization_clearing_features">Clearing features</a>
<li><a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
<li><a href="Customization.html#features_example">Feature example</a>
<li><a href="Customization.html#Customization_features_example">Feature example</a>
</ul>
</ul>
</div>
@ -497,7 +505,7 @@
<li><a href="Modules.html#Modules_introduction">Modules Introduction</a>
<li><a href="Modules.html#Modules_nn1">Basics</a>
<li><a href="Modules.html#Modules_nn2">The SWIG runtime code</a>
<li><a href="Modules.html#external_run_time">External access to the runtime</a>
<li><a href="Modules.html#Modules_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>
@ -620,35 +628,36 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CSharp.html#csharp_introduction">Introduction</a>
<li><a href="CSharp.html#csharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_introduction">Introduction</a>
<li><a href="CSharp.html#CSharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#CSharp_arrays">C# Arrays</a>
<ul>
<li><a href="CSharp.html#CSharp_arrays_swig_library">The SWIG C arrays library</a>
<li><a href="CSharp.html#CSharp_arrays_pinvoke_default_array_marshalling">Managed arrays using P/Invoke default array marshalling</a>
<li><a href="CSharp.html#CSharp_arrays_pinning">Managed arrays using pinning</a>
</ul>
<li><a href="CSharp.html#csharp_exceptions">C# Exceptions</a>
<li><a href="CSharp.html#CSharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="CSharp.html#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="CSharp.html#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="CSharp.html#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="CSharp.html#csharp_custom_application_exception">Custom C# ApplicationException example</a>
<li><a href="CSharp.html#CSharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="CSharp.html#CSharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="CSharp.html#CSharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="CSharp.html#CSharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
<li><a href="CSharp.html#csharp_directors">C# Directors</a>
<li><a href="CSharp.html#CSharp_directors">C# Directors</a>
<ul>
<li><a href="CSharp.html#csharp_directors_example">Directors example</a>
<li><a href="CSharp.html#csharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#csharp_director_caveats">Director caveats</a>
<li><a href="CSharp.html#CSharp_directors_example">Directors example</a>
<li><a href="CSharp.html#CSharp_directors_implementation">Directors implementation</a>
<li><a href="CSharp.html#CSharp_director_caveats">Director caveats</a>
</ul>
<li><a href="CSharp.html#csharp_typemap_examples">C# Typemap examples</a>
<li><a href="CSharp.html#CSharp_typemap_examples">C# Typemap examples</a>
<ul>
<li><a href="CSharp.html#csharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="CSharp.html#csharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="CSharp.html#csharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="CSharp.html#csharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="CSharp.html#csharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="CSharp.html#csharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="CSharp.html#CSharp_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="CSharp.html#CSharp_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="CSharp.html#CSharp_date_marshalling">Date marshalling using the csin typemap and associated attributes</a>
<li><a href="CSharp.html#CSharp_date_properties">A date example demonstrating marshalling of C# properties</a>
<li><a href="CSharp.html#CSharp_partial_classes">Turning wrapped classes into partial classes</a>
<li><a href="CSharp.html#CSharp_extending_proxy_class">Extending proxy classes with additional C# code</a>
<li><a href="CSharp.html#CSharp_enum_underlying_type">Underlying type for enums</a>
</ul>
</ul>
</div>
@ -682,7 +691,7 @@
<li><a href="Chicken.html#Chicken_nn16">Typemaps</a>
<li><a href="Chicken.html#Chicken_nn17">Pointers</a>
<ul>
<li><a href="Chicken.html#collection">Garbage collection</a>
<li><a href="Chicken.html#Chicken_collection">Garbage collection</a>
</ul>
<li><a href="Chicken.html#Chicken_nn18">Unsupported features and known problems</a>
<ul>
@ -692,7 +701,36 @@
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">20 SWIG and Guile</a></h3>
<h3><a href="Go.html#Go">20 SWIG and Go</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Go.html#Go_overview">Overview</a>
<li><a href="Go.html#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="Go.html#Go_commandline">Additional Commandline Options</a>
<li><a href="Go.html#Go_outputs">Go Output Files</a>
</ul>
<li><a href="Go.html#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="Go.html#Go_package">Go Package Name</a>
<li><a href="Go.html#Go_names">Go Names</a>
<li><a href="Go.html#Go_constants">Go Constants</a>
<li><a href="Go.html#Go_enumerations">Go Enumerations</a>
<li><a href="Go.html#Go_classes">Go Classes</a>
<ul>
<li><a href="Go.html#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="Go.html#Go_templates">Go Templates</a>
<li><a href="Go.html#Go_director_classes">Go Director Classes</a>
<li><a href="Go.html#Go_primitive_type_mappings">Default Go primitive type mappings</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Guile.html#Guile">21 SWIG and Guile</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -727,149 +765,149 @@
</div>
<!-- INDEX -->
<h3><a href="Java.html#Java">21 SWIG and Java</a></h3>
<h3><a href="Java.html#Java">22 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>
<li><a href="Java.html#Java_overview">Overview</a>
<li><a href="Java.html#Java_preliminaries">Preliminaries</a>
<ul>
<li><a href="Java.html#running_swig">Running SWIG</a>
<li><a href="Java.html#java_commandline">Additional Commandline Options</a>
<li><a href="Java.html#getting_right_headers">Getting the right header files</a>
<li><a href="Java.html#compiling_dynamic">Compiling a dynamic module</a>
<li><a href="Java.html#using_module">Using your module</a>
<li><a href="Java.html#dynamic_linking_problems">Dynamic linking problems</a>
<li><a href="Java.html#compilation_problems_cpp">Compilation problems and compiling with C++</a>
<li><a href="Java.html#building_windows">Building on Windows</a>
<li><a href="Java.html#Java_running_swig">Running SWIG</a>
<li><a href="Java.html#Java_commandline">Additional Commandline Options</a>
<li><a href="Java.html#Java_getting_right_headers">Getting the right header files</a>
<li><a href="Java.html#Java_compiling_dynamic">Compiling a dynamic module</a>
<li><a href="Java.html#Java_using_module">Using your module</a>
<li><a href="Java.html#Java_dynamic_linking_problems">Dynamic linking problems</a>
<li><a href="Java.html#Java_compilation_problems_cpp">Compilation problems and compiling with C++</a>
<li><a href="Java.html#Java_building_windows">Building on Windows</a>
<ul>
<li><a href="Java.html#visual_studio">Running SWIG from Visual Studio</a>
<li><a href="Java.html#nmake">Using NMAKE</a>
<li><a href="Java.html#Java_visual_studio">Running SWIG from Visual Studio</a>
<li><a href="Java.html#Java_nmake">Using NMAKE</a>
</ul>
</ul>
<li><a href="Java.html#java_basic_tour">A tour of basic C/C++ wrapping</a>
<li><a href="Java.html#Java_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="Java.html#module_packages_classes">Modules, packages and generated Java classes</a>
<li><a href="Java.html#functions">Functions</a>
<li><a href="Java.html#global_variables">Global variables</a>
<li><a href="Java.html#constants">Constants</a>
<li><a href="Java.html#enumerations">Enumerations</a>
<li><a href="Java.html#Java_module_packages_classes">Modules, packages and generated Java classes</a>
<li><a href="Java.html#Java_functions">Functions</a>
<li><a href="Java.html#Java_global_variables">Global variables</a>
<li><a href="Java.html#Java_constants">Constants</a>
<li><a href="Java.html#Java_enumerations">Enumerations</a>
<ul>
<li><a href="Java.html#anonymous_enums">Anonymous enums</a>
<li><a href="Java.html#typesafe_enums">Typesafe enums</a>
<li><a href="Java.html#proper_enums">Proper Java enums</a>
<li><a href="Java.html#typeunsafe_enums">Type unsafe enums</a>
<li><a href="Java.html#simple_enums">Simple enums</a>
<li><a href="Java.html#Java_anonymous_enums">Anonymous enums</a>
<li><a href="Java.html#Java_typesafe_enums">Typesafe enums</a>
<li><a href="Java.html#Java_proper_enums">Proper Java enums</a>
<li><a href="Java.html#Java_typeunsafe_enums">Type unsafe enums</a>
<li><a href="Java.html#Java_simple_enums">Simple enums</a>
</ul>
<li><a href="Java.html#pointers">Pointers</a>
<li><a href="Java.html#structures">Structures</a>
<li><a href="Java.html#classes">C++ classes</a>
<li><a href="Java.html#inheritance">C++ inheritance</a>
<li><a href="Java.html#pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
<li><a href="Java.html#Java_pointers">Pointers</a>
<li><a href="Java.html#Java_structures">Structures</a>
<li><a href="Java.html#Java_classes">C++ classes</a>
<li><a href="Java.html#Java_inheritance">C++ inheritance</a>
<li><a href="Java.html#Java_pointers_refs_arrays">Pointers, references, arrays and pass by value</a>
<ul>
<li><a href="Java.html#null_pointers">Null pointers</a>
<li><a href="Java.html#Java_null_pointers">Null pointers</a>
</ul>
<li><a href="Java.html#overloaded_functions">C++ overloaded functions</a>
<li><a href="Java.html#java_default_arguments">C++ default arguments</a>
<li><a href="Java.html#namespaces">C++ namespaces</a>
<li><a href="Java.html#templates">C++ templates</a>
<li><a href="Java.html#smart_pointers">C++ Smart Pointers</a>
<li><a href="Java.html#Java_overloaded_functions">C++ overloaded functions</a>
<li><a href="Java.html#Java_default_arguments">C++ default arguments</a>
<li><a href="Java.html#Java_namespaces">C++ namespaces</a>
<li><a href="Java.html#Java_templates">C++ templates</a>
<li><a href="Java.html#Java_smart_pointers">C++ Smart Pointers</a>
</ul>
<li><a href="Java.html#further_details">Further details on the generated Java classes</a>
<li><a href="Java.html#Java_further_details">Further details on the generated Java classes</a>
<ul>
<li><a href="Java.html#imclass">The intermediary JNI class</a>
<li><a href="Java.html#Java_imclass">The intermediary JNI class</a>
<ul>
<li><a href="Java.html#imclass_pragmas">The intermediary JNI class pragmas</a>
<li><a href="Java.html#Java_imclass_pragmas">The intermediary JNI class pragmas</a>
</ul>
<li><a href="Java.html#java_module_class">The Java module class</a>
<li><a href="Java.html#Java_module_class">The Java module class</a>
<ul>
<li><a href="Java.html#module_class_pragmas">The Java module class pragmas</a>
<li><a href="Java.html#Java_module_class_pragmas">The Java module class pragmas</a>
</ul>
<li><a href="Java.html#java_proxy_classes">Java proxy classes</a>
<li><a href="Java.html#Java_proxy_classes">Java proxy classes</a>
<ul>
<li><a href="Java.html#memory_management">Memory management</a>
<li><a href="Java.html#inheritance_mirroring">Inheritance</a>
<li><a href="Java.html#proxy_classes_gc">Proxy classes and garbage collection</a>
<li><a href="Java.html#java_pgcpp">The premature garbage collection prevention parameter for proxy class marshalling</a>
<li><a href="Java.html#java_multithread_libraries">Single threaded applications and thread safety</a>
<li><a href="Java.html#Java_memory_management">Memory management</a>
<li><a href="Java.html#Java_inheritance_mirroring">Inheritance</a>
<li><a href="Java.html#Java_proxy_classes_gc">Proxy classes and garbage collection</a>
<li><a href="Java.html#Java_pgcpp">The premature garbage collection prevention parameter for proxy class marshalling</a>
<li><a href="Java.html#Java_multithread_libraries">Single threaded applications and thread safety</a>
</ul>
<li><a href="Java.html#type_wrapper_classes">Type wrapper classes</a>
<li><a href="Java.html#enum_classes">Enum classes</a>
<li><a href="Java.html#Java_type_wrapper_classes">Type wrapper classes</a>
<li><a href="Java.html#Java_enum_classes">Enum classes</a>
<ul>
<li><a href="Java.html#typesafe_enums_classes">Typesafe enum classes</a>
<li><a href="Java.html#proper_enums_classes">Proper Java enum classes</a>
<li><a href="Java.html#typeunsafe_enums_classes">Type unsafe enum classes</a>
<li><a href="Java.html#Java_typesafe_enums_classes">Typesafe enum classes</a>
<li><a href="Java.html#Java_proper_enums_classes">Proper Java enum classes</a>
<li><a href="Java.html#Java_typeunsafe_enums_classes">Type unsafe enum classes</a>
</ul>
</ul>
<li><a href="Java.html#java_directors">Cross language polymorphism using directors</a>
<li><a href="Java.html#Java_directors">Cross language polymorphism using directors</a>
<ul>
<li><a href="Java.html#java_enabling_directors">Enabling directors</a>
<li><a href="Java.html#java_directors_classes">Director classes</a>
<li><a href="Java.html#java_directors_overhead">Overhead and code bloat</a>
<li><a href="Java.html#java_directors_example">Simple directors example</a>
<li><a href="Java.html#java_directors_threading">Director threading issues</a>
<li><a href="Java.html#Java_enabling_directors">Enabling directors</a>
<li><a href="Java.html#Java_directors_classes">Director classes</a>
<li><a href="Java.html#Java_directors_overhead">Overhead and code bloat</a>
<li><a href="Java.html#Java_directors_example">Simple directors example</a>
<li><a href="Java.html#Java_directors_threading">Director threading issues</a>
</ul>
<li><a href="Java.html#java_allprotected">Accessing protected members</a>
<li><a href="Java.html#common_customization">Common customization features</a>
<li><a href="Java.html#Java_allprotected">Accessing protected members</a>
<li><a href="Java.html#Java_common_customization">Common customization features</a>
<ul>
<li><a href="Java.html#helper_functions">C/C++ helper functions</a>
<li><a href="Java.html#class_extension">Class extension with %extend</a>
<li><a href="Java.html#exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="Java.html#method_access">Method access with %javamethodmodifiers</a>
<li><a href="Java.html#Java_helper_functions">C/C++ helper functions</a>
<li><a href="Java.html#Java_class_extension">Class extension with %extend</a>
<li><a href="Java.html#Java_exception_handling">Exception handling with %exception and %javaexception</a>
<li><a href="Java.html#Java_method_access">Method access with %javamethodmodifiers</a>
</ul>
<li><a href="Java.html#tips_techniques">Tips and techniques</a>
<li><a href="Java.html#Java_tips_techniques">Tips and techniques</a>
<ul>
<li><a href="Java.html#input_output_parameters">Input and output parameters using primitive pointers and references</a>
<li><a href="Java.html#simple_pointers">Simple pointers</a>
<li><a href="Java.html#c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="Java.html#unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="Java.html#java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
<li><a href="Java.html#Java_input_output_parameters">Input and output parameters using primitive pointers and references</a>
<li><a href="Java.html#Java_simple_pointers">Simple pointers</a>
<li><a href="Java.html#Java_c_arrays">Wrapping C arrays with Java arrays</a>
<li><a href="Java.html#Java_unbounded_c_arrays">Unbounded C Arrays</a>
<li><a href="Java.html#Java_heap_allocations">Overriding new and delete to allocate from Java heap</a>
</ul>
<li><a href="Java.html#java_typemaps">Java typemaps</a>
<li><a href="Java.html#Java_typemaps">Java typemaps</a>
<ul>
<li><a href="Java.html#default_primitive_type_mappings">Default primitive type mappings</a>
<li><a href="Java.html#Java_default_primitive_type_mappings">Default primitive type mappings</a>
<li><a href="Java.html#Java_default_non_primitive_typemaps">Default typemaps for non-primitive types</a>
<li><a href="Java.html#jvm64">Sixty four bit JVMs</a>
<li><a href="Java.html#what_is_typemap">What is a typemap?</a>
<li><a href="Java.html#typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
<li><a href="Java.html#typemap_attributes">Java typemap attributes</a>
<li><a href="Java.html#special_variables">Java special variables</a>
<li><a href="Java.html#typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="Java.html#java_code_typemaps">Java code typemaps</a>
<li><a href="Java.html#java_directors_typemaps">Director specific typemaps</a>
<li><a href="Java.html#Java_jvm64">Sixty four bit JVMs</a>
<li><a href="Java.html#Java_what_is_typemap">What is a typemap?</a>
<li><a href="Java.html#Java_typemaps_c_to_java_types">Typemaps for mapping C/C++ types to Java types</a>
<li><a href="Java.html#Java_typemap_attributes">Java typemap attributes</a>
<li><a href="Java.html#Java_special_variables">Java special variables</a>
<li><a href="Java.html#Java_typemaps_for_c_and_cpp">Typemaps for both C and C++ compilation</a>
<li><a href="Java.html#Java_code_typemaps">Java code typemaps</a>
<li><a href="Java.html#Java_directors_typemaps">Director specific typemaps</a>
</ul>
<li><a href="Java.html#typemap_examples">Typemap Examples</a>
<li><a href="Java.html#Java_typemap_examples">Typemap Examples</a>
<ul>
<li><a href="Java.html#simpler_enum_classes">Simpler Java enums for enums without initializers</a>
<li><a href="Java.html#exception_typemap">Handling C++ exception specifications as Java exceptions</a>
<li><a href="Java.html#nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
<li><a href="Java.html#converting_java_string_arrays">Converting Java String arrays to char ** </a>
<li><a href="Java.html#expanding_java_object">Expanding a Java object to multiple arguments</a>
<li><a href="Java.html#using_typemaps_return_arguments">Using typemaps to return arguments</a>
<li><a href="Java.html#adding_downcasts">Adding Java downcasts to polymorphic return types</a>
<li><a href="Java.html#adding_equals_method">Adding an equals method to the Java classes</a>
<li><a href="Java.html#void_pointers">Void pointers and a common Java base class</a>
<li><a href="Java.html#struct_pointer_pointer">Struct pointer to pointer</a>
<li><a href="Java.html#java_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="Java.html#java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="Java.html#java_date_marshalling">Date marshalling using the javain typemap and associated attributes</a>
<li><a href="Java.html#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a>
<li><a href="Java.html#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a>
<li><a href="Java.html#Java_nan_exception_typemap">NaN Exception - exception handling for a particular type</a>
<li><a href="Java.html#Java_converting_java_string_arrays">Converting Java String arrays to char ** </a>
<li><a href="Java.html#Java_expanding_java_object">Expanding a Java object to multiple arguments</a>
<li><a href="Java.html#Java_using_typemaps_return_arguments">Using typemaps to return arguments</a>
<li><a href="Java.html#Java_adding_downcasts">Adding Java downcasts to polymorphic return types</a>
<li><a href="Java.html#Java_adding_equals_method">Adding an equals method to the Java classes</a>
<li><a href="Java.html#Java_void_pointers">Void pointers and a common Java base class</a>
<li><a href="Java.html#Java_struct_pointer_pointer">Struct pointer to pointer</a>
<li><a href="Java.html#Java_memory_management_member_variables">Memory management when returning references to member variables</a>
<li><a href="Java.html#Java_memory_management_objects">Memory management for objects passed to the C++ layer</a>
<li><a href="Java.html#Java_date_marshalling">Date marshalling using the javain typemap and associated attributes</a>
</ul>
<li><a href="Java.html#java_directors_faq">Living with Java Directors</a>
<li><a href="Java.html#odds_ends">Odds and ends</a>
<li><a href="Java.html#Java_directors_faq">Living with Java Directors</a>
<li><a href="Java.html#Java_odds_ends">Odds and ends</a>
<ul>
<li><a href="Java.html#javadoc_comments">JavaDoc comments</a>
<li><a href="Java.html#functional_interface">Functional interface without proxy classes</a>
<li><a href="Java.html#using_own_jni_functions">Using your own JNI functions</a>
<li><a href="Java.html#performance">Performance concerns and hints</a>
<li><a href="Java.html#java_debugging">Debugging</a>
<li><a href="Java.html#Java_javadoc_comments">JavaDoc comments</a>
<li><a href="Java.html#Java_functional_interface">Functional interface without proxy classes</a>
<li><a href="Java.html#Java_using_own_jni_functions">Using your own JNI functions</a>
<li><a href="Java.html#Java_performance">Performance concerns and hints</a>
<li><a href="Java.html#Java_debugging">Debugging</a>
</ul>
<li><a href="Java.html#java_examples">Examples</a>
<li><a href="Java.html#Java_examples">Examples</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Lisp.html#Lisp">22 SWIG and Common Lisp</a></h3>
<h3><a href="Lisp.html#Lisp">23 SWIG and Common Lisp</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -892,7 +930,7 @@
</div>
<!-- INDEX -->
<h3><a href="Lua.html#Lua">23 SWIG and Lua</a></h3>
<h3><a href="Lua.html#Lua">24 SWIG and Lua</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -949,48 +987,45 @@
</div>
<!-- INDEX -->
<h3><a href="Modula3.html#Modula3">24 SWIG and Modula-3</a></h3>
<h3><a href="Modula3.html#Modula3">25 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Modula3.html#modula3_overview">Overview</a>
<li><a href="Modula3.html#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="Modula3.html#whyscripting">Why not scripting ?</a>
<li><a href="Modula3.html#whymodula3">Why Modula-3 ?</a>
<li><a href="Modula3.html#whycpp">Why C / C++ ?</a>
<li><a href="Modula3.html#whyswig">Why SWIG ?</a>
<li><a href="Modula3.html#Modula3_motivation">Motivation</a>
</ul>
<li><a href="Modula3.html#conception">Conception</a>
<li><a href="Modula3.html#Modula3_conception">Conception</a>
<ul>
<li><a href="Modula3.html#cinterface">Interfaces to C libraries</a>
<li><a href="Modula3.html#cppinterface">Interfaces to C++ libraries</a>
<li><a href="Modula3.html#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="Modula3.html#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="Modula3.html#preliminaries">Preliminaries</a>
<li><a href="Modula3.html#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="Modula3.html#compilers">Compilers</a>
<li><a href="Modula3.html#commandline">Additional Commandline Options</a>
<li><a href="Modula3.html#Modula3_compilers">Compilers</a>
<li><a href="Modula3.html#Modula3_commandline">Additional Commandline Options</a>
</ul>
<li><a href="Modula3.html#modula3_typemaps">Modula-3 typemaps</a>
<li><a href="Modula3.html#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="Modula3.html#inoutparam">Inputs and outputs</a>
<li><a href="Modula3.html#ordinals">Subranges, Enumerations, Sets</a>
<li><a href="Modula3.html#class">Objects</a>
<li><a href="Modula3.html#imports">Imports</a>
<li><a href="Modula3.html#exceptions">Exceptions</a>
<li><a href="Modula3.html#typemap_example">Example</a>
<li><a href="Modula3.html#Modula3_inoutparam">Inputs and outputs</a>
<li><a href="Modula3.html#Modula3_ordinals">Subranges, Enumerations, Sets</a>
<li><a href="Modula3.html#Modula3_class">Objects</a>
<li><a href="Modula3.html#Modula3_imports">Imports</a>
<li><a href="Modula3.html#Modula3_exceptions">Exceptions</a>
<li><a href="Modula3.html#Modula3_typemap_example">Example</a>
</ul>
<li><a href="Modula3.html#hints">More hints to the generator</a>
<li><a href="Modula3.html#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="Modula3.html#features">Features</a>
<li><a href="Modula3.html#pragmas">Pragmas</a>
<li><a href="Modula3.html#Modula3_features">Features</a>
<li><a href="Modula3.html#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="Modula3.html#remarks">Remarks</a>
<li><a href="Modula3.html#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Mzscheme.html#Mzscheme">25 SWIG and MzScheme</a></h3>
<h3><a href="Mzscheme.html#Mzscheme">26 SWIG and MzScheme</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1000,7 +1035,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">26 SWIG and Ocaml</a></h3>
<h3><a href="Ocaml.html#Ocaml">27 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1051,7 +1086,7 @@
</div>
<!-- INDEX -->
<h3><a href="Octave.html#Octave">27 SWIG and Octave</a></h3>
<h3><a href="Octave.html#Octave">28 SWIG and Octave</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1086,7 +1121,7 @@
</div>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">28 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html#Perl5">29 SWIG and Perl5</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1153,7 +1188,7 @@
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">29 SWIG and PHP</a></h3>
<h3><a href="Php.html#Php">30 SWIG and PHP</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1193,7 +1228,7 @@
</div>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">30 SWIG and Pike</a></h3>
<h3><a href="Pike.html#Pike">31 SWIG and Pike</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1217,7 +1252,7 @@
</div>
<!-- INDEX -->
<h3><a href="Python.html#Python">31 SWIG and Python</a></h3>
<h3><a href="Python.html#Python">32 SWIG and Python</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1320,7 +1355,7 @@
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">32 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html#Ruby">33 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1353,7 +1388,7 @@
<li><a href="Ruby.html#Ruby_nn22">C++ namespaces</a>
<li><a href="Ruby.html#Ruby_nn23">C++ templates</a>
<li><a href="Ruby.html#Ruby_nn23_1">C++ Standard Template Library (STL)</a>
<li><a href="Ruby.html#C_STL_Functors">C++ STL Functors</a>
<li><a href="Ruby.html#Ruby_C_STL_Functors">C++ STL Functors</a>
<li><a href="Ruby.html#Ruby_C_Iterators">C++ STL Iterators</a>
<li><a href="Ruby.html#Ruby_nn24">C++ Smart Pointers</a>
<li><a href="Ruby.html#Ruby_nn25">Cross-Language Polymorphism</a>
@ -1437,7 +1472,7 @@
</ul>
<li><a href="Ruby.html#Ruby_nn53">Advanced Topics</a>
<ul>
<li><a href="Ruby.html#Ruby_nn54">Operator overloading</a>
<li><a href="Ruby.html#Ruby_operator_overloading">Operator overloading</a>
<li><a href="Ruby.html#Ruby_nn55">Creating Multi-Module Packages</a>
<li><a href="Ruby.html#Ruby_nn56">Specifying Mixin Modules</a>
</ul>
@ -1454,7 +1489,7 @@
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">33 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html#Tcl">34 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1520,7 +1555,7 @@
</div>
<!-- INDEX -->
<h3><a href="R.html#R">34 SWIG and R</a></h3>
<h3><a href="R.html#R">35 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1536,7 +1571,7 @@
</div>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">35 Extending SWIG to support new languages</a></h3>
<h3><a href="Extending.html#Extending">36 Extending SWIG to support new languages</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1585,7 +1620,7 @@
<li><a href="Extending.html#Extending_nn36">Entry point to code generation</a>
<li><a href="Extending.html#Extending_nn37">Module I/O and wrapper skeleton</a>
<li><a href="Extending.html#Extending_nn38">Low-level code generators</a>
<li><a href="Extending.html#Extending_nn39">Configuration files</a>
<li><a href="Extending.html#Extending_configuration_files">Configuration files</a>
<li><a href="Extending.html#Extending_nn40">Runtime support</a>
<li><a href="Extending.html#Extending_nn41">Standard library files</a>
<li><a href="Extending.html#Extending_nn42">User examples</a>

26
Doc/Manual/Customization.html
View file

@ -10,7 +10,7 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#exception">Exception handling with %exception</a>
<li><a href="#Customization_exception">Exception handling with %exception</a>
<ul>
<li><a href="#Customization_nn3">Handling exceptions in C code</a>
<li><a href="#Customization_nn4">Exception handling with longjmp()</a>
@ -20,14 +20,14 @@
<li><a href="#Customization_exception_special_variables">Special variables for %exception</a>
<li><a href="#Customization_nn7">Using The SWIG exception library</a>
</ul>
<li><a href="#ownership">Object ownership and %newobject</a>
<li><a href="#features">Features and the %feature directive</a>
<li><a href="#Customization_ownership">Object ownership and %newobject</a>
<li><a href="#Customization_features">Features and the %feature directive</a>
<ul>
<li><a href="#Customization_feature_attributes">Feature attributes</a>
<li><a href="#Customization_feature_flags">Feature flags</a>
<li><a href="#Customization_clearing_features">Clearing features</a>
<li><a href="#Customization_features_default_args">Features and default arguments</a>
<li><a href="#features_example">Feature example</a>
<li><a href="#Customization_features_example">Feature example</a>
</ul>
</ul>
</div>
@ -45,7 +45,7 @@ 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>
<H2><a name="Customization_exception"></a>11.1 Exception handling with %exception</H2>
<p>
@ -83,7 +83,7 @@ How the exception is handled depends on the target language, for example, Python
<p>
When defined, the code enclosed in braces is inserted directly into the low-level wrapper
functions. The special variable <tt>$action</tt> is one of a few
<a href="Customization.html#Customization_exception_special_variables">%exception special variable</a>
<a href="Customization.html#Customization_exception_special_variables">%exception special variables</a>
supported and gets replaced with the actual operation
to be performed (a function call, method invocation, attribute access, etc.). An exception handler
remains in effect until it is explicitly deleted. This is done by using either <tt>%exception</tt>
@ -351,7 +351,7 @@ 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
rules as for <tt>%rename</tt> described in the section on
<a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>.
<a href="SWIGPlus.html#SWIGPlus_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>
@ -582,7 +582,7 @@ it can be used elsewhere in SWIG. This includes typemaps and helper
functions.
</p>
<H2><a name="ownership"></a>11.2 Object ownership and %newobject</H2>
<H2><a name="Customization_ownership"></a>11.2 Object ownership and %newobject</H2>
<p>
@ -734,7 +734,7 @@ char *strdup(const char *s);
The results might not be what you expect.
</p>
<H2><a name="features"></a>11.3 Features and the %feature directive</H2>
<H2><a name="Customization_features"></a>11.3 Features and the %feature directive</H2>
<p>
@ -773,9 +773,9 @@ involving <tt>%feature</tt>:
</div>
<p>
The name matching rules outlined in the <a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
The name matching rules outlined in the <a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
section applies to all <tt>%feature</tt> directives.
In fact the the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
In fact the <tt>%rename</tt> directive is just a special form of <tt>%feature</tt>.
The matching rules mean that features are very flexible and can be applied with
pinpoint accuracy to specific declarations if needed.
Additionally, if no declaration name is given, a global feature is said to be defined.
@ -854,7 +854,7 @@ In the following example, <tt>MyExceptionClass</tt> is the name of the Java clas
</div>
<p>
Further details can be obtained from the <a href="Java.html#exception_handling">Java exception handling</a> section.
Further details can be obtained from the <a href="Java.html#Java_exception_handling">Java exception handling</a> section.
</p>
<H3><a name="Customization_feature_flags"></a>11.3.2 Feature flags</H3>
@ -1123,7 +1123,7 @@ specifying or not specifying default arguments in a feature is not applicable as
in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
</p>
<H3><a name="features_example"></a>11.3.5 Feature example</H3>
<H3><a name="Customization_features_example"></a>11.3.5 Feature example</H3>
<p>

122
Doc/Manual/Extending.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending"></a>35 Extending SWIG to support new languages</H1>
<H1><a name="Extending"></a>36 Extending SWIG to support new languages</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -54,7 +54,7 @@
<li><a href="#Extending_nn36">Entry point to code generation</a>
<li><a href="#Extending_nn37">Module I/O and wrapper skeleton</a>
<li><a href="#Extending_nn38">Low-level code generators</a>
<li><a href="#Extending_nn39">Configuration files</a>
<li><a href="#Extending_configuration_files">Configuration files</a>
<li><a href="#Extending_nn40">Runtime support</a>
<li><a href="#Extending_nn41">Standard library files</a>
<li><a href="#Extending_nn42">User examples</a>
@ -75,7 +75,7 @@
<H2><a name="Extending_nn2"></a>35.1 Introduction</H2>
<H2><a name="Extending_nn2"></a>36.1 Introduction</H2>
<p>
@ -91,7 +91,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3"></a>35.2 Prerequisites</H2>
<H2><a name="Extending_nn3"></a>36.2 Prerequisites</H2>
<p>
@ -121,7 +121,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4"></a>35.3 The Big Picture</H2>
<H2><a name="Extending_nn4"></a>36.3 The Big Picture</H2>
<p>
@ -158,7 +158,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5"></a>35.4 Execution Model</H2>
<H2><a name="Extending_nn5"></a>36.4 Execution Model</H2>
<p>
@ -203,7 +203,7 @@ latter stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6"></a>35.4.1 Preprocessing</H3>
<H3><a name="Extending_nn6"></a>36.4.1 Preprocessing</H3>
<p>
@ -284,7 +284,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7"></a>35.4.2 Parsing</H3>
<H3><a name="Extending_nn7"></a>36.4.2 Parsing</H3>
<p>
@ -385,7 +385,7 @@ returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
</p>
<H3><a name="Extending_nn8"></a>35.4.3 Parse Trees</H3>
<H3><a name="Extending_nn8"></a>36.4.3 Parse Trees</H3>
<p>
@ -640,7 +640,7 @@ $ swig -c++ -python -debug-module 4 example.i
</pre>
</div>
<H3><a name="Extending_nn9"></a>35.4.4 Attribute namespaces</H3>
<H3><a name="Extending_nn9"></a>36.4.4 Attribute namespaces</H3>
<p>
@ -659,7 +659,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10"></a>35.4.5 Symbol Tables</H3>
<H3><a name="Extending_nn10"></a>36.4.5 Symbol Tables</H3>
<p>
@ -750,7 +750,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</div>
<H3><a name="Extending_nn11"></a>35.4.6 The %feature directive</H3>
<H3><a name="Extending_nn11"></a>36.4.6 The %feature directive</H3>
<p>
@ -806,7 +806,7 @@ For example, the exception code above is simply
stored without any modifications.
</p>
<H3><a name="Extending_nn12"></a>35.4.7 Code Generation</H3>
<H3><a name="Extending_nn12"></a>36.4.7 Code Generation</H3>
<p>
@ -928,7 +928,7 @@ public :
The role of these functions is described shortly.
</p>
<H3><a name="Extending_nn13"></a>35.4.8 SWIG and XML</H3>
<H3><a name="Extending_nn13"></a>36.4.8 SWIG and XML</H3>
<p>
@ -941,7 +941,7 @@ internal data structures, it may be useful to keep XML in the back of
your mind as a model.
</p>
<H2><a name="Extending_nn14"></a>35.5 Primitive Data Structures</H2>
<H2><a name="Extending_nn14"></a>36.5 Primitive Data Structures</H2>
<p>
@ -987,7 +987,7 @@ typedef Hash Typetab;
</pre>
</div>
<H3><a name="Extending_nn15"></a>35.5.1 Strings</H3>
<H3><a name="Extending_nn15"></a>36.5.1 Strings</H3>
<p>
@ -1128,7 +1128,7 @@ Returns the number of replacements made (if any).
</div>
<H3><a name="Extending_nn16"></a>35.5.2 Hashes</H3>
<H3><a name="Extending_nn16"></a>36.5.2 Hashes</H3>
<p>
@ -1205,7 +1205,7 @@ Returns the list of hash table keys.
</div>
<H3><a name="Extending_nn17"></a>35.5.3 Lists</H3>
<H3><a name="Extending_nn17"></a>36.5.3 Lists</H3>
<p>
@ -1294,7 +1294,7 @@ If <tt>t</tt> is not a standard object, it is assumed to be a <tt>char *</tt>
and is used to create a String object.
</div>
<H3><a name="Extending_nn18"></a>35.5.4 Common operations</H3>
<H3><a name="Extending_nn18"></a>36.5.4 Common operations</H3>
The following operations are applicable to all datatypes.
@ -1349,7 +1349,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</div>
<H3><a name="Extending_nn19"></a>35.5.5 Iterating over Lists and Hashes</H3>
<H3><a name="Extending_nn19"></a>36.5.5 Iterating over Lists and Hashes</H3>
To iterate over the elements of a list or a hash table, the following functions are used:
@ -1394,7 +1394,7 @@ for (j = First(j); j.item; j= Next(j)) {
</div>
<H3><a name="Extending_nn20"></a>35.5.6 I/O</H3>
<H3><a name="Extending_nn20"></a>36.5.6 I/O</H3>
Special I/O functions are used for all internal I/O. These operations
@ -1531,7 +1531,7 @@ Similarly, the preprocessor and parser all operate on string-files.
</div>
<H2><a name="Extending_nn21"></a>35.6 Navigating and manipulating parse trees</H2>
<H2><a name="Extending_nn21"></a>36.6 Navigating and manipulating parse trees</H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1665,7 +1665,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</div>
<H2><a name="Extending_nn22"></a>35.7 Working with attributes</H2>
<H2><a name="Extending_nn22"></a>36.7 Working with attributes</H2>
<p>
@ -1782,7 +1782,7 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</div>
<H2><a name="Extending_nn23"></a>35.8 Type system</H2>
<H2><a name="Extending_nn23"></a>36.8 Type system</H2>
<p>
@ -1791,7 +1791,7 @@ pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
</p>
<H3><a name="Extending_nn24"></a>35.8.1 String encoding of types</H3>
<H3><a name="Extending_nn24"></a>36.8.1 String encoding of types</H3>
<p>
@ -1892,7 +1892,7 @@ make the final type, the two parts are just joined together using
string concatenation.
</p>
<H3><a name="Extending_nn25"></a>35.8.2 Type construction</H3>
<H3><a name="Extending_nn25"></a>36.8.2 Type construction</H3>
<p>
@ -2061,7 +2061,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</div>
<H3><a name="Extending_nn26"></a>35.8.3 Type tests</H3>
<H3><a name="Extending_nn26"></a>36.8.3 Type tests</H3>
<p>
@ -2148,7 +2148,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</div>
<H3><a name="Extending_nn27"></a>35.8.4 Typedef and inheritance</H3>
<H3><a name="Extending_nn27"></a>36.8.4 Typedef and inheritance</H3>
<p>
@ -2250,7 +2250,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</div>
<H3><a name="Extending_nn28"></a>35.8.5 Lvalues</H3>
<H3><a name="Extending_nn28"></a>36.8.5 Lvalues</H3>
<p>
@ -2287,7 +2287,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</div>
<H3><a name="Extending_nn29"></a>35.8.6 Output functions</H3>
<H3><a name="Extending_nn29"></a>36.8.6 Output functions</H3>
<p>
@ -2349,7 +2349,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</div>
<H2><a name="Extending_nn30"></a>35.9 Parameters</H2>
<H2><a name="Extending_nn30"></a>36.9 Parameters</H2>
<p>
@ -2448,7 +2448,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</div>
<H2><a name="Extending_nn31"></a>35.10 Writing a Language Module</H2>
<H2><a name="Extending_nn31"></a>36.10 Writing a Language Module</H2>
<p>
@ -2463,7 +2463,7 @@ describes the creation of a minimal Python module. You should be able to extra
this to other languages.
</p>
<H3><a name="Extending_nn32"></a>35.10.1 Execution model</H3>
<H3><a name="Extending_nn32"></a>36.10.1 Execution model</H3>
<p>
@ -2473,7 +2473,7 @@ the parsing of command line options, all aspects of code generation are controll
different methods of the <tt>Language</tt> that must be defined by your module.
</p>
<H3><a name="Extending_starting_out"></a>35.10.2 Starting out</H3>
<H3><a name="Extending_starting_out"></a>36.10.2 Starting out</H3>
<p>
@ -2581,7 +2581,7 @@ that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
</p>
<H3><a name="Extending_nn34"></a>35.10.3 Command line options</H3>
<H3><a name="Extending_nn34"></a>36.10.3 Command line options</H3>
<p>
@ -2640,7 +2640,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35"></a>35.10.4 Configuration and preprocessing</H3>
<H3><a name="Extending_nn35"></a>36.10.4 Configuration and preprocessing</H3>
<p>
@ -2689,7 +2689,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36"></a>35.10.5 Entry point to code generation</H3>
<H3><a name="Extending_nn36"></a>36.10.5 Entry point to code generation</H3>
<p>
@ -2747,7 +2747,7 @@ int Python::top(Node *n) {
</pre>
</div>
<H3><a name="Extending_nn37"></a>35.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn37"></a>36.10.6 Module I/O and wrapper skeleton</H3>
<!-- please report bugs in this section to mgossage -->
@ -2895,7 +2895,7 @@ functionWrapper : void Shape_y_set(Shape *self,double y)
</pre>
</div>
<H3><a name="Extending_nn38"></a>35.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn38"></a>36.10.7 Low-level code generators</H3>
<!-- please report bugs in this section to mgossage -->
@ -3049,7 +3049,7 @@ but without the typemaps, there is still work to do.
</p>
<H3><a name="Extending_nn39"></a>35.10.8 Configuration files</H3>
<H3><a name="Extending_configuration_files"></a>36.10.8 Configuration files</H3>
<!-- please report bugs in this section to ttn -->
@ -3090,8 +3090,6 @@ The nickname is used in four places:
<TR><TD><B>usage</B></TD><TD><B>transform</B></TD></TR>
<TR><TD>"skip" tag</TD><TD>(none)</TD></TR>
<TR><TD>Examples/ subdir name</TD><TD>(none)</TD></TR>
<TR><TD>Examples/GIFPlot/ subdir name</TD>
<TD>capitalize (upcase first letter)</TD></TR>
<TR><TD>Examples/test-suite/ subdir name</TD><TD>(none)</TD></TR>
<!-- add more uses here (remember to adjust header) -->
</TABLE>
@ -3159,8 +3157,8 @@ skip-qux = $(skip-qux99)
<p>
Lastly, you need to modify each of <TT>check-aliveness</TT>,
<TT>check-examples</TT>, <TT>check-test-suite</TT>,
<TT>check-gifplot</TT> (all targets) and <TT>lib-languages</TT> (var).
<TT>check-examples</TT>, <TT>check-test-suite</TT>
and <TT>lib-languages</TT> (var).
Use the nickname for these, not the alias.
Note that you can do this even before you have any tests or examples
set up; the Makefile rules do some sanity checking and skip around
@ -3175,10 +3173,6 @@ and look to the existing languages for examples.
<dd> Do <TT>cp ../python/check.list .</TT> and modify to taste.
One subdir per line.
<dt> <b>Examples/GIFPlot/Qux99/check.list</b>
<dd> Do <TT>cp ../Python/check.list .</TT> and modify to taste.
One subdir per line.
<dt> <b>Lib/qux99/extra-install.list</b>
<dd> If you add your language to the top-level Makefile.in var
<TT>lib-languages</TT>, then <TT>make install</TT> will install
@ -3199,7 +3193,7 @@ politely displays the ignoring language message.
</dl>
<H3><a name="Extending_nn40"></a>35.10.9 Runtime support</H3>
<H3><a name="Extending_nn40"></a>36.10.9 Runtime support</H3>
<p>
@ -3208,7 +3202,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41"></a>35.10.10 Standard library files</H3>
<H3><a name="Extending_nn41"></a>36.10.10 Standard library files</H3>
<p>
@ -3227,7 +3221,7 @@ The following are the minimum that are usually supported:
Please copy these and modify for any new language.
</p>
<H3><a name="Extending_nn42"></a>35.10.11 User examples</H3>
<H3><a name="Extending_nn42"></a>36.10.11 User examples</H3>
<p>
@ -3252,11 +3246,11 @@ These can be found, for example for Python, in
<p>
By default, all of the examples are built and run when the user types
<tt>make check</tt>. To ensure that your examples are automatically run
during this process, see the section on <a href="#n37a">configuration
during this process, see the section on <a href="#Extending_configuration_files">configuration
files</a>.
</p>
<H3><a name="Extending_test_suite"></a>35.10.12 Test driven development and the test-suite</H3>
<H3><a name="Extending_test_suite"></a>36.10.12 Test driven development and the test-suite</H3>
<p>
@ -3315,7 +3309,7 @@ It is therefore essential that the runtime tests are written in a manner that di
but error/exception out with an error message on stderr on failure.
</p>
<H4><a name="Extending_running_test_suite"></a>35.10.12.1 Running the test-suite</H4>
<H4><a name="Extending_running_test_suite"></a>36.10.12.1 Running the test-suite</H4>
<p>
@ -3475,7 +3469,15 @@ SWIG can be analyzed for bad memory accesses using:
make ret_by_value.ctest SWIGTOOL="valgrind --tool=memcheck --trace-children=yes"
</pre></div>
<H3><a name="Extending_nn43"></a>35.10.13 Documentation</H3>
<p>
A debugger can also be invoked easily on an individual test, for example gdb:
</p>
<div class="shell"><pre>
make ret_by_value.ctest RUNTOOL="gdb --args"
</pre></div>
<H3><a name="Extending_nn43"></a>36.10.13 Documentation</H3>
<p>
@ -3507,7 +3509,7 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H3><a name="Extending_prerequisites"></a>35.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<H3><a name="Extending_prerequisites"></a>36.10.14 Prerequisites for adding a new language module to the SWIG distribution</H3>
<p>
@ -3564,7 +3566,7 @@ should be added should there be an area not already covered by
the existing tests.
</p>
<H3><a name="Extending_coding_style_guidelines"></a>35.10.15 Coding style guidelines</H3>
<H3><a name="Extending_coding_style_guidelines"></a>36.10.15 Coding style guidelines</H3>
<p>
@ -3588,7 +3590,7 @@ The generated C/C++ code should also follow this style as close as possible. How
should be avoided as unlike the SWIG developers, users will never have consistent tab settings.
</p>
<H2><a name="Extending_debugging_options"></a>35.11 Debugging Options</H2>
<H2><a name="Extending_debugging_options"></a>36.11 Debugging Options</H2>
<p>
@ -3613,7 +3615,7 @@ There are various command line options which can aid debugging a SWIG interface
The complete list of command line options for SWIG are available by running <tt>swig -help</tt>.
</p>
<H2><a name="Extending_nn46"></a>35.12 Guide to parse tree nodes</H2>
<H2><a name="Extending_nn46"></a>36.12 Guide to parse tree nodes</H2>
<p>
@ -4021,7 +4023,7 @@ extern "X" { ... } declaration.
</pre>
</div>
<H2><a name="Extending_further_info"></a>35.13 Further Development Information</H2>
<H2><a name="Extending_further_info"></a>36.13 Further Development Information</H2>
<p>

454
Doc/Manual/Go.html Normal file
View file

@ -0,0 +1,454 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Go</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Go"></a>20 SWIG and Go</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Go_overview">Overview</a>
<li><a href="#Go_running_swig">Running SWIG with Go</a>
<ul>
<li><a href="#Go_commandline">Additional Commandline Options</a>
<li><a href="#Go_outputs">Go Output Files</a>
</ul>
<li><a href="#Go_basic_tour">A tour of basic C/C++ wrapping</a>
<ul>
<li><a href="#Go_package">Go Package Name</a>
<li><a href="#Go_names">Go Names</a>
<li><a href="#Go_constants">Go Constants</a>
<li><a href="#Go_enumerations">Go Enumerations</a>
<li><a href="#Go_classes">Go Classes</a>
<ul>
<li><a href="#Go_class_inheritance">Go Class Inheritance</a>
</ul>
<li><a href="#Go_templates">Go Templates</a>
<li><a href="#Go_director_classes">Go Director Classes</a>
<li><a href="#Go_primitive_type_mappings">Default Go primitive type mappings</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<p>
This chapter describes SWIG's support of Go. For more information on
the Go programming language
see <a href="http://golang.org/">golang.org</a>.
</p>
<H2><a name="Go_overview"></a>20.1 Overview</H2>
<p>
Go is a compiled language, not a scripting language. However, it does
not support direct calling of functions written in C/C++. The cgo
program may be used to generate wrappers to call C code from Go, but
there is no convenient way to call C++ code. SWIG fills this gap.
</p>
<p>
There are (at least) two different Go compilers. One is the gc
compiler, normally invoked under the names 6g, 8g, or 5g. The other
is the gccgo compiler, which is a frontend to the gcc compiler suite.
The interface to C/C++ code is completely different for the two Go
compilers. SWIG supports both, selected by a command line option.
</p>
<p>
Because Go is a type-safe compiled language, SWIG's runtime type
checking and runtime library are not used with Go. This should be
borne in mind when reading the rest of the SWIG documentation.
</p>
<H2><a name="Go_running_swig"></a>20.2 Running SWIG with Go</H2>
<p>
To generate Go code, use the <tt>-go</tt> option with SWIG. By
default SWIG will generate code for the gc compilers. To generate
code for gccgo, you should also use the <tt>-gccgo</tt> option.
</p>
<H3><a name="Go_commandline"></a>20.2.1 Additional Commandline Options</H3>
<p>
These are the command line options for SWIG's GO module. They can
also be seen by using:
</p>
<div class="code"><pre>
swig -go -help
</pre></div>
<table summary="Go specific options">
<tr>
<th>Go specific options</th>
</tr>
<tr>
<td>-gccgo</td>
<td>Generate code for gccgo. The default is to generate code for
6g/8g/6g.</td>
</tr>
<tr>
<td>-package &lt;name&gt;</td>
<td>Set the name of the Go package to &lt;name&gt;. The default
package name is the SWIG module name.</td>
</tr>
<tr>
<td>-go-prefix &lt;prefix&gt;</td>
<td>When generating code for gccgo, set the prefix to use. This
corresponds to the <tt>-fgo-prefix</tt> option to gccgo.</td>
</tr>
<tr>
<td>-long-type-size &lt;s&gt;</td>
<td>Set the size for the C/C++ type <tt>long</tt>. This controls
whether <tt>long</tt> is converted to the Go type <tt>int32</tt>
or <tt>int64</tt>. The &lt;s&gt; argument should be 32 or 64.</td>
</tr>
</table>
<H3><a name="Go_outputs"></a>20.2.2 Go Output Files</H3>
<p> When generating Go code, SWIG will generate the following
files:</p>
<ul>
<li>
MODULE.go will contain the Go functions that your Go code will call.
These functions will be wrappers for the C++ functions defined by your
module. This file should, of course, be compiled with the Go
compiler.
<li>
MODULE_wrap.c or MODULE_wrap.cxx will contain C/C++ functions will be
invoked by the Go wrapper code. This file should be compiled with the
usual C or C++ compiler and linked into a shared library.
<li>
MODULE_wrap.h will be generated if you use the directors feature. It
provides a definition of the generated C++ director classes. It is
generally not necessary to use this file, but in some special cases it
may be helpful to include it in your code, compiled with the usual C
or C++ compiler.
<li>
If using the gc compiler, MODULE_gc.c will contain C code which should
be compiled with the C compiler distributed as part of the gc compiler: 6c, 8c,
or 5c. It should then be combined with the compiled MODULE.go using
gopack. This file will not be generated when using gccgo.
</ul>
<p>
A typical command sequence would look like this:
</p>
<div class="code"><pre>
% swig -go example.i
% gcc -c -fpic example.c
% gcc -c -fpic example_wrap.c
% gcc -shared example.o example_wrap.o -o example.so
% 6g example.go
% 6c example_gc.c
% gopack grc example.a example.6 example_gc.6
% 6g main.go # your code, not generated by SWIG
% 6l main.6
</pre></div>
<H2><a name="Go_basic_tour"></a>20.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG attempts to build a natural Go interface to your
C/C++ code. However, the languages are somewhat different, so some
modifications have to occur. This section briefly covers the
essential aspects of this wrapping.
</p>
<H3><a name="Go_package"></a>20.3.1 Go Package Name</H3>
<p>
All Go source code lives in a package. The name of this package will
default to the name of the module from SWIG's <tt>%module</tt>
directive. You may override this by using SWIG's <tt>-package</tt>
command line option.
</p>
<H3><a name="Go_names"></a>20.3.2 Go Names</H3>
<p>
In Go, a function is only visible outside the current package if the
first letter of the name is uppercase. This is quite different from
C/C++. Because of this, C/C++ names are modified when generating the
Go interface: the first letter is forced to be uppercase if it is not
already. This affects the names of functions, methods, variables,
constants, enums, and classes.
</p>
<p>
C/C++ variables are wrapped with setter and getter functions in Go.
First the first letter of the variable name will be forced to
uppercase, and then <tt>Get</tt> or <tt>Set</tt> will be prepended.
For example, if the C/C++ variable is called <tt>var</tt>, then SWIG
will define the functions <tt>GetVar</tt> and <tt>SetVar</tt>. If a
variable is declared as <tt>const</tt>, or if
SWIG's <a href="SWIG.html#SWIG_readonly_variables">
<tt>%immutable</tt> directive</a> is used for the variable, then only
the getter will be defined.
</p>
<p>
C++ classes will be discussed further below. Here we'll note that the
first letter of the class name will be forced to uppercase to give the
name of a type in Go. A constructor will be named <tt>New</tt>
followed by that name, and the destructor will be
named <tt>Delete</tt> followed by that name.
</p>
<H3><a name="Go_constants"></a>20.3.3 Go Constants</H3>
<p>
C/C++ constants created via <tt>#define</tt> or the <tt>%constant</tt>
directive become Go constants, declared with a <tt>const</tt>
declaration.
<H3><a name="Go_enumerations"></a>20.3.4 Go Enumerations</H3>
<p>
C/C++ enumeration types will cause SWIG to define an integer type with
the name of the enumeration (with first letter forced to uppercase as
usual). The values of the enumeration will become variables in Go;
code should avoid modifying those variables.
</p>
<H3><a name="Go_classes"></a>20.3.5 Go Classes</H3>
<p>
Go has interfaces, methods and inheritance, but it does not have
classes in the same sense as C++. This sections describes how SWIG
represents C++ classes represented in Go.
</p>
<p>
For a C++ class <tt>ClassName</tt>, SWIG will define two types in Go:
an underlying type, which will just hold a pointer to the C++ type,
and an interface type. The interface type will be
named <tt>ClassName</tt>. SWIG will define a
function <tt>NewClassName</tt> which will take any constructor
arguments and return a value of the interface
type <tt>ClassName</tt>. SWIG will also define a
destructor <tt>DeleteClassName</tt>.
</p>
<p>
SWIG will represent any methods of the C++ class as methods on the
underlying type, and also as methods of the interface type. Thus C++
methods may be invoked directly using the
usual <tt>val.MethodName</tt> syntax. Public members of the C++ class
will be given getter and setter functions defined as methods of the
class.
</p>
<p>
SWIG will represent static methods of C++ classes as ordinary Go
functions. SWIG will use names like <tt>ClassName_MethodName</tt>.
SWIG will give static members getter and setter functions with names
like <tt>GetClassName_VarName</tt>.
</p>
<p>
Given a value of the interface type, Go code can retrieve the pointer
to the C++ type by calling the <tt>Swigcptr</tt> method. This will
return a value of type <tt>SwigcptrClassName</tt>, which is just a
name for <tt>uintptr</tt>. A Go type conversion can be used to
convert this value to a different C++ type, but note that this
conversion will not be type checked and is essentially equivalent
to <tt>reinterpret_cast</tt>. This should only be used for very
special cases, such as where C++ would use a <tt>dynamic_cast</tt>.
</p>
<H4><a name="Go_class_inheritance"></a>20.3.5.1 Go Class Inheritance</H4>
<p>
C++ class inheritance is automatically represented in Go due to its
use of interfaces. The interface for a child class will be a superset
of the interface of its parent class. Thus a value of the child class
type in Go may be passed to a function which expects the parent class.
Doing the reverse will require an explicit type assertion, which will
be checked dynamically.
</p>
<H3><a name="Go_templates"></a>20.3.6 Go Templates</H3>
<p>
In order to use C++ templates in Go, you must tell SWIG to create
wrappers for a particular template instantation. To do this, use
the <tt>%template</tt> directive.
<H3><a name="Go_director_classes"></a>20.3.7 Go Director Classes</H3>
<p>
SWIG's director feature permits a Go type to act as the subclass of a
C++ class with virtual methods. This is complicated by the fact that
C++ and Go define inheritance differently. In Go, structs can inherit
methods via anonymous field embedding. However, when a method is
called for an embedded struct, if that method calls any other methods,
they are called for the embedded struct, not for the original type.
Therefore, SWIG must use Go interfaces to represent C++ inheritance.
</p>
<p>
In order to use the director feature in Go, you must define a type in
your Go code. You must then add methods for the type. Define a
method in Go for each C++ virtual function that you want to override.
You must then create a value of your new type, and pass a pointer to
it to the function <tt>NewDirectorClassName</tt>,
where <tt>ClassName</tt> is the name of the C++ class. That will
return a value of type <tt>ClassName</tt>.
</p>
<p>
For example:
</p>
<div class="code">
<pre>
type GoClass struct { }
func (p *GoClass) VirtualFunction() { }
func MakeClass() ClassName {
return NewDirectorClassName(&amp;GoClass{})
}
</pre>
</div>
<p>
Any call in C++ code to the virtual function will wind up calling the
method defined in Go. The Go code may of course call other methods on
itself, and those methods may be defined either in Go or in C++.
</p>
<H3><a name="Go_primitive_type_mappings"></a>20.3.8 Default Go primitive type mappings</H3>
<p>
The following table lists the default type mapping from C/C++ to Go.
This table will tell you which Go type to expect for a function which
uses a given C/C++ type.
</p>
<table BORDER summary="Go primitive type mappings">
<tr>
<td><b>C/C++ type</b></td>
<td><b>Go type</b></td>
</tr>
<tr>
<td>bool</td>
<td>bool</td>
</tr>
<tr>
<td>char</td>
<td>byte</td>
</tr>
<tr>
<td>signed char</td>
<td>int8</td>
</tr>
<tr>
<td>unsigned char</td>
<td>byte</td>
</tr>
<tr>
<td>short</td>
<td>int16</td>
</tr>
<tr>
<td>unsigned short</td>
<td>uint16</td>
</tr>
<tr>
<td>int</td>
<td>int</td>
</tr>
<tr>
<td>unsigned int</td>
<td>uint</td>
</tr>
<tr>
<td>long</td>
<td>int32 or int64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>unsigned long</td>
<td>uint32 or uint64, depending on <tt>-long-type-size</tt></td>
</tr>
<tr>
<td>long long</td>
<td>int64</td>
</tr>
<tr>
<td>unsigned long long</td>
<td>uint64</td>
</tr>
<tr>
<td>float</td>
<td>float32</td>
</tr>
<tr>
<td>double</td>
<td>float64</td>
</tr>
<tr>
<td>char *<br>char []</td>
<td>string</td>
</tr>
</table>
<p>
Note that SWIG wraps the C <tt>char</tt> type as a character. Pointers
and arrays of this type are wrapped as strings. The <tt>signed
char</tt> type can be used if you want to treat <tt>char</tt> as a
signed number rather than a character. Also note that all const
references to primitive types are treated as if they are passed by
value.
</p>
<p>
These type mappings are defined by the "gotype" typemap. You may change
that typemap, or add new values, to control how C/C++ types are mapped
into Go types.
</p>
</body>
</html>

50
Doc/Manual/Guile.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Guile"></a>20 SWIG and Guile</H1>
<H1><a name="Guile"></a>21 SWIG and Guile</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -47,7 +47,7 @@
<p>
This section details guile-specific support in SWIG.
<H2><a name="Guile_nn2"></a>20.1 Meaning of "Module"</H2>
<H2><a name="Guile_nn2"></a>21.1 Meaning of "Module"</H2>
<p>
@ -55,7 +55,7 @@ There are three different concepts of "module" involved, defined
separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
we explicitly prefix the context, e.g., "guile-module".
<H2><a name="Guile_nn3"></a>20.2 Using the SCM or GH Guile API</H2>
<H2><a name="Guile_nn3"></a>21.2 Using the SCM or GH Guile API</H2>
<p>The guile module can currently export wrapper files that use the guile GH interface or the
@ -69,7 +69,7 @@ SCM interface is the default. The SCM and GH interface differ greatly in how th
pointers and have completely different run-time code. See below for more info.
<p>The GH interface to guile is deprecated. Read more about why in the
<a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
<a href="http://www.gnu.org/software/guile/docs/docs-1.6/guile-ref/GH.html#GH">Guile manual</a>.
The idea of the GH interface was to provide a high level API that other languages and projects
could adopt. This was a good idea, but didn't pan out well for general development. But for the
specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
@ -103,7 +103,7 @@ for the specific API. Currently only the guile language module has created a ma
but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
If that happens, there is A LOT less code duplication in the standard typemaps.</p>
<H2><a name="Guile_nn4"></a>20.3 Linkage</H2>
<H2><a name="Guile_nn4"></a>21.3 Linkage</H2>
<p>
@ -111,7 +111,7 @@ Guile support is complicated by a lack of user community cohesiveness,
which manifests in multiple shared-library usage conventions. A set of
policies implementing a usage convention is called a <b>linkage</b>.
<H3><a name="Guile_nn5"></a>20.3.1 Simple Linkage</H3>
<H3><a name="Guile_nn5"></a>21.3.1 Simple Linkage</H3>
<p>
@ -206,7 +206,7 @@ placed between the <code>define-module</code> form and the
<code>SWIG_init</code> via a preprocessor define to avoid symbol
clashes. For this case, however, passive linkage is available.
<H3><a name="Guile_nn6"></a>20.3.2 Passive Linkage</H3>
<H3><a name="Guile_nn6"></a>21.3.2 Passive Linkage</H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -216,7 +216,7 @@ package name (see below).
<p>You should use passive linkage rather than simple linkage when you
are using multiple modules.
<H3><a name="Guile_nn7"></a>20.3.3 Native Guile Module Linkage</H3>
<H3><a name="Guile_nn7"></a>21.3.3 Native Guile Module Linkage</H3>
<p>SWIG can also generate wrapper code that does all the Guile module
@ -257,7 +257,7 @@ Newer Guile versions have a shorthand procedure for this:
</div>
</ul>
<H3><a name="Guile_nn8"></a>20.3.4 Old Auto-Loading Guile Module Linkage</H3>
<H3><a name="Guile_nn8"></a>21.3.4 Old Auto-Loading Guile Module Linkage</H3>
<p>Guile used to support an autoloading facility for object-code
@ -283,7 +283,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<H3><a name="Guile_nn9"></a>20.3.5 Hobbit4D Linkage</H3>
<H3><a name="Guile_nn9"></a>21.3.5 Hobbit4D Linkage</H3>
<p>
@ -308,7 +308,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
experimental; the (hobbit4d link) conventions are not well understood.
</p>
<H2><a name="Guile_nn10"></a>20.4 Underscore Folding</H2>
<H2><a name="Guile_nn10"></a>21.4 Underscore Folding</H2>
<p>
@ -320,7 +320,7 @@ complained so far.
<code>%rename</code> to specify the Guile name of the wrapped
functions and variables (see CHANGES).
<H2><a name="Guile_nn11"></a>20.5 Typemaps</H2>
<H2><a name="Guile_nn11"></a>21.5 Typemaps</H2>
<p>
@ -409,10 +409,10 @@ See also the "multivalue" example.
%feature("constasvar") can be applied to any constant, immutable variable, or enum.
Instead of exporting the constant as a function that must be called, the
constant will appear as a scheme variable. See
<a href="Customization.html#features">Features and the %feature directive</a>
<a href="Customization.html#Customization_features">Features and the %feature directive</a>
for info on how to apply the %feature.</p>
<H2><a name="Guile_nn12"></a>20.6 Representation of pointers as smobs</H2>
<H2><a name="Guile_nn12"></a>21.6 Representation of pointers as smobs</H2>
<p>
@ -433,7 +433,7 @@ representing the expected pointer type. See also
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>20.6.1 GH Smobs</H3>
<H3><a name="Guile_nn13"></a>21.6.1 GH Smobs</H3>
<p>
@ -462,7 +462,7 @@ that created them, so the first module we check will most likely be correct.
Once we have a swig_type_info structure, we loop through the linked list of
casts, using pointer comparisons.</p>
<H3><a name="Guile_nn14"></a>20.6.2 SCM Smobs</H3>
<H3><a name="Guile_nn14"></a>21.6.2 SCM Smobs</H3>
<p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
@ -477,7 +477,7 @@ in the smob tag. If a generated GOOPS module has been loaded, smobs will be wra
GOOPS class.</p>
<H3><a name="Guile_nn15"></a>20.6.3 Garbage Collection</H3>
<H3><a name="Guile_nn15"></a>21.6.3 Garbage Collection</H3>
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
@ -487,11 +487,11 @@ to the destructor for this type. The destructor is the generated wrapper around
So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
the wrapped delete function. So the only way to delete an object is from the garbage collector, since the
delete function is not available to scripts. How swig determines if a type should be garbage collected
is exactly like described in <a href="Customization.html#ownership">
is exactly like described in <a href="Customization.html#Customization_ownership">
Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
<H2><a name="Guile_nn16"></a>20.7 Exception Handling</H2>
<H2><a name="Guile_nn16"></a>21.7 Exception Handling</H2>
<p>
@ -517,7 +517,7 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<H2><a name="Guile_nn17"></a>20.8 Procedure documentation</H2>
<H2><a name="Guile_nn17"></a>21.8 Procedure documentation</H2>
<p>If invoked with the command-line option <code>-procdoc
@ -553,7 +553,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<H2><a name="Guile_nn18"></a>20.9 Procedures with setters</H2>
<H2><a name="Guile_nn18"></a>21.9 Procedures with setters</H2>
<p>For global variables, SWIG creates a single wrapper procedure
@ -581,7 +581,7 @@ struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
pointer)</code> and <code>(<var>struct-member</var>-set pointer
value)</code> are <em>not</em> generated.
<H2><a name="Guile_nn19"></a>20.10 GOOPS Proxy Classes</H2>
<H2><a name="Guile_nn19"></a>21.10 GOOPS Proxy Classes</H2>
<p>SWIG can also generate classes and generic functions for use with
@ -730,7 +730,7 @@ Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put th
<code>%import "foo.h"</code> before the <code>%inline</code> block.
</p>
<H3><a name="Guile_nn20"></a>20.10.1 Naming Issues</H3>
<H3><a name="Guile_nn20"></a>21.10.1 Naming Issues</H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -767,9 +767,7 @@ guile-modules. For example,</p>
(use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
</pre></div>
<p>TODO: Renaming class name prefixes?</p>
<H3><a name="Guile_nn21"></a>20.10.2 Linking</H3>
<H3><a name="Guile_nn21"></a>21.10.2 Linking</H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires

15
Doc/Manual/Introduction.html
View file

@ -37,7 +37,7 @@
<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
nutshell, SWIG is a compiler that takes C/C++ declarations and creates
the wrappers needed to access those declarations from other languages including
including Perl, Python, Tcl, Ruby, Guile, and Java. SWIG normally
requires no modifications to existing code and can often be used to
@ -68,7 +68,8 @@ a dedicated IDL compiler). Although
this style of development isn't appropriate for every
project, it is particularly well suited to software development in the
small; especially the research and development work that is commonly found
in scientific and engineering projects.
in scientific and engineering projects. However, nowadays SWIG is known to be used in many
large open source and commercial projects.
<H2><a name="Introduction_nn3"></a>2.2 Why use SWIG?</H2>
@ -365,7 +366,7 @@ possible to support different types of interfaces depending on the application.
<p>
SWIG is a command line tool and as such can be incorporated into any build system that supports invoking external tools/compilers.
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from from popular IDEs such as
SWIG is most commonly invoked from within a Makefile, but is also known to be invoked from popular IDEs such as
Microsoft Visual Studio.
</p>
@ -375,10 +376,10 @@ If you are using the GNU Autotools
<a href="http://www.gnu.org/software/automake">Automake</a>/
<a href="http://www.gnu.org/software/libtool">Libtool</a>)
to configure SWIG use in your project, the SWIG Autoconf macros can be used.
The primary macro is <tt>ac_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html">http://www.gnu.org/software/ac-archive/htmldoc/ac_pkg_swig.html</a>.
The <tt>ac_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/ac-archive/htmldoc/index.html">Autoconf Macro Archive</a>
The primary macro is <tt>ax_pkg_swig</tt>, see
<a href="http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig">http://www.gnu.org/software/autoconf-archive/ax_pkg_swig.html#ax_pkg_swig</a>.
The <tt>ax_python_devel</tt> macro is also helpful for generating Python extensions. See the
<a href="http://www.gnu.org/software/autoconf-archive/">Autoconf Archive</a>
for further information on this and other Autoconf macros.
</p>

582
Doc/Manual/Java.html
View file

File diff suppressed because it is too large Load diff

142
Doc/Manual/Library.html
View file

@ -27,9 +27,10 @@
</ul>
<li><a href="#Library_stl_cpp_library">STL/C++ Library</a>
<ul>
<li><a href="#Library_nn14">std_string.i</a>
<li><a href="#Library_nn15">std_vector.i</a>
<li><a href="#Library_std_string">std::string</a>
<li><a href="#Library_std_vector">std::vector</a>
<li><a href="#Library_stl_exceptions">STL exceptions</a>
<li><a href="#Library_std_shared_ptr">shared_ptr smart pointer</a>
</ul>
<li><a href="#Library_nn16">Utility Libraries</a>
<ul>
@ -893,7 +894,7 @@ char *foo();
This will release the result if the appropriate target language support is available.
SWIG provides the appropriate "newfree" typemap for <tt>char *</tt> so that the memory is released,
however, you may need to provide your own "newfree" typemap for other types.
See <a href="Customization.html#ownership">Object ownership and %newobject</a> for more details.
See <a href="Customization.html#Customization_ownership">Object ownership and %newobject</a> for more details.
</p>
<H3><a name="Library_nn12"></a>8.3.4 cstring.i</H3>
@ -1383,6 +1384,7 @@ The following table shows which C++ classes are supported and the equivalent SWI
<tr> <td>std::set</td> <td>set</td> <td>std_set.i</td> </tr>
<tr> <td>std::string</td> <td>string</td> <td>std_string.i</td> </tr>
<tr> <td>std::vector</td> <td>vector</td> <td>std_vector.i</td> </tr>
<tr> <td>std::shared_ptr</td> <td>shared_ptr</td> <td>std_shared_ptr.i</td> </tr>
</table>
@ -1392,7 +1394,7 @@ Please look for the library files in the appropriate language library directory.
</p>
<H3><a name="Library_nn14"></a>8.4.1 std_string.i</H3>
<H3><a name="Library_std_string"></a>8.4.1 std::string</H3>
<p>
@ -1476,16 +1478,11 @@ void foo(string s, const String &amp;t); // std_string typemaps still applie
</pre>
</div>
<p>
<b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
We're looking into it.
</p>
<H3><a name="Library_nn15"></a>8.4.2 std_vector.i</H3>
<H3><a name="Library_std_vector"></a>8.4.2 std::vector</H3>
<p>
The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
The <tt>std_vector.i</tt> library provides support for the C++ <tt>std::vector</tt> class in the STL.
Using this library involves the use of the <tt>%template</tt> directive. All you need to do is to
instantiate different versions of <tt>vector</tt> for the types that you want to use. For example:
</p>
@ -1660,11 +1657,6 @@ if you want to make their head explode.
details and the public API exposed to the interpreter vary.
</p>
<p>
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
</p>
<H3><a name="Library_stl_exceptions"></a>8.4.3 STL exceptions</H3>
@ -1715,6 +1707,124 @@ The <tt>%exception</tt> directive can be used by placing the following code befo
Any thrown STL exceptions will then be gracefully handled instead of causing a crash.
</p>
<H3><a name="Library_std_shared_ptr"></a>8.4.4 shared_ptr smart pointer</H3>
<p>
Some target languages have support for handling the widely used <tt>boost::shared_ptr</tt> smart pointer.
This smart pointer is also available as <tt>std::tr1::shared_ptr</tt> before it becomes fully standardized as <tt>std::shared_ptr</tt>.
The <tt>boost_shared_ptr.i</tt> library provides support for <tt>boost::shared_ptr</tt> and <tt>std_shared_ptr.i</tt> provides support for <tt>std::shared_ptr</tt>, but if the following macro is defined as shown, it can be used for <tt>std::tr1::shared_ptr</tt>:
</p>
<div class="code">
<pre>
#define SWIG_SHARED_PTR_SUBNAMESPACE tr1
%include &lt;std_shared_ptr.i&gt;
</pre>
</div>
<p>
You can only use one of these variants of shared_ptr in your interface file at a time.
and all three variants must be used in conjunction with the <tt>%shared_ptr(T)</tt> macro,
where <tt>T</tt> is the underlying pointer type equating to usage <tt>shared_ptr&lt;T&gt;</tt>.
The type <tt>T</tt> must be non-primitive.
A simple example demonstrates usage:
</p>
<div class="code">
<pre>
%module example
%include &lt;boost_shared_ptr.i&gt;
%shared_ptr(IntValue)
%inline %{
#include &lt;boost/shared_ptr.hpp&gt;
struct IntValue {
int value;
IntValue(int v) : value(v) {}
};
static int extractValue(const IntValue &amp;t) {
return t.value;
}
static int extractValueSmart(boost::shared_ptr&lt;IntValue&gt; t) {
return t-&gt;value;
}
%}
</pre>
</div>
<p>
Note that the <tt>%shared_ptr(IntValue)</tt> declaration occurs after the inclusion of the <tt>boost_shared_ptr.i</tt>
library which provides the macro and, very importantly, before any usage or declaration of the type, <tt>IntValue</tt>.
The <tt>%shared_ptr</tt> macro provides, a few things for handling this smart pointer, but mostly a number of
typemaps. These typemaps override the default typemaps so that the underlying proxy class is stored and passed around
as a pointer to a <tt>shared_ptr</tt> instead of a plain pointer to the underlying type.
This approach means that any instantiation of the type can be passed to methods taking the type by value, reference, pointer
or as a smart pointer.
The interested reader might want to look at the generated code, however, usage is simple and no different
handling is required from the target language.
For example, a simple use case of the above code from Java would be:
</p>
<div class="targetlang">
<pre>
IntValue iv = new IntValue(1234);
int val1 = example.extractValue(iv);
int val2 = example.extractValueSmart(iv);
System.out.println(val1 + " " + val2);
</pre>
</div>
<p>
This shared_ptr library works quite differently to SWIG's normal, but somewhat limited,
<a href="SWIGPlus.html#SWIGPlus_smart_pointers">smart pointer handling</a>.
The shared_ptr library does not generate extra wrappers, just for smart pointer handling, in addition to the proxy class.
The normal proxy class including inheritance relationships is generated as usual.
The only real change introduced by the <tt>%shared_ptr</tt> macro is that the proxy class stores a pointer to the shared_ptr instance instead of a raw pointer to the instance.
A proxy class derived from a base which is being wrapped with shared_ptr can and <b>must</b> be wrapped as a shared_ptr too.
In other words all classes in an inheritance hierarchy must all be used with the <tt>%shared_ptr</tt> macro.
For example the following code can be used with the base class shown earlier:
</p>
<div class="code">
<pre>
%shared_ptr(DerivedIntValue)
%inline %{
struct DerivedIntValue : IntValue {
DerivedIntValue(int value) : IntValue(value) {}
...
};
%}
</pre>
</div>
<p>
Note that if the <tt>%shared_ptr</tt> macro is omitted for any class in the inheritance hierarchy, it will
result in a C++ compiler error.
For example if the above <tt>%shared_ptr(DerivedIntValue)</tt> is omitted, the following is typical of the compiler error that will result:
</p>
<div class="shell">
<pre>
example_wrap.cxx: In function 'void Java_exampleJNI_delete_1DerivedIntValue(JNIEnv*, _jclass*, jlong)':
example_wrap.cxx:3169: error: 'smartarg1' was not declared in this scope
</pre>
</div>
<p>
A shared_ptr of the derived class can now be passed to a method where the base is expected in the target language, just as it can in C++:
</p>
<div class="targetlang">
<pre>
DerivedIntValue div = new DerivedIntValue(5678);
int val3 = example.extractValue(div);
int val4 = example.extractValueSmart(div);
</pre>
</div>
<H2><a name="Library_nn16"></a>8.5 Utility Libraries</H2>

30
Doc/Manual/Lisp.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lisp_nn1"></a>22 SWIG and Common Lisp</H1>
<H1><a name="Lisp"></a>23 SWIG and Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,16 +41,16 @@
Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI
foreign function interfaces.
</p>
<H2><a name="Lisp_nn2"></a>22.1 Allegro Common Lisp</H2>
<H2><a name="Lisp_nn2"></a>23.1 Allegro Common Lisp</H2>
<p>
Allegro Common Lisp support in SWIG has been updated to include
support for both C and C++. You can read about the interface
<a href="Allegrocl.html#Allegrocl_nn1">here</a>
<a href="Allegrocl.html#Allegrocl">here</a>
</p>
<H2><a name="Lisp_nn3"></a>22.2 Common Foreign Function Interface(CFFI)</H2>
<H2><a name="Lisp_nn3"></a>23.2 Common Foreign Function Interface(CFFI)</H2>
<p>
@ -77,7 +77,7 @@ swig -cffi -module <i>module-name</i> <i>file-name</i>
files and the various things which you can do with them.
</p>
<H3><a name="Lisp_nn4"></a>22.2.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn4"></a>23.2.1 Additional Commandline Options </H3>
<p>
@ -96,14 +96,14 @@ swig -cffi -help
<tr>
<td>-generate-typedef</td>
<td>If this option is given then defctype will be used to generate<br\>
<td>If this option is given then defctype will be used to generate<br/>
shortcuts according to the typedefs in the input.
</td>
</tr>
<tr>
<td>-[no]cwrap</td>
<td>Turn on or turn off generation of an intermediate C file when<br\>
<td>Turn on or turn off generation of an intermediate C file when<br/>
creating a C interface. By default this is only done for C++ code.
</td>
</tr>
@ -118,7 +118,7 @@ swig -cffi -help
</table>
<H3><a name="Lisp_nn5"></a>22.2.2 Generating CFFI bindings</H3>
<H3><a name="Lisp_nn5"></a>23.2.2 Generating CFFI bindings</H3>
As we mentioned earlier the ideal way to use SWIG is to use interface
@ -269,7 +269,7 @@ The generated SWIG Code will be:
want to lispify the names, also, before we forget you want to
export the generated lisp names. To do this, we will use the
SWIG <a
href="Customization.html#features">feature directive</a>.
href="Customization.html#Customization_features">feature directive</a>.
Let's edit the interface file such that the C type "div_t*" is changed
to Lisp type ":my-pointer", we lispify all names,
export everything, and do some more stuff.
@ -392,7 +392,7 @@ The feature <i>intern_function</i> ensures that all C names are
</pre></div>
<H3><a name="Lisp_nn6"></a>22.2.3 Generating CFFI bindings for C++ code</H3>
<H3><a name="Lisp_nn6"></a>23.2.3 Generating CFFI bindings for C++ code</H3>
<p>This feature to SWIG (for CFFI) is very new and still far from
@ -568,7 +568,7 @@ If you have any questions, suggestions, patches, etc., related to CFFI
module feel free to contact us on the SWIG mailing list, and
also please add a "[CFFI]" tag in the subject line.
<H3><a name="Lisp_nn7"></a>22.2.4 Inserting user code into generated files</H3>
<H3><a name="Lisp_nn7"></a>23.2.4 Inserting user code into generated files</H3>
<p>
@ -608,7 +608,7 @@ Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
</p>
<H2><a name="Lisp_nn8"></a>22.3 CLISP</H2>
<H2><a name="Lisp_nn8"></a>23.3 CLISP</H2>
<p>
@ -638,7 +638,7 @@ swig -clisp -module <i>module-name</i> <i>file-name</i>
interface file for the CLISP module. The CLISP module tries to
produce code which is both human readable and easily modifyable.
</p>
<H3><a name="Lisp_nn9"></a>22.3.1 Additional Commandline Options </H3>
<H3><a name="Lisp_nn9"></a>23.3.1 Additional Commandline Options </H3>
<p>
@ -671,7 +671,7 @@ and global variables will be created otherwise only definitions for<br/>
</table>
<H3><a name="Lisp_nn10"></a>22.3.2 Details on CLISP bindings</H3>
<H3><a name="Lisp_nn10"></a>23.3.2 Details on CLISP bindings</H3>
<p>
@ -795,7 +795,7 @@ struct bar {
</pre></div>
<H2><a name="Lisp_nn11"></a>22.4 UFFI </H2>
<H2><a name="Lisp_nn11"></a>23.4 UFFI </H2>
</body>

82
Doc/Manual/Lua.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua_nn1"></a>23 SWIG and Lua</H1>
<H1><a name="Lua"></a>24 SWIG and Lua</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -67,13 +67,13 @@
<p>
Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight configuration language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++). Its also a <em>really</em> tiny language, less than 6000 lines of code, which compiles to &lt;100 kilobytes of binary code. It can be found at <a href="http://www.lua.org">http://www.lua.org</a>
</p>
<H2><a name="Lua_nn2"></a>23.1 Preliminaries</H2>
<H2><a name="Lua_nn2"></a>24.1 Preliminaries</H2>
<p>
The current SWIG implementation is designed to work with Lua 5.0.x and Lua 5.1.x. It should work with later versions of Lua, but certainly not with Lua 4.0 due to substantial API changes. ((Currently SWIG generated code has only been tested on Windows with MingW, though given the nature of Lua, is should not have problems on other OS's)). It is possible to either static link or dynamic link a Lua module into the interpreter (normally Lua static links its libraries, as dynamic linking is not available on all platforms).
</p>
<H2><a name="Lua_nn3"></a>23.2 Running SWIG</H2>
<H2><a name="Lua_nn3"></a>24.2 Running SWIG</H2>
<p>
@ -105,7 +105,7 @@ This creates a C/C++ source file <tt>example_wrap.c</tt> or <tt>example_wrap.cxx
<p>
The name of the wrapper file is derived from the name of the input file. For example, if the input file is <tt>example.i</tt>, the name of the wrapper file is <tt>example_wrap.c</tt>. To change this, you can use the -o option. The wrappered module will export one function <tt>"int luaopen_example(lua_State* L)"</tt> which must be called to register the module with the Lua interpreter. The name "luaopen_example" depends upon the name of the module.
</p>
<H3><a name="Lua_nn4"></a>23.2.1 Compiling and Linking and Interpreter</H3>
<H3><a name="Lua_nn4"></a>24.2.1 Compiling and Linking and Interpreter</H3>
<p>
@ -152,7 +152,7 @@ $ gcc -c example.c -o example.o
$ gcc -I/usr/include/lua -L/usr/lib/lua min.o example_wrap.o example.o -o my_lua
</pre></div>
<H3><a name="Lua_nn5"></a>23.2.2 Compiling a dynamic module</H3>
<H3><a name="Lua_nn5"></a>24.2.2 Compiling a dynamic module</H3>
<p>
@ -220,7 +220,7 @@ Is quite obvious (Go back and consult the Lua documents on how to enable loadlib
<H3><a name="Lua_nn6"></a>23.2.3 Using your module</H3>
<H3><a name="Lua_nn6"></a>24.2.3 Using your module</H3>
<p>
@ -238,19 +238,19 @@ $ ./my_lua
&gt;
</pre></div>
<H2><a name="Lua_nn7"></a>23.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Lua_nn7"></a>24.3 A tour of basic C/C++ wrapping</H2>
<p>
By default, SWIG tries to build a very natural Lua interface to your C/C++ code. This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Lua_nn8"></a>23.3.1 Modules</H3>
<H3><a name="Lua_nn8"></a>24.3.1 Modules</H3>
<p>
The SWIG module directive specifies the name of the Lua module. If you specify `module example', then everything is wrapped into a Lua table 'example' containing all the functions and variables. When choosing a module name, make sure you don't use the same name as a built-in Lua command or standard module name.
</p>
<H3><a name="Lua_nn9"></a>23.3.2 Functions</H3>
<H3><a name="Lua_nn9"></a>24.3.2 Functions</H3>
<p>
@ -288,7 +288,7 @@ It is also possible to rename the module with an assignment.
24
</pre></div>
<H3><a name="Lua_nn10"></a>23.3.3 Global variables</H3>
<H3><a name="Lua_nn10"></a>24.3.3 Global variables</H3>
<p>
@ -334,7 +334,7 @@ extern double Foo;
%mutable;
</pre></div>
<p>
SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>
&gt; print(e.Foo) -- reading works ok
@ -362,7 +362,7 @@ nil
3.142
</pre></div>
<H3><a name="Lua_nn11"></a>23.3.4 Constants and enums</H3>
<H3><a name="Lua_nn11"></a>24.3.4 Constants and enums</H3>
<p>
@ -385,7 +385,7 @@ example.SUNDAY=0
<p>
Constants are not guaranteed to remain constant in Lua. The name of the constant could be accidentally reassigned to refer to some other object. Unfortunately, there is no easy way for SWIG to generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Lua_nn12"></a>23.3.5 Pointers</H3>
<H3><a name="Lua_nn12"></a>24.3.5 Pointers</H3>
<p>
@ -423,7 +423,7 @@ Lua enforces the integrity of its userdata, so it is virtually impossible to cor
nil
</pre></div>
<H3><a name="Lua_nn13"></a>23.3.6 Structures</H3>
<H3><a name="Lua_nn13"></a>24.3.6 Structures</H3>
<p>
@ -509,7 +509,7 @@ Because the pointer points inside the structure, you can modify the contents and
&gt; x.a = 3 -- Modifies the same structure
</pre></div>
<H3><a name="Lua_nn14"></a>23.3.7 C++ classes</H3>
<H3><a name="Lua_nn14"></a>24.3.7 C++ classes</H3>
<p>
@ -570,7 +570,7 @@ It is not (currently) possible to access static members of an instance:
-- does NOT work
</pre></div>
<H3><a name="Lua_nn15"></a>23.3.8 C++ inheritance</H3>
<H3><a name="Lua_nn15"></a>24.3.8 C++ inheritance</H3>
<p>
@ -595,7 +595,7 @@ then the function <tt>spam()</tt> accepts a Foo pointer or a pointer to any clas
<p>
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Lua_nn16"></a>23.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Lua_nn16"></a>24.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -626,7 +626,7 @@ Foo spam7();
<p>
then all three functions will return a pointer to some Foo object. Since the third function (spam7) returns a value, newly allocated memory is used to hold the result and a pointer is returned (Lua will release this memory when the return value is garbage collected). The other two are pointers which are assumed to be managed by the C code and so will not be garbage collected.
</p>
<H3><a name="Lua_nn17"></a>23.3.10 C++ overloaded functions</H3>
<H3><a name="Lua_nn17"></a>24.3.10 C++ overloaded functions</H3>
<p>
@ -712,7 +712,7 @@ Please refer to the "SWIG and C++" chapter for more information about overloadin
<p>
Dealing with the Lua coercion mechanism, the priority is roughly (integers, floats, strings, userdata). But it is better to rename the functions rather than rely upon the ordering.
</p>
<H3><a name="Lua_nn18"></a>23.3.11 C++ operators</H3>
<H3><a name="Lua_nn18"></a>24.3.11 C++ operators</H3>
<p>
@ -824,7 +824,7 @@ It is also possible to overload the operator<tt>[]</tt>, but currently this cann
};
</pre></div>
<H3><a name="Lua_nn19"></a>23.3.12 Class extension with %extend</H3>
<H3><a name="Lua_nn19"></a>24.3.12 Class extension with %extend</H3>
<p>
@ -879,7 +879,7 @@ true
<p>
Extend works with both C and C++ code, on classes and structs. It does not modify the underlying object in any way---the extensions only show up in the Lua interface. The only item to take note of is the code has to use the '$self' instead of 'this', and that you cannot access protected/private members of the code (as you are not officially part of the class).
</p>
<H3><a name="Lua_nn20"></a>23.3.13 C++ templates</H3>
<H3><a name="Lua_nn20"></a>24.3.13 C++ templates</H3>
<p>
@ -914,7 +914,7 @@ In Lua:
<p>
Obviously, there is more to template wrapping than shown in this example. More details can be found in the SWIG and C++ chapter. Some more complicated examples will appear later.
</p>
<H3><a name="Lua_nn21"></a>23.3.14 C++ Smart Pointers</H3>
<H3><a name="Lua_nn21"></a>24.3.14 C++ Smart Pointers</H3>
<p>
@ -966,7 +966,7 @@ If you ever need to access the underlying pointer returned by <tt>operator-&gt;(
&gt; f = p:__deref__() -- Returns underlying Foo *
</pre></div>
<H3><a name="Lua_nn22"></a>23.3.15 C++ Exceptions</H3>
<H3><a name="Lua_nn22"></a>24.3.15 C++ Exceptions</H3>
<p>
@ -1099,23 +1099,23 @@ userdata: 0003D880
</pre></div>
<p>
Note: is is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this
Note: it is also possible (though tedious) to have a function throw several different kinds of exceptions. To process this
will require a pcall, followed by a set of if statements checking the type of the error.
</p>
<p>
All of this code assumes that your C++ code uses exception specification (which a lot doesn't).
If it doesn't consult the "<a href="SWIGPlus.html#SWIGPlus_catches">Exception handling with %catches</a>" section
and the "<a href="Customization.html#exception">Exception handling with %exception</a>" section, for more details on how to
and the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section, for more details on how to
add exception specification to functions or globally (respectively).
</p>
<H2><a name="Lua_nn23"></a>23.4 Typemaps</H2>
<H2><a name="Lua_nn23"></a>24.4 Typemaps</H2>
<p>This section explains what typemaps are and the usage of them. The default wrappering behaviour of SWIG is enough in most cases. However sometimes SWIG may need a little additional assistance to know which typemap to apply to provide the best wrappering. This section will be explaining how to use typemaps to best effect</p>
<H3><a name="Lua_nn24"></a>23.4.1 What is a typemap?</H3>
<H3><a name="Lua_nn24"></a>24.4.1 What is a typemap?</H3>
<p>A typemap is nothing more than a code generation rule that is attached to a specific C datatype. For example, to convert integers from Lua to C, you might define a typemap like this:</p>
@ -1143,7 +1143,7 @@ Received an integer : 6
720
</pre></div>
<H3><a name="Lua_nn25"></a>23.4.2 Using typemaps</H3>
<H3><a name="Lua_nn25"></a>24.4.2 Using typemaps</H3>
<p>There are many ready written typemaps built into SWIG for all common types (int, float, short, long, char*, enum and more), which SWIG uses automatically, with no effort required on your part.</p>
@ -1196,7 +1196,7 @@ void swap(int *sx, int *sy);
<p>Note: C++ references must be handled exactly the same way. However SWIG will automatically wrap a <tt>const int&amp;</tt> as an input parameter (since that it obviously input).</p>
<H3><a name="Lua_nn26"></a>23.4.3 Typemaps and arrays</H3>
<H3><a name="Lua_nn26"></a>24.4.3 Typemaps and arrays</H3>
<p>Arrays present a challenge for SWIG, because like pointers SWIG does not know whether these are input or output values, nor
@ -1210,7 +1210,7 @@ extern void sort_double(double* arr, int len);
<p>There are basically two ways that SWIG can deal with this. The first way, uses the <tt>&lt;carrays.i&gt;</tt> library
to create an array in C/C++ then this can be filled within Lua and passed into the function. It works, but its a bit tedious.
More details can be found in the <a href="Library.html#Library_nn5">carrays.i</a> documention.</p>
More details can be found in the <a href="Library.html#Library_carrays">carrays.i</a> documention.</p>
<p>The second and more intuitive way, would be to pass a Lua table directly into the function, and have SWIG automatically convert between Lua-table and C-array. Within the <tt>&lt;typemaps.i&gt;</tt> file there are typemaps ready written to perform this task. To use them is again a matter of using %appy in the correct manner.</p>
@ -1260,7 +1260,7 @@ and Lua tables to be 1..N, (the indexing follows the norm for the language). In
<p>Note: SWIG also can support arrays of pointers in a similar manner.</p>
<H3><a name="Lua_nn27"></a>23.4.4 Typemaps and pointer-pointer functions</H3>
<H3><a name="Lua_nn27"></a>24.4.4 Typemaps and pointer-pointer functions</H3>
<p>Several C++ libraries use a pointer-pointer functions to create its objects. These functions require a pointer to a pointer which is then filled with the pointer to the new object. Microsoft's COM and DirectX as well as many other libraries have this kind of function. An example is given below:</p>
@ -1294,7 +1294,7 @@ int Create_Math(iMath** pptr); // its creator (assume it mallocs)
ptr=nil -- the iMath* will be GC'ed as normal
</pre></div>
<H2><a name="Lua_nn28"></a>23.5 Writing typemaps</H2>
<H2><a name="Lua_nn28"></a>24.5 Writing typemaps</H2>
<p>This section describes how you can modify SWIG's default wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> directive. This is an advanced topic that assumes familiarity with the Lua C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.</p>
@ -1303,7 +1303,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<p>Before proceeding, you should read the previous section on using typemaps, as well as read the ready written typemaps found in luatypemaps.swg and typemaps.i. These are both well documented and fairly easy to read. You should not attempt to write your own typemaps until you have read and can understand both of these files (they may well also give you a idea to base your worn on).</p>
<H3><a name="Lua_nn29"></a>23.5.1 Typemaps you can write</H3>
<H3><a name="Lua_nn29"></a>24.5.1 Typemaps you can write</H3>
<p>There are many different types of typemap that can be written, the full list can be found in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter. However the following are the most commonly used ones.</p>
@ -1316,7 +1316,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
(the syntax for the typecheck is different from the typemap, see typemaps for details).</li>
</ul>
<H3><a name="Lua_nn30"></a>23.5.2 SWIG's Lua-C API</H3>
<H3><a name="Lua_nn30"></a>24.5.2 SWIG's Lua-C API</H3>
<p>This section explains the SWIG specific Lua-C API. It does not cover the main Lua-C api, as this is well documented and not worth covering.</p>
@ -1365,7 +1365,7 @@ This macro, when called within the context of a SWIG wrappered function, will di
<div class="indent">
Similar to SWIG_fail_arg, except that it will display the swig_type_info information instead.</div>
<H2><a name="Lua_nn31"></a>23.6 Customization of your Bindings</H2>
<H2><a name="Lua_nn31"></a>24.6 Customization of your Bindings</H2>
<p>
@ -1374,7 +1374,7 @@ This section covers adding of some small extra bits to your module to add the la
<H3><a name="Lua_nn32"></a>23.6.1 Writing your own custom wrappers</H3>
<H3><a name="Lua_nn32"></a>24.6.1 Writing your own custom wrappers</H3>
<p>
@ -1393,7 +1393,7 @@ int native_function(lua_State*L) // my native code
The <tt>%native</tt> directive in the above example, tells SWIG that there is a function <tt>int native_function(lua_State*L);</tt> which is to be added into the module under the name '<tt>my_func</tt>'. SWIG will not add any wrappering for this function, beyond adding it into the function table. How you write your code is entirely up to you.
</p>
<H3><a name="Lua_nn33"></a>23.6.2 Adding additional Lua code</H3>
<H3><a name="Lua_nn33"></a>24.6.2 Adding additional Lua code</H3>
<p>
@ -1431,7 +1431,7 @@ Good uses for this feature is adding of new code, or writing helper functions to
See Examples/lua/arrays for an example of this code.
</p>
<H2><a name="Lua_nn34"></a>23.7 Details on the Lua binding</H2>
<H2><a name="Lua_nn34"></a>24.7 Details on the Lua binding</H2>
<p>
@ -1442,7 +1442,7 @@ See Examples/lua/arrays for an example of this code.
</i>
</p>
<H3><a name="Lua_nn35"></a>23.7.1 Binding global data into the module.</H3>
<H3><a name="Lua_nn35"></a>24.7.1 Binding global data into the module.</H3>
<p>
@ -1502,7 +1502,7 @@ end
<p>
That way when you call '<tt>a=example.Foo</tt>', the interpreter looks at the table 'example' sees that there is no field 'Foo' and calls __index. This will in turn check in '.get' table and find the existence of 'Foo' and then return the value of the C function call 'Foo_get()'. Similarly for the code '<tt>example.Foo=10</tt>', the interpreter will check the table, then call the __newindex which will then check the '.set' table and call the C function 'Foo_set(10)'.
</p>
<H3><a name="Lua_nn36"></a>23.7.2 Userdata and Metatables</H3>
<H3><a name="Lua_nn36"></a>24.7.2 Userdata and Metatables</H3>
<p>
@ -1582,7 +1582,7 @@ Note: Both the opaque structures (like the FILE*) and normal wrappered classes/s
<p>
Note: Operator overloads are basically done in the same way, by adding functions such as '__add' &amp; '__call' to the classes metatable. The current implementation is a bit rough as it will add any member function beginning with '__' into the metatable too, assuming its an operator overload.
</p>
<H3><a name="Lua_nn37"></a>23.7.3 Memory management</H3>
<H3><a name="Lua_nn37"></a>24.7.3 Memory management</H3>
<p>

21
Doc/Manual/Makefile
View file

@ -9,6 +9,7 @@
# validation.
#
# Additional html validation can be done using the validate target.
# Additional link checking can be done using the linkchecker target.
#
# Note the # and " are escaped
@ -28,9 +29,9 @@ CCache.html: ../../CCache/ccache.yo
# it is just used as a primitive HTML checker.
# CCache.html is generated by yodl2html and has a few insignificant problems, so we don't put it through tidy
check:
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
tidy -errors --gnu-emacs yes -quiet index.html
tidy -errors --gnu-emacs yes -quiet Sections.html
all=`sed '/^#/d' chapters | grep -v CCache.html`; for a in $$all; do tidy -errors --gnu-emacs yes -quiet $$a; done;
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book || true
@ -49,7 +50,7 @@ swightml.book:
echo "Sections.html" >> swightml.book
cat chapters >> swightml.book
clean: clean-baks
maintainer-clean: clean-baks
rm -f swightml.book
rm -f swigpdf.book
rm -f CCache.html
@ -60,11 +61,15 @@ clean-baks:
rm -f *.bak
test:
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
grep "href=\".*\.html\"" index.html
grep "href=\".*\.html\"" Sections.html
all=`sed '/^#/d' chapters`; for a in $$all; do grep -l "href=\".*\.html\"" $$a; done;
# Validating using the WDG offline validator - http://www.htmlhelp.com/tools/validator/offline/
validate:
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
all=`sed '/^#/d' chapters`; for a in $$all; do validate --emacs $$a; done;
# Link checking using linkchecker (can take a while - 30 mins)
linkchecker:
linkchecker --anchors Contents.html

279
Doc/Manual/Modula3.html
View file

@ -5,42 +5,39 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Modula3"></a>24 SWIG and Modula-3</H1>
<H1><a name="Modula3"></a>25 SWIG and Modula-3</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#modula3_overview">Overview</a>
<li><a href="#Modula3_modula3_overview">Overview</a>
<ul>
<li><a href="#whyscripting">Why not scripting ?</a>
<li><a href="#whymodula3">Why Modula-3 ?</a>
<li><a href="#whycpp">Why C / C++ ?</a>
<li><a href="#whyswig">Why SWIG ?</a>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#conception">Conception</a>
<li><a href="#Modula3_conception">Conception</a>
<ul>
<li><a href="#cinterface">Interfaces to C libraries</a>
<li><a href="#cppinterface">Interfaces to C++ libraries</a>
<li><a href="#Modula3_cinterface">Interfaces to C libraries</a>
<li><a href="#Modula3_cppinterface">Interfaces to C++ libraries</a>
</ul>
<li><a href="#preliminaries">Preliminaries</a>
<li><a href="#Modula3_preliminaries">Preliminaries</a>
<ul>
<li><a href="#compilers">Compilers</a>
<li><a href="#commandline">Additional Commandline Options</a>
<li><a href="#Modula3_compilers">Compilers</a>
<li><a href="#Modula3_commandline">Additional Commandline Options</a>
</ul>
<li><a href="#modula3_typemaps">Modula-3 typemaps</a>
<li><a href="#Modula3_typemaps">Modula-3 typemaps</a>
<ul>
<li><a href="#inoutparam">Inputs and outputs</a>
<li><a href="#ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#class">Objects</a>
<li><a href="#imports">Imports</a>
<li><a href="#exceptions">Exceptions</a>
<li><a href="#typemap_example">Example</a>
<li><a href="#Modula3_inoutparam">Inputs and outputs</a>
<li><a href="#Modula3_ordinals">Subranges, Enumerations, Sets</a>
<li><a href="#Modula3_class">Objects</a>
<li><a href="#Modula3_imports">Imports</a>
<li><a href="#Modula3_exceptions">Exceptions</a>
<li><a href="#Modula3_typemap_example">Example</a>
</ul>
<li><a href="#hints">More hints to the generator</a>
<li><a href="#Modula3_hints">More hints to the generator</a>
<ul>
<li><a href="#features">Features</a>
<li><a href="#pragmas">Pragmas</a>
<li><a href="#Modula3_features">Features</a>
<li><a href="#Modula3_pragmas">Pragmas</a>
</ul>
<li><a href="#remarks">Remarks</a>
<li><a href="#Modula3_remarks">Remarks</a>
</ul>
</div>
<!-- INDEX -->
@ -49,24 +46,29 @@
<p>
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
<a href="http://modula3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html#SWIG">basics</a>
of SWIG,
especially
<a href="Typemaps.html">typemaps</a>.
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="modula3_overview"></a>24.1 Overview</H2>
<H2><a name="Modula3_modula3_overview"></a>25.1 Overview</H2>
<p>
The Modula-3 support is very basic and highly experimental!
Modula-3 is a compiled language in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor to Pascal.
</p>
<p>
SWIG's Modula-3 support is currently very basic and highly experimental!
Many features are still not designed satisfyingly
and I need more discussion about the odds and ends.
Don't rely on any feature, incompatible changes are likely in the future!
The Modula-3 generator was already useful for interfacing
to the libraries
However, the Modula-3 generator was already useful for interfacing
to the libraries:
</p>
<ol>
@ -78,130 +80,34 @@ PLPlot
<li>
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/fftw/">
FFTW
</a> .
</a>
</li>
</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>24.1.1 Why not scripting ?</H3>
<H3><a name="Modula3_motivation"></a>25.1.1 Motivation</H3>
<p>
SWIG started as wrapper from the fast compiled languages C and C++
to high level scripting languages like Python.
Although scripting languages are designed
to make programming life easier
by hiding machine internals from the programmer
there are several aspects of today's scripting languages
that are unfavourable in my opinion.
Although it is possible to write Modula-3 code that performs as well as C/C++
most existing libraries are not written in Modula-3 but in C or C++, and
even libraries in other languages may provide C header files.
</p>
<p>
Besides C, C++, Cluster (a Modula derivate for Amiga computers)
I evaluated several scripting like languages in the past:
Different dialects of BASIC,
Perl, ARexx (a variant of Rexx for Amiga computers),
shell scripts.
I found them too inconsistent,
too weak in distinguishing types,
too weak in encapsulating pieces of code.
Eventually I have started several projects in Python
because of the fine syntax.
But when projects became larger
I lost the track.
I got convinced that one can not have
maintainable code in a language
that is not statically typed.
In fact the main advantages of scripting languages
e.g. matching regular expressions,
complex built-in datatypes like lists, dictionaries,
are not advantages of the language itself
but can be provided by function libraries.
</p>
<H3><a name="whymodula3"></a>24.1.2 Why Modula-3 ?</H3>
<p>
Modula-3 is a compiler language
in the tradition of Niklaus Wirth's Modula 2,
which is in turn a successor of the popular Pascal.
I have chosen Modula-3
because of its
logical syntax,
strong modularization,
the type system which is very detailed
for machine types compared to other languages.
Of course it supports all of the modern games
like exceptions, objects, garbage collection, threads.
While C++ programmers must
control three languages,
namely the preprocessor, C and ++,
Modula-3 is made in one go
and the language definition is really compact.
Fortunately Modula-3 can call C functions, but you have to write Modula-3
interfaces to them, and to make things comfortable you will also need
wrappers that convert between high-level features of Modula-3 (garbage
collecting, exceptions) and the explicit tracking of allocated memory and
exception codes used by C APIs.
</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.
SWIG converts C headers to Modula-3 interfaces for you, and using typemaps
you can pass <tt>TEXT</tt>s or open arrays, and convert error return codes
into exceptions.
</p>
<p>
Unfortunately Modula's safety and strength
requires more writing than scripting languages do.
Today if I want to safe characters
I prefer Haskell (similar to OCAML) -
it's statically typed, too.
</p>
<H3><a name="whycpp"></a>24.1.3 Why C / C++ ?</H3>
<p>
Although it is no problem to write Modula-3 programs
that performs as fast as C
most libraries are not written in Modula-3 but in C.
Fortunately the binary interface of most function libraries
can be addressed by Modula-3.
Even more fortunately even non-C libraries may provide C header files.
This is where SWIG becomes helpful.
</p>
<H3><a name="whyswig"></a>24.1.4 Why SWIG ?</H3>
<p>
The C headers and the possibility to interface to C libraries
still leaves the work for you
to write Modula-3 interfaces to them.
To make things comfortable you will also need
wrappers that convert between high-level features of Modula-3
(garbage collecting, exceptions)
and the low level of the C libraries.
</p>
<p>
SWIG converts C headers to Modula-3 interfaces for you.
You could call the C functions without loss
of efficiency but it won't be joy
because you could not pass <tt>TEXT</tt>s
or open arrays and
you would have to process error return codes
rather then exceptions.
But using some typemaps SWIG will also generate
wrappers that bring the whole Modula-3 comfort to you.
If the library API is ill designed
writing appropriate typemaps can be still time-consuming.
E.g. C programmers are very creative to work-around
@ -211,55 +117,28 @@ otherwise you lose static safety and consistency.
</p>
<p>
But you have still a problem:
C library interfaces are often ill.
They lack for certain information
because C compilers wouldn't care about.
You should integrate detailed type information
by adding <tt>typedef</tt>s and <tt>const</tt>s
and you should persuade the C library programmer
to add this information to his interface.
Only this way other language users can benefit from your work
and only this way you can easily update your interfaces
when a new library version is released.
You will realise that writing <b>good</b> SWIG interfaces
is very costly and it will only amortise
when considering evolving libraries.
</p>
<p>
Without SWIG you would probably never consider
to call C++ libraries from Modula-3.
But with SWIG this is worth a consideration.
SWIG can write C wrappers to C++ functions and object methods
that may throw exceptions.
In fact it breaks down C++ libraries to C interfaces
which can be in turn called from Modula-3.
To make it complete you can hide the C interface
with Modula-3 classes and exceptions.
Without SWIG you would probably never consider trying to call C++ libraries
from Modula-3, but with SWIG this is becomes feasible.
SWIG can generate C wrappers to C++ functions and object methods
that may throw exceptions, and then wrap these C wrappers for Module-3.
To make it complete you can then hide the C interface with Modula-3 classes and
exceptions.
</p>
<p>
Although SWIG does the best it can do
it can only serve as a one-way strategy.
That means you can use C++ libraries
with Modula-3 (even with call back functions),
but it's certainly not possible to smoothly
integrate Modula-3 code into a C / C++ project.
SWIG allows you to call C and C++ libraries from Modula-3 (even with call back
functions), but it doesn't allow you to easily integrate a Module-3 module into
a C/C++ project.
</p>
<H2><a name="conception"></a>24.2 Conception</H2>
<H2><a name="Modula3_conception"></a>25.2 Conception</H2>
<H3><a name="cinterface"></a>24.2.1 Interfaces to C libraries</H3>
<H3><a name="Modula3_cinterface"></a>25.2.1 Interfaces to C libraries</H3>
<p>
Modula-3 has an integrated support for calling C functions.
Modula-3 has integrated support for calling C functions.
This is also extensively used by the standard Modula-3 libraries
to call OS functions.
The Modula-3 part of SWIG and the corresponding SWIG library
@ -404,7 +283,7 @@ and the principal type must be renamed (<tt>%typemap</tt>).
</p>
<H3><a name="cppinterface"></a>24.2.2 Interfaces to C++ libraries</H3>
<H3><a name="Modula3_cppinterface"></a>25.2.2 Interfaces to C++ libraries</H3>
<p>
@ -417,7 +296,7 @@ with a C interface.
<p>
Here's a scheme of how the function calls to Modula-3 wrappers
a redirected to C library functions:
are redirected to C library functions:
</p>
<table summary="Modula-3 C++ library">
@ -477,13 +356,13 @@ Is it possible to sub-class C++ classes with Modula-3 code?
This issue is addressed by directors,
a feature that was experimentally added to some Language modules
like
<a href="Java.html#java_directors">Java</a> and
<a href="Python.html#directors">Python</a>.
<a href="Java.html#Java_directors">Java</a> and
<a href="Python.html#Python_directors">Python</a>.
</li>
<li>
How to manage storage with the garbage collector of Modula-3?
Support for
<a href="Customization.html#ownership">
<a href="Customization.html#Customization_ownership">
<tt>%newobject</tt> and <tt>%typemap(newfree)</tt></a>
isn't implemented, yet.
What's about resources that are managed by the garbage collector
@ -494,7 +373,7 @@ as far as I know.
<li>
How to turn C++ exceptions into Modula-3 exceptions?
There's also no support for
<a href="Customization.html#exception">
<a href="Customization.html#Customization_exception">
<tt>%exception</tt></a>, yet.
</li>
</ul>
@ -505,10 +384,10 @@ There is no C++ library I wrote a SWIG interface for,
so I'm not sure if this is possible or sensible, yet.
</p>
<H2><a name="preliminaries"></a>24.3 Preliminaries</H2>
<H2><a name="Modula3_preliminaries"></a>25.3 Preliminaries</H2>
<H3><a name="compilers"></a>24.3.1 Compilers</H3>
<H3><a name="Modula3_compilers"></a>25.3.1 Compilers</H3>
<p>
@ -522,7 +401,7 @@ For testing examples I use Critical Mass cm3.
</p>
<H3><a name="commandline"></a>24.3.2 Additional Commandline Options</H3>
<H3><a name="Modula3_commandline"></a>25.3.2 Additional Commandline Options</H3>
<p>
@ -599,10 +478,10 @@ Instead generate templates for some basic typemaps.
</tr>
</table>
<H2><a name="modula3_typemaps"></a>24.4 Modula-3 typemaps</H2>
<H2><a name="Modula3_typemaps"></a>25.4 Modula-3 typemaps</H2>
<H3><a name="inoutparam"></a>24.4.1 Inputs and outputs</H3>
<H3><a name="Modula3_inoutparam"></a>25.4.1 Inputs and outputs</H3>
<p>
@ -818,7 +697,7 @@ consist of the following parts:
</table>
<H3><a name="ordinals"></a>24.4.2 Subranges, Enumerations, Sets</H3>
<H3><a name="Modula3_ordinals"></a>25.4.2 Subranges, Enumerations, Sets</H3>
<p>
@ -870,7 +749,7 @@ that I'd like to automate.
</p>
<H3><a name="class"></a>24.4.3 Objects</H3>
<H3><a name="Modula3_class"></a>25.4.3 Objects</H3>
<p>
@ -883,7 +762,7 @@ is not really useful, yet.
</p>
<H3><a name="imports"></a>24.4.4 Imports</H3>
<H3><a name="Modula3_imports"></a>25.4.4 Imports</H3>
<p>
@ -918,7 +797,7 @@ IMPORT M3toC;
</pre></div>
<H3><a name="exceptions"></a>24.4.5 Exceptions</H3>
<H3><a name="Modula3_exceptions"></a>25.4.5 Exceptions</H3>
<p>
@ -942,7 +821,7 @@ you should declare
<tt>%typemap("m3wrapinconv:throws") blah * %{OSError.E%}</tt>.
</p>
<H3><a name="typemap_example"></a>24.4.6 Example</H3>
<H3><a name="Modula3_typemap_example"></a>25.4.6 Example</H3>
<p>
@ -989,10 +868,10 @@ where almost everything is generated by a typemap:
</pre></div>
<H2><a name="hints"></a>24.5 More hints to the generator</H2>
<H2><a name="Modula3_hints"></a>25.5 More hints to the generator</H2>
<H3><a name="features"></a>24.5.1 Features</H3>
<H3><a name="Modula3_features"></a>25.5.1 Features</H3>
<table border summary="Modula-3 features">
@ -1022,14 +901,14 @@ where almost everything is generated by a typemap:
This is necessary in the cases
where it was defined by a non-trivial C expression.
This feature is used by the
<tt>-generateconst</tt> <a href="#options">option</a>.
<tt>-generateconst</tt> <a href="#Modula3_commandline">option</a>.
In future it may be generalized to other kind of values
such as strings.
</td>
</tr>
</table>
<H3><a name="pragmas"></a>24.5.2 Pragmas</H3>
<H3><a name="Modula3_pragmas"></a>25.5.2 Pragmas</H3>
<table border summary="Modula-3 pragmas">
@ -1052,14 +931,14 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H2><a name="remarks"></a>24.6 Remarks</H2>
<H2><a name="Modula3_remarks"></a>25.6 Remarks</H2>
<ul>
<li>
The Modula-3 part of SWIG doesn't try to generate nicely formatted code.
Use <tt>m3pp</tt> to postprocess the Modula files,
it does a very good job here.
If you need to read the generated code, use <tt>m3pp</tt> to postprocess the
Modula files.
</li>
</ul>

8
Doc/Manual/Modules.html
View file

@ -13,7 +13,7 @@
<li><a href="#Modules_introduction">Modules Introduction</a>
<li><a href="#Modules_nn1">Basics</a>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to the runtime</a>
<li><a href="#Modules_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>
@ -29,7 +29,7 @@
<p>
Each invocation of SWIG requires a module name to be specified.
The module name is used to name the resulting target language extension module.
Exactly what this means and and what the name is used for
Exactly what this means and what the name is used for
depends on the target language, for example the name can define
a target language namespace or merely be a useful name for naming files or helper classes.
Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
@ -241,10 +241,10 @@ can peacefully coexist. So the type structures are separated by the
is empty. Only modules compiled with the same pair will share type information.
</p>
<H2><a name="external_run_time"></a>15.4 External access to the runtime</H2>
<H2><a name="Modules_external_run_time"></a>15.4 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
to be called. Calling these functions from a typemap is supported, since the typemap code
is embedded into the <tt>_wrap.c</tt> file, which has those declarations available. If you need

4
Doc/Manual/Mzscheme.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="MzScheme"></a>25 SWIG and MzScheme</H1>
<H1><a name="Mzscheme"></a>26 SWIG and MzScheme</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -22,7 +22,7 @@
<p>
This section contains information on SWIG's support of MzScheme.
<H2><a name="MzScheme_nn2"></a>25.1 Creating native MzScheme structures</H2>
<H2><a name="MzScheme_nn2"></a>26.1 Creating native MzScheme structures</H2>
<p>

62
Doc/Manual/Ocaml.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>26 SWIG and Ocaml</H1>
<H1><a name="Ocaml"></a>27 SWIG and Ocaml</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -80,7 +80,7 @@ If you're not familiar with the Objective Caml language, you can visit
<a href="http://www.ocaml.org/">The Ocaml Website</a>.
</p>
<H2><a name="Ocaml_nn2"></a>26.1 Preliminaries</H2>
<H2><a name="Ocaml_nn2"></a>27.1 Preliminaries</H2>
<p>
@ -99,7 +99,7 @@ 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>26.1.1 Running SWIG</H3>
<H3><a name="Ocaml_nn3"></a>27.1.1 Running SWIG</H3>
<p>
@ -122,7 +122,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
<H3><a name="Ocaml_nn4"></a>26.1.2 Compiling the code</H3>
<H3><a name="Ocaml_nn4"></a>27.1.2 Compiling the code</H3>
<p>
@ -158,7 +158,7 @@ the user more freedom with respect to custom typing.
</pre>
</div>
<H3><a name="Ocaml_nn5"></a>26.1.3 The camlp4 module</H3>
<H3><a name="Ocaml_nn5"></a>27.1.3 The camlp4 module</H3>
<p>
@ -234,7 +234,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6"></a>26.1.4 Using your module</H3>
<H3><a name="Ocaml_nn6"></a>27.1.4 Using your module</H3>
<p>
@ -248,7 +248,7 @@ When linking any ocaml bytecode with your module, use the -custom
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>26.1.5 Compilation problems and compiling with C++</H3>
<H3><a name="Ocaml_nn7"></a>27.1.5 Compilation problems and compiling with C++</H3>
<p>
@ -259,7 +259,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8"></a>26.2 The low-level Ocaml/C interface</H2>
<H2><a name="Ocaml_nn8"></a>27.2 The low-level Ocaml/C interface</H2>
<p>
@ -360,7 +360,7 @@ is that you must append them to the return list with swig_result = caml_list_a
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9"></a>26.2.1 The generated module</H3>
<H3><a name="Ocaml_nn9"></a>27.2.1 The generated module</H3>
<p>
@ -394,7 +394,7 @@ it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>26.2.2 Enums</H3>
<H3><a name="Ocaml_nn10"></a>27.2.2 Enums</H3>
<p>
@ -457,7 +457,7 @@ val x : Enum_test.c_obj = C_enum `a
</pre>
</div>
<H4><a name="Ocaml_nn11"></a>26.2.2.1 Enum typing in Ocaml</H4>
<H4><a name="Ocaml_nn11"></a>27.2.2.1 Enum typing in Ocaml</H4>
<p>
@ -470,10 +470,10 @@ 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>26.2.3 Arrays</H3>
<H3><a name="Ocaml_nn12"></a>27.2.3 Arrays</H3>
<H4><a name="Ocaml_nn13"></a>26.2.3.1 Simple types of bounded arrays</H4>
<H4><a name="Ocaml_nn13"></a>27.2.3.1 Simple types of bounded arrays</H4>
<p>
@ -494,7 +494,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn14"></a>26.2.3.2 Complex and unbounded arrays</H4>
<H4><a name="Ocaml_nn14"></a>27.2.3.2 Complex and unbounded arrays</H4>
<p>
@ -507,7 +507,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn15"></a>26.2.3.3 Using an object</H4>
<H4><a name="Ocaml_nn15"></a>27.2.3.3 Using an object</H4>
<p>
@ -521,7 +521,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required sentinel, etc.
</p>
<H4><a name="Ocaml_nn16"></a>26.2.3.4 Example typemap for a function taking float * and int</H4>
<H4><a name="Ocaml_nn16"></a>27.2.3.4 Example typemap for a function taking float * and int</H4>
<p>
@ -572,7 +572,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn17"></a>26.2.4 C++ Classes</H3>
<H3><a name="Ocaml_nn17"></a>27.2.4 C++ Classes</H3>
<p>
@ -615,7 +615,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
</p>
<H4><a name="Ocaml_nn18"></a>26.2.4.1 STL vector and string Example</H4>
<H4><a name="Ocaml_nn18"></a>27.2.4.1 STL vector and string Example</H4>
<p>
@ -695,7 +695,7 @@ baz
#
</pre></div>
<H4><a name="Ocaml_nn19"></a>26.2.4.2 C++ Class Example</H4>
<H4><a name="Ocaml_nn19"></a>27.2.4.2 C++ Class Example</H4>
<p>
@ -725,7 +725,7 @@ public:
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn20"></a>26.2.4.3 Compiling the example</H4>
<H4><a name="Ocaml_nn20"></a>27.2.4.3 Compiling the example</H4>
<div class="code"><pre>
@ -743,7 +743,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></div>
<H4><a name="Ocaml_nn21"></a>26.2.4.4 Sample Session</H4>
<H4><a name="Ocaml_nn21"></a>27.2.4.4 Sample Session</H4>
<div class="code"><pre>
@ -770,10 +770,10 @@ Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn22"></a>26.2.5 Director Classes</H3>
<H3><a name="Ocaml_nn22"></a>27.2.5 Director Classes</H3>
<H4><a name="Ocaml_nn23"></a>26.2.5.1 Director Introduction</H4>
<H4><a name="Ocaml_nn23"></a>27.2.5.1 Director Introduction</H4>
<p>
@ -800,7 +800,7 @@ class foo {
};
</pre></div>
<H4><a name="Ocaml_nn24"></a>26.2.5.2 Overriding Methods in Ocaml</H4>
<H4><a name="Ocaml_nn24"></a>27.2.5.2 Overriding Methods in Ocaml</H4>
<p>
@ -828,7 +828,7 @@ In this example, I'll examine the objective caml code involved in providing
an overloaded class. This example is contained in Examples/ocaml/shapes.
</p>
<H4><a name="Ocaml_nn25"></a>26.2.5.3 Director Usage Example</H4>
<H4><a name="Ocaml_nn25"></a>27.2.5.3 Director Usage Example</H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -887,7 +887,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn26"></a>26.2.5.4 Creating director objects</H4>
<H4><a name="Ocaml_nn26"></a>27.2.5.4 Creating director objects</H4>
<p>
@ -928,7 +928,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn27"></a>26.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<H4><a name="Ocaml_nn27"></a>27.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<p>
@ -939,7 +939,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn28"></a>26.2.5.6 <tt>directorin</tt> typemap</H4>
<H4><a name="Ocaml_nn28"></a>27.2.5.6 <tt>directorin</tt> typemap</H4>
<p>
@ -950,7 +950,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn29"></a>26.2.5.7 <tt>directorout</tt> typemap</H4>
<H4><a name="Ocaml_nn29"></a>27.2.5.7 <tt>directorout</tt> typemap</H4>
<p>
@ -961,7 +961,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn30"></a>26.2.5.8 <tt>directorargout</tt> typemap</H4>
<H4><a name="Ocaml_nn30"></a>27.2.5.8 <tt>directorargout</tt> typemap</H4>
<p>
@ -978,7 +978,7 @@ In the event that you don't specify all of the necessary values, integral
values will read zero, and struct or object returns have undefined results.
</p>
<H3><a name="Ocaml_nn31"></a>26.2.6 Exceptions</H3>
<H3><a name="Ocaml_nn31"></a>27.2.6 Exceptions</H3>
<p>

68
Doc/Manual/Octave.html
View file

@ -8,7 +8,7 @@
<body bgcolor="#ffffff">
<H1><a name="Octave"></a>27 SWIG and Octave</H1>
<H1><a name="Octave"></a>28 SWIG and Octave</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -54,21 +54,22 @@ More information can be found at <a href="http://www.octave.org">www.octave.org<
Also, there are a dozen or so examples in the Examples/octave directory, and hundreds in the test suite (Examples/test-suite and Examples/test-suite/octave).
</p>
<H2><a name="Octave_nn2"></a>27.1 Preliminaries</H2>
<H2><a name="Octave_nn2"></a>28.1 Preliminaries</H2>
<p>
The current SWIG implemention is based on Octave 2.9.12. Support for other versions (in particular the recent 3.0) has not been tested, nor has support for any OS other than Linux.
The SWIG implemention was first based on Octave 2.9.12, so this is the minimum version required. Testing has only been done on Linux.
</p>
<H2><a name="Octave_nn3"></a>27.2 Running SWIG</H2>
<H2><a name="Octave_nn3"></a>28.2 Running SWIG</H2>
<p>
Let's start with a very simple SWIG interface file:
Let's start with a very simple SWIG interface file, example.i:
</p>
<div class="code"><pre>%module example
<div class="code"><pre>
%module example
%{
#include "example.h"
%}
@ -76,20 +77,27 @@ int gcd(int x, int y);
extern double Foo; </pre></div>
<p>
To build an Octave module, run SWIG using the <tt>-octave</tt> option. The <tt>-c++</tt> option is required (for now) as Octave itself is written in C++ and thus the wrapper code must also be.
To build an Octave module when wrapping C code, run SWIG using the <tt>-octave</tt> option:
</p>
<div class="shell"><pre>$ swig -octave example.i </pre></div>
<p>
The <tt>-c++</tt> option is also required when wrapping C++ code:
</p>
<div class="shell"><pre>$ swig -octave -c++ example.i </pre></div>
<p>
This creates a C/C++ source file <tt>example_wrap.cxx</tt>. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
This creates a C++ source file <tt>example_wrap.cxx</tt>. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<p>
The swig command line has a number of options you can use, like to redirect it's output. Use <tt>swig --help</tt> to learn about these.
</p>
<H3><a name="Octave_nn5"></a>27.2.1 Compiling a dynamic module</H3>
<H3><a name="Octave_nn5"></a>28.2.1 Compiling a dynamic module</H3>
<p>
@ -116,7 +124,7 @@ $ mkoctfile example_wrap.cxx example.c
<div class="targetlang"><pre>octave:1&gt; example</pre></div>
<H3><a name="Octave_nn6"></a>27.2.2 Using your module</H3>
<H3><a name="Octave_nn6"></a>28.2.2 Using your module</H3>
<p>
@ -134,10 +142,10 @@ octave:4&gt; example.cvar.Foo=4;
octave:5&gt; example.cvar.Foo
ans = 4 </pre></div>
<H2><a name="Octave_nn7"></a>27.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Octave_nn7"></a>28.3 A tour of basic C/C++ wrapping</H2>
<H3><a name="Octave_nn8"></a>27.3.1 Modules</H3>
<H3><a name="Octave_nn8"></a>28.3.1 Modules</H3>
<p>
@ -179,7 +187,7 @@ One can also rename it by simple assignment, e.g.,
octave:1&gt; some_vars = cvar;
</pre></div>
<H3><a name="Octave_nn9"></a>27.3.2 Functions</H3>
<H3><a name="Octave_nn9"></a>28.3.2 Functions</H3>
<p>
@ -196,7 +204,7 @@ int fact(int n); </pre></div>
<div class="targetlang"><pre>octave:1&gt; example.fact(4)
24 </pre></div>
<H3><a name="Octave_nn10"></a>27.3.3 Global variables</H3>
<H3><a name="Octave_nn10"></a>28.3.3 Global variables</H3>
<p>
@ -231,7 +239,7 @@ extern double Foo;
</pre></div>
<p>
SWIG will allow the the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
SWIG will allow the reading of <tt>Foo</tt> but when a set attempt is made, an error function will be called.
</p>
<div class="targetlang"><pre>octave:1&gt; example
@ -249,7 +257,7 @@ octave:2&gt; example.PI=3.142;
octave:3&gt; example.PI
ans = 3.1420 </pre></div>
<H3><a name="Octave_nn11"></a>27.3.4 Constants and enums</H3>
<H3><a name="Octave_nn11"></a>28.3.4 Constants and enums</H3>
<p>
@ -271,7 +279,7 @@ example.SCONST="Hello World"
example.SUNDAY=0
.... </pre></div>
<H3><a name="Octave_nn12"></a>27.3.5 Pointers</H3>
<H3><a name="Octave_nn12"></a>28.3.5 Pointers</H3>
<p>
@ -318,7 +326,7 @@ octave:2&gt; f=example.fopen("not there","r");
error: value on right hand side of assignment is undefined
error: evaluating assignment expression near line 2, column 2 </pre></div>
<H3><a name="Octave_nn13"></a>27.3.6 Structures and C++ classes</H3>
<H3><a name="Octave_nn13"></a>28.3.6 Structures and C++ classes</H3>
<p>
@ -453,7 +461,7 @@ ans = 1
Depending on the ownership setting of a <tt>swig_ref</tt>, it may call C++ destructors when its reference count goes to zero. See the section on memory management below for details.
</p>
<H3><a name="Octave_nn15"></a>27.3.7 C++ inheritance</H3>
<H3><a name="Octave_nn15"></a>28.3.7 C++ inheritance</H3>
<p>
@ -462,7 +470,7 @@ This information contains the full class hierarchy. When an indexing operation (
the tree is walked to find a match in the current class as well as any of its bases. The lookup is then cached in the <tt>swig_ref</tt>.
</p>
<H3><a name="Octave_nn17"></a>27.3.8 C++ overloaded functions</H3>
<H3><a name="Octave_nn17"></a>28.3.8 C++ overloaded functions</H3>
<p>
@ -472,7 +480,7 @@ The dispatch function selects which overload to call (if any) based on the passe
<tt>typecheck</tt> typemaps are used to analyze each argument, as well as assign precedence. See the chapter on typemaps for details.
</p>
<H3><a name="Octave_nn18"></a>27.3.9 C++ operators</H3>
<H3><a name="Octave_nn18"></a>28.3.9 C++ operators</H3>
<p>
@ -572,7 +580,7 @@ On the C++ side, the default mappings are as follows:
%rename(__brace) *::operator[];
</pre></div>
<H3><a name="Octave_nn19"></a>27.3.10 Class extension with %extend</H3>
<H3><a name="Octave_nn19"></a>28.3.10 Class extension with %extend</H3>
<p>
@ -602,7 +610,7 @@ octave:3&gt; printf("%s\n",a);
octave:4&gt; a.__str()
4
</pre></div>
<H3><a name="Octave_nn20"></a>27.3.11 C++ templates</H3>
<H3><a name="Octave_nn20"></a>28.3.11 C++ templates</H3>
<p>
@ -679,14 +687,14 @@ ans =
</pre></div>
<H3><a name="Octave_nn21"></a>27.3.12 C++ Smart Pointers</H3>
<H3><a name="Octave_nn21"></a>28.3.12 C++ Smart Pointers</H3>
<p>
C++ smart pointers are fully supported as in other modules.
</p>
<H3><a name="Octave_nn22"></a>27.3.13 Directors (calling Octave from C++ code)</H3>
<H3><a name="Octave_nn22"></a>28.3.13 Directors (calling Octave from C++ code)</H3>
<p>
@ -766,14 +774,14 @@ c-side routine called
octave-side routine called
</pre></div>
<H3><a name="Octave_nn23"></a>27.3.14 Threads</H3>
<H3><a name="Octave_nn23"></a>28.3.14 Threads</H3>
<p>
The use of threads in wrapped Director code is not supported; i.e., an Octave-side implementation of a C++ class must be called from the Octave interpreter's thread. Anything fancier (apartment/queue model, whatever) is left to the user. Without anything fancier, this amounts to the limitation that Octave must drive the module... like, for example, an optimization package that calls Octave to evaluate an objective function.
</p>
<H3><a name="Octave_nn24"></a>27.3.15 Memory management</H3>
<H3><a name="Octave_nn24"></a>28.3.15 Memory management</H3>
<p>
@ -807,14 +815,14 @@ The %newobject directive may be used to control this behavior for pointers retur
In the case where one wishes for the C++ side to own an object that was created in Octave (especially a Director object), one can use the __disown() method to invert this logic. Then letting the Octave reference count go to zero will not destroy the object, but destroying the object will invalidate the Octave-side object if it still exists (and call destructors of other C++ bases in the case of multiple inheritance/<tt>subclass()</tt>'ing).
</p>
<H3><a name="Octave_nn25"></a>27.3.16 STL support</H3>
<H3><a name="Octave_nn25"></a>28.3.16 STL support</H3>
<p>
This is some skeleton support for various STL containers.
Various STL library files are provided for wrapping STL containers.
</p>
<H3><a name="Octave_nn26"></a>27.3.17 Matrix typemaps</H3>
<H3><a name="Octave_nn26"></a>28.3.17 Matrix typemaps</H3>
<p>

96
Doc/Manual/Perl5.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Perl5"></a>28 SWIG and Perl5</H1>
<H1><a name="Perl5"></a>29 SWIG and Perl5</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -87,7 +87,7 @@ later. Earlier versions are problematic and SWIG generated extensions
may not compile or run correctly.
</p>
<H2><a name="Perl5_nn2"></a>28.1 Overview</H2>
<H2><a name="Perl5_nn2"></a>29.1 Overview</H2>
<p>
@ -108,7 +108,7 @@ described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
</p>
<H2><a name="Perl5_nn3"></a>28.2 Preliminaries</H2>
<H2><a name="Perl5_nn3"></a>29.2 Preliminaries</H2>
<p>
@ -133,7 +133,7 @@ To build the module, you will need to compile the file
<tt>example_wrap.c</tt> and link it with the rest of your program.
</p>
<H3><a name="Perl5_nn4"></a>28.2.1 Getting the right header files</H3>
<H3><a name="Perl5_nn4"></a>29.2.1 Getting the right header files</H3>
<p>
@ -165,7 +165,7 @@ loaded, an easy way to find out is to run Perl itself.
</pre>
</div>
<H3><a name="Perl5_nn5"></a>28.2.2 Compiling a dynamic module</H3>
<H3><a name="Perl5_nn5"></a>29.2.2 Compiling a dynamic module</H3>
<p>
@ -198,7 +198,7 @@ the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
</p>
<H3><a name="Perl5_nn6"></a>28.2.3 Building a dynamic module with MakeMaker</H3>
<H3><a name="Perl5_nn6"></a>29.2.3 Building a dynamic module with MakeMaker</H3>
<p>
@ -232,7 +232,7 @@ the preferred approach to compilation. More information about MakeMaker can be
found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
and Randal Schwartz.</p>
<H3><a name="Perl5_nn7"></a>28.2.4 Building a static version of Perl</H3>
<H3><a name="Perl5_nn7"></a>29.2.4 Building a static version of Perl</H3>
<p>
@ -301,7 +301,7 @@ added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
</p>
<H3><a name="Perl5_nn8"></a>28.2.5 Using the module</H3>
<H3><a name="Perl5_nn8"></a>29.2.5 Using the module</H3>
<p>
@ -456,7 +456,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Perl5_nn9"></a>28.2.6 Compilation problems and compiling with C++</H3>
<H3><a name="Perl5_nn9"></a>29.2.6 Compilation problems and compiling with C++</H3>
<p>
@ -599,7 +599,7 @@ have to find the macro that conflicts and add an #undef into the .i file. Pleas
any conflicting macros you find to <a href="http://www.swig.org/mail.html">swig-user mailing list</a>.
</p>
<H3><a name="Perl5_nn10"></a>28.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Perl5_nn10"></a>29.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -626,7 +626,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H2><a name="Perl5_nn11"></a>28.3 Building Perl Extensions under Windows</H2>
<H2><a name="Perl5_nn11"></a>29.3 Building Perl Extensions under Windows</H2>
<p>
@ -637,7 +637,7 @@ section assumes you are using SWIG with Microsoft Visual C++
although the procedure may be similar with other compilers.
</p>
<H3><a name="Perl5_nn12"></a>28.3.1 Running SWIG from Developer Studio</H3>
<H3><a name="Perl5_nn12"></a>29.3.1 Running SWIG from Developer Studio</H3>
<p>
@ -700,7 +700,7 @@ print "$a\n";
</pre></div>
<H3><a name="Perl5_nn13"></a>28.3.2 Using other compilers</H3>
<H3><a name="Perl5_nn13"></a>29.3.2 Using other compilers</H3>
<p>
@ -708,7 +708,7 @@ SWIG is known to work with Cygwin and may work with other compilers on Windows.
For general hints and suggestions refer to the <a href="Windows.html#Windows">Windows</a> chapter.
</p>
<H2><a name="Perl5_nn14"></a>28.4 The low-level interface</H2>
<H2><a name="Perl5_nn14"></a>29.4 The low-level interface</H2>
<p>
@ -718,7 +718,7 @@ can be used to control your application. However, it is also used to
construct more user-friendly proxy classes as described in the next section.
</p>
<H3><a name="Perl5_nn15"></a>28.4.1 Functions</H3>
<H3><a name="Perl5_nn15"></a>29.4.1 Functions</H3>
<p>
@ -741,7 +741,7 @@ use example;
$a = &amp;example::fact(2);
</pre></div>
<H3><a name="Perl5_nn16"></a>28.4.2 Global variables</H3>
<H3><a name="Perl5_nn16"></a>29.4.2 Global variables</H3>
<p>
@ -811,7 +811,7 @@ extern char *path; // Declared later in the input
</pre>
</div>
<H3><a name="Perl5_nn17"></a>28.4.3 Constants</H3>
<H3><a name="Perl5_nn17"></a>29.4.3 Constants</H3>
<p>
@ -851,7 +851,7 @@ print example::FOO,"\n";
</pre>
</div>
<H3><a name="Perl5_nn18"></a>28.4.4 Pointers</H3>
<H3><a name="Perl5_nn18"></a>29.4.4 Pointers</H3>
<p>
@ -960,7 +960,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the
SWIG and XS, this is no longer supported.
</p>
<H3><a name="Perl5_nn19"></a>28.4.5 Structures</H3>
<H3><a name="Perl5_nn19"></a>29.4.5 Structures</H3>
<p>
@ -1094,7 +1094,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</div>
<H3><a name="Perl5_nn20"></a>28.4.6 C++ classes</H3>
<H3><a name="Perl5_nn20"></a>29.4.6 C++ classes</H3>
<p>
@ -1159,7 +1159,7 @@ provides direct access to C++ objects. A higher level interface using Perl prox
can be built using these low-level accessors. This is described shortly.
</p>
<H3><a name="Perl5_nn21"></a>28.4.7 C++ classes and type-checking</H3>
<H3><a name="Perl5_nn21"></a>29.4.7 C++ classes and type-checking</H3>
<p>
@ -1195,7 +1195,7 @@ If necessary, the type-checker also adjusts the value of the pointer (as is nece
multiple inheritance is used).
</p>
<H3><a name="Perl5_nn22"></a>28.4.8 C++ overloaded functions</H3>
<H3><a name="Perl5_nn22"></a>29.4.8 C++ overloaded functions</H3>
<p>
@ -1239,7 +1239,7 @@ example::Spam_foo_d($s,3.14);
Please refer to the "SWIG Basics" chapter for more information.
</p>
<H3><a name="Perl5_nn23"></a>28.4.9 Operators</H3>
<H3><a name="Perl5_nn23"></a>29.4.9 Operators</H3>
<p>
@ -1266,7 +1266,7 @@ The following C++ operators are currently supported by the Perl module:
<li>operator or </li>
</ul>
<H3><a name="Perl5_nn24"></a>28.4.10 Modules and packages</H3>
<H3><a name="Perl5_nn24"></a>29.4.10 Modules and packages</H3>
<p>
@ -1361,7 +1361,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></div>
-->
<H2><a name="Perl5_nn25"></a>28.5 Input and output parameters</H2>
<H2><a name="Perl5_nn25"></a>29.5 Input and output parameters</H2>
<p>
@ -1580,7 +1580,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
</p>
<H2><a name="Perl5_nn26"></a>28.6 Exception handling</H2>
<H2><a name="Perl5_nn26"></a>29.6 Exception handling</H2>
<p>
@ -1745,7 +1745,7 @@ This is still supported, but it is deprecated. The newer <tt>%exception</tt> di
functionality, but it has additional capabilities that make it more powerful.
</p>
<H2><a name="Perl5_nn27"></a>28.7 Remapping datatypes with typemaps</H2>
<H2><a name="Perl5_nn27"></a>29.7 Remapping datatypes with typemaps</H2>
<p>
@ -1762,7 +1762,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Perl interface.
</p>
<H3><a name="Perl5_nn28"></a>28.7.1 A simple typemap example</H3>
<H3><a name="Perl5_nn28"></a>29.7.1 A simple typemap example</H3>
<p>
@ -1866,7 +1866,7 @@ example::count("e","Hello World");
</div>
<H3><a name="Perl5_nn29"></a>28.7.2 Perl5 typemaps</H3>
<H3><a name="Perl5_nn29"></a>29.7.2 Perl5 typemaps</H3>
<p>
@ -1971,7 +1971,7 @@ Return of C++ member data (all languages).
Check value of input parameter.
</div>
<H3><a name="Perl5_nn30"></a>28.7.3 Typemap variables</H3>
<H3><a name="Perl5_nn30"></a>29.7.3 Typemap variables</H3>
<p>
@ -2042,7 +2042,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</div>
<H3><a name="Perl5_nn31"></a>28.7.4 Useful functions</H3>
<H3><a name="Perl5_nn31"></a>29.7.4 Useful functions</H3>
<p>
@ -2111,7 +2111,7 @@ int sv_isa(SV *, char *0;
</div>
<H2><a name="Perl5_nn32"></a>28.8 Typemap Examples</H2>
<H2><a name="Perl5_nn32"></a>29.8 Typemap Examples</H2>
<p>
@ -2120,7 +2120,7 @@ might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Perl5_nn33"></a>28.8.1 Converting a Perl5 array to a char **</H3>
<H3><a name="Perl5_nn33"></a>29.8.1 Converting a Perl5 array to a char **</H3>
<p>
@ -2212,7 +2212,7 @@ print @$b,"\n"; # Print it out
</pre></div>
<H3><a name="Perl5_nn34"></a>28.8.2 Return values</H3>
<H3><a name="Perl5_nn34"></a>29.8.2 Return values</H3>
<p>
@ -2241,7 +2241,7 @@ can be done using the <tt>EXTEND()</tt> macro as in :
}
</pre></div>
<H3><a name="Perl5_nn35"></a>28.8.3 Returning values from arguments</H3>
<H3><a name="Perl5_nn35"></a>29.8.3 Returning values from arguments</H3>
<p>
@ -2295,7 +2295,7 @@ print "multout(7,13) = @r\n";
($x,$y) = multout(7,13);
</pre></div>
<H3><a name="Perl5_nn36"></a>28.8.4 Accessing array structure members</H3>
<H3><a name="Perl5_nn36"></a>29.8.4 Accessing array structure members</H3>
<p>
@ -2358,7 +2358,7 @@ the "in" typemap in the previous section would be used to convert an
to copy the converted array into a C data structure.
</p>
<H3><a name="Perl5_nn37"></a>28.8.5 Turning Perl references into C pointers</H3>
<H3><a name="Perl5_nn37"></a>29.8.5 Turning Perl references into C pointers</H3>
<p>
@ -2423,7 +2423,7 @@ print "$c\n";
</pre></div>
<H3><a name="Perl5_nn38"></a>28.8.6 Pointer handling</H3>
<H3><a name="Perl5_nn38"></a>29.8.6 Pointer handling</H3>
<p>
@ -2502,7 +2502,7 @@ For example:
</pre>
</div>
<H2><a name="Perl5_nn39"></a>28.9 Proxy classes</H2>
<H2><a name="Perl5_nn39"></a>29.9 Proxy classes</H2>
<p>
@ -2518,7 +2518,7 @@ to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
<H3><a name="Perl5_nn40"></a>28.9.1 Preliminaries</H3>
<H3><a name="Perl5_nn40"></a>29.9.1 Preliminaries</H3>
<p>
@ -2540,7 +2540,7 @@ SWIG creates a collection of high-level Perl wrappers. In your scripts, you wil
high level wrappers. The wrappers, in turn, interact with the low-level procedural module.
</p>
<H3><a name="Perl5_nn41"></a>28.9.2 Structure and class wrappers</H3>
<H3><a name="Perl5_nn41"></a>29.9.2 Structure and class wrappers</H3>
<p>
@ -2666,7 +2666,7 @@ $v-&gt;DESTROY();
</pre></div>
<H3><a name="Perl5_nn42"></a>28.9.3 Object Ownership</H3>
<H3><a name="Perl5_nn42"></a>29.9.3 Object Ownership</H3>
<p>
@ -2753,7 +2753,7 @@ counting, garbage collection, or advanced features one might find in
sophisticated languages.
</p>
<H3><a name="Perl5_nn43"></a>28.9.4 Nested Objects</H3>
<H3><a name="Perl5_nn43"></a>29.9.4 Nested Objects</H3>
<p>
@ -2806,7 +2806,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></div>
<H3><a name="Perl5_nn44"></a>28.9.5 Proxy Functions</H3>
<H3><a name="Perl5_nn44"></a>29.9.5 Proxy Functions</H3>
<p>
@ -2840,7 +2840,7 @@ This function replaces the original function, but operates in an
identical manner.
</p>
<H3><a name="Perl5_nn45"></a>28.9.6 Inheritance</H3>
<H3><a name="Perl5_nn45"></a>29.9.6 Inheritance</H3>
<p>
@ -2916,12 +2916,12 @@ particular, inheritance of data members is extremely tricky (and I'm
not even sure if it really works).
</p>
<H3><a name="Perl5_nn46"></a>28.9.7 Modifying the proxy methods</H3>
<H3><a name="Perl5_nn46"></a>29.9.7 Modifying the proxy methods</H3>
<p>
It is possible to override the SWIG generated proxy/shadow methods, using <tt>%feature("shadow")</tt>.
It works like all the other <a href="Customization.html#features">%feature directives</a>.
It works like all the other <a href="Customization.html#Customization_features">%feature directives</a>.
Here is a simple example showing how to add some Perl debug code to the constructor:
</p>
@ -2944,7 +2944,7 @@ public:
};
</pre></div>
<H2><a name="Perl5_nn47"></a>28.10 Adding additional Perl code</H2>
<H2><a name="Perl5_nn47"></a>29.10 Adding additional Perl code</H2>
<p>

56
Doc/Manual/Php.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>29 SWIG and PHP</H1>
<H1><a name="Php"></a>30 SWIG and PHP</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -75,7 +75,7 @@ your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1"></a>29.1 Generating PHP Extensions</H2>
<H2><a name="Php_nn1"></a>30.1 Generating PHP Extensions</H2>
<p>
@ -122,7 +122,7 @@ and it doesn't play nicely with package system. We don't recommend
this approach, or provide explicit support for it.
</p>
<H3><a name="Php_nn1_1"></a>29.1.1 Building a loadable extension</H3>
<H3><a name="Php_nn1_1"></a>30.1.1 Building a loadable extension</H3>
<p>
@ -137,7 +137,7 @@ least work for Linux though):
gcc -shared example_wrap.o -o example.so
</pre></div>
<H3><a name="Php_nn1_3"></a>29.1.2 Using PHP Extensions</H3>
<H3><a name="Php_nn1_3"></a>30.1.2 Using PHP Extensions</H3>
<p>
@ -168,7 +168,7 @@ attempts to do the <tt>dl()</tt> call for you:
include("example.php");
</pre></div>
<H2><a name="Php_nn2"></a>29.2 Basic PHP interface</H2>
<H2><a name="Php_nn2"></a>30.2 Basic PHP interface</H2>
<p>
@ -178,7 +178,7 @@ possible for names of symbols in one extension module to clash with
other symbols unless care is taken to <tt>%rename</tt> them.
</p>
<H3><a name="Php_nn2_1"></a>29.2.1 Constants</H3>
<H3><a name="Php_nn2_1"></a>30.2.1 Constants</H3>
<p>
@ -303,7 +303,7 @@ both point to the same value, without the case test taking place. (
Apologies, this paragraph needs rewriting to make some sense. )
</p>
<H3><a name="Php_nn2_2"></a>29.2.2 Global Variables</H3>
<H3><a name="Php_nn2_2"></a>30.2.2 Global Variables</H3>
<p>
@ -352,7 +352,7 @@ undefined.
At this time SWIG does not support custom accessor methods.
</p>
<H3><a name="Php_nn2_3"></a>29.2.3 Functions</H3>
<H3><a name="Php_nn2_3"></a>30.2.3 Functions</H3>
<p>
@ -405,7 +405,7 @@ print $s; # The value of $s was not changed.
-->
<H3><a name="Php_nn2_4"></a>29.2.4 Overloading</H3>
<H3><a name="Php_nn2_4"></a>30.2.4 Overloading</H3>
<p>
@ -413,7 +413,7 @@ Although PHP does not support overloading functions natively, swig
will generate dispatch functions which will use <tt>%typecheck</tt>
typemaps to allow overloading. This dispatch function's operation and
precedence is described in <a
href="TypemapsSWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
Overloaded Functions and Methods</a>.
</p>
@ -461,7 +461,7 @@ taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5"></a>29.2.5 Pointers and References</H3>
<H3><a name="Php_nn2_5"></a>30.2.5 Pointers and References</H3>
<p>
@ -593,7 +593,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing
variable, or assigning <tt>NULL</tt> to a variable.
</p>
<H3><a name="Php_nn2_6"></a>29.2.6 Structures and C++ classes</H3>
<H3><a name="Php_nn2_6"></a>30.2.6 Structures and C++ classes</H3>
<p>
@ -652,7 +652,7 @@ Would be used in the following way from PHP5:
Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
</p>
<H4><a name="Php_nn2_6_1"></a>29.2.6.1 Using <tt>-noproxy</tt></H4>
<H4><a name="Php_nn2_6_1"></a>30.2.6.1 Using <tt>-noproxy</tt></H4>
<p>
@ -678,7 +678,7 @@ Complex_im_set($obj,$d);
Complex_im_get($obj);
</pre></div>
<H4><a name="Php_nn2_6_2"></a>29.2.6.2 Constructors and Destructors</H4>
<H4><a name="Php_nn2_6_2"></a>30.2.6.2 Constructors and Destructors</H4>
<p>
@ -719,7 +719,7 @@ the programmer can either reassign the variable or call
<tt>unset($v)</tt>
</p>
<H4><a name="Php_nn2_6_3"></a>29.2.6.3 Static Member Variables</H4>
<H4><a name="Php_nn2_6_3"></a>30.2.6.3 Static Member Variables</H4>
<p>
@ -762,7 +762,7 @@ Ko::threats(10);
echo "There has now been " . Ko::threats() . " threats\n";
</pre></div>
<H4><a name="Php_nn2_6_4"></a>29.2.6.4 Static Member Functions</H4>
<H4><a name="Php_nn2_6_4"></a>30.2.6.4 Static Member Functions</H4>
<p>
@ -784,7 +784,7 @@ Ko::threats();
</pre></div>
<H3><a name="Php_nn2_7"></a>29.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<H3><a name="Php_nn2_7"></a>30.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<p>
@ -857,7 +857,7 @@ either <tt>%init</tt> or <tt>%minit</tt>.
<p>
To insert code into the <tt>PHP_MSHUTDOWN_FUNCTION</tt>, one can use
either <tt>%init</tt> or <tt>%minit</tt>.
either <tt>%shutdown</tt> or <tt>%mshutdown</tt>.
</p>
<div class="code"><pre>
@ -868,11 +868,11 @@ either <tt>%init</tt> or <tt>%minit</tt>.
</pre></div>
<p>
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements insert code
into the request init and shutdown code respectively.
The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but insert code
into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively.
</p>
<H2><a name="Php_nn3"></a>29.3 Cross language polymorphism</H2>
<H2><a name="Php_nn3"></a>30.3 Cross language polymorphism</H2>
<p>
@ -907,7 +907,7 @@ wrapper functions takes care of all the cross-language method routing
transparently.
</p>
<H3><a name="Php_nn3_1"></a>29.3.1 Enabling directors</H3>
<H3><a name="Php_nn3_1"></a>30.3.1 Enabling directors</H3>
<p>
@ -999,7 +999,7 @@ class MyFoo extends Foo {
</div>
<H3><a name="Php_nn3_2"></a>29.3.2 Director classes</H3>
<H3><a name="Php_nn3_2"></a>30.3.2 Director classes</H3>
@ -1079,7 +1079,7 @@ so there is no need for the extra overhead involved with routing the
calls through PHP.
</p>
<H3><a name="Php_nn3_3"></a>29.3.3 Ownership and object destruction</H3>
<H3><a name="Php_nn3_3"></a>30.3.3 Ownership and object destruction</H3>
<p>
@ -1135,7 +1135,7 @@ In this example, we are assuming that FooContainer will take care of
deleting all the Foo pointers it contains at some point.
</p>
<H3><a name="Php_nn3_4"></a>29.3.4 Exception unrolling</H3>
<H3><a name="Php_nn3_4"></a>30.3.4 Exception unrolling</H3>
<p>
@ -1194,7 +1194,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception
as soon as the C wrapper function returns.
</p>
<H3><a name="Php_nn3_5"></a>29.3.5 Overhead and code bloat</H3>
<H3><a name="Php_nn3_5"></a>30.3.5 Overhead and code bloat</H3>
<p>
@ -1227,7 +1227,7 @@ optimized by selectively enabling director methods (using the %feature
directive) for only those methods that are likely to be extended in PHP.
</p>
<H3><a name="Php_nn3_6"></a>29.3.6 Typemaps</H3>
<H3><a name="Php_nn3_6"></a>30.3.6 Typemaps</H3>
<p>
@ -1241,7 +1241,7 @@ need to be supported.
</p>
<H3><a name="Php_nn3_7"></a>29.3.7 Miscellaneous</H3>
<H3><a name="Php_nn3_7"></a>30.3.7 Miscellaneous</H3>
<p> Director typemaps for STL classes are mostly in place, and hence you

26
Doc/Manual/Pike.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>30 SWIG and Pike</H1>
<H1><a name="Pike"></a>31 SWIG and Pike</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -46,10 +46,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2"></a>30.1 Preliminaries</H2>
<H2><a name="Pike_nn2"></a>31.1 Preliminaries</H2>
<H3><a name="Pike_nn3"></a>30.1.1 Running SWIG</H3>
<H3><a name="Pike_nn3"></a>31.1.1 Running SWIG</H3>
<p>
@ -94,7 +94,7 @@ can use the <tt>-o</tt> option:
<div class="code">
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</div>
<H3><a name="Pike_nn4"></a>30.1.2 Getting the right header files</H3>
<H3><a name="Pike_nn4"></a>31.1.2 Getting the right header files</H3>
<p>
@ -114,7 +114,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5"></a>30.1.3 Using your module</H3>
<H3><a name="Pike_nn5"></a>31.1.3 Using your module</H3>
<p>
@ -129,10 +129,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
(1) Result: 24
</pre></div>
<H2><a name="Pike_nn6"></a>30.2 Basic C/C++ Mapping</H2>
<H2><a name="Pike_nn6"></a>31.2 Basic C/C++ Mapping</H2>
<H3><a name="Pike_nn7"></a>30.2.1 Modules</H3>
<H3><a name="Pike_nn7"></a>31.2.1 Modules</H3>
<p>
@ -143,7 +143,7 @@ concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
</p>
<H3><a name="Pike_nn8"></a>30.2.2 Functions</H3>
<H3><a name="Pike_nn8"></a>31.2.2 Functions</H3>
<p>
@ -168,11 +168,11 @@ exactly as you'd expect it to:
(1) Result: 24
</pre></div>
<H3><a name="Pike_nn9"></a>30.2.3 Global variables</H3>
<H3><a name="Pike_nn9"></a>31.2.3 Global variables</H3>
<p>
Global variables are currently wrapped as a pair of of functions, one to get
Global variables are currently wrapped as a pair of functions, one to get
the current value of the variable and another to set it. For example, the
declaration
</p>
@ -197,7 +197,7 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(3) Result: 3.141590
</pre></div>
<H3><a name="Pike_nn10"></a>30.2.4 Constants and enumerated types</H3>
<H3><a name="Pike_nn10"></a>31.2.4 Constants and enumerated types</H3>
<p>
@ -205,7 +205,7 @@ Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
</p>
<H3><a name="Pike_nn11"></a>30.2.5 Constructors and Destructors</H3>
<H3><a name="Pike_nn11"></a>31.2.5 Constructors and Destructors</H3>
<p>
@ -213,7 +213,7 @@ 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>30.2.6 Static Members</H3>
<H3><a name="Pike_nn12"></a>31.2.6 Static Members</H3>
<p>

100
Doc/Manual/Preface.html
View file

@ -11,13 +11,12 @@
<div class="sectiontoc">
<ul>
<li><a href="#Preface_nn2">Introduction</a>
<li><a href="#Preface_nn3">Special Introduction for Version 1.3</a>
<li><a href="#Preface_nn4">SWIG Versions</a>
<li><a href="#Preface_nn5">SWIG resources</a>
<li><a href="#Preface_nn6">Prerequisites</a>
<li><a href="#Preface_nn7">Organization of this manual</a>
<li><a href="#Preface_nn8">How to avoid reading the manual</a>
<li><a href="#Preface_nn9">Backwards Compatibility</a>
<li><a href="#Preface_nn9">Backwards compatibility</a>
<li><a href="#Preface_nn10">Credits</a>
<li><a href="#Preface_nn11">Bug reports</a>
</ul>
@ -49,34 +48,22 @@ has since evolved into a general purpose tool that is used in a wide
variety of applications--in fact almost anything where C/C++ programming
is involved.
<H2><a name="Preface_nn3"></a>1.2 Special Introduction for Version 1.3</H2>
<H2><a name="Preface_nn4"></a>1.2 SWIG Versions</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
system. Today, nearly a dozen developers are working to create
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.
In the late 1990's, the most stable version of SWIG was release
1.1p5. Versions 1.3.x were officially development versions and these were released
over a period of 10 years starting from the year 2000. The final version in the 1.3.x
series was 1.3.40, but in truth the 1.3.x series had been stable for many years.
An official stable version was released along with the decision to make SWIG
license changes and this gave rise to version 2.0.0 in 2010. The license was clarified
so that the code that SWIG generated could be distributed
under license terms of the user's choice/requirements and at the same time the SWIG
source was placed under the GNU General Public License version 3.
</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
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>
<H2><a name="Preface_nn5"></a>1.3 SWIG resources</H2>
<p>
@ -106,7 +93,7 @@ SWIG along with information about beta releases and future work.
</p>
<p>
SVN access to the latest version of SWIG is also available. More information
Subversion access to the latest version of SWIG is also available. More information
about this can be obtained at:
</p>
@ -115,7 +102,7 @@ about this can be obtained at:
</pre></div>
<H2><a name="Preface_nn6"></a>1.5 Prerequisites</H2>
<H2><a name="Preface_nn6"></a>1.4 Prerequisites</H2>
<p>
@ -132,7 +119,7 @@ writing a normal C program.
</p>
<p>
Recent SWIG releases have become significantly more capable in
Over time SWIG releases have become significantly more capable in
their C++ handling--especially support for advanced features like
namespaces, overloaded operators, and templates. Whenever possible,
this manual tries to cover the technicalities of this interface.
@ -140,7 +127,7 @@ However, this isn't meant to be a tutorial on C++ programming. For many
of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program
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>
<H2><a name="Preface_nn7"></a>1.5 Organization of this manual</H2>
<p>
@ -149,11 +136,10 @@ provide an overview of its capabilities. The remaining chapters are
devoted to specific SWIG language modules and are self
contained. Thus, if you are using SWIG to build Python interfaces, you
can 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.
to know.
</p>
<H2><a name="Preface_nn8"></a>1.7 How to avoid reading the manual</H2>
<H2><a name="Preface_nn8"></a>1.6 How to avoid reading the manual</H2>
<p>
@ -165,24 +151,19 @@ 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>
<H2><a name="Preface_nn9"></a>1.7 Backwards compatibility</H2>
<p>
If you are a previous user of SWIG, don't expect recent versions of
SWIG to provide backwards compatibility. In fact, backwards
compatibility issues may arise even between successive 1.3.x releases.
Although these incompatibilities are regrettable, SWIG-1.3 is an active
development project. The primary goal of this effort is to make SWIG
If you are a previous user of SWIG, don't expect
SWIG to provide complete backwards compatibility.
Although the developers strive to the utmost to keep backwards compatibility,
this isn't always possible as the
primary goal over time is to make SWIG
better---a process that would simply be impossible if the developers
are constantly bogged down with backwards compatibility issues.
</p>
<p>
On a positive note, a few incompatibilities are a small price to pay
for the large number of new features that have been
added---namespaces, templates, smart pointers, overloaded methods,
operators, and more.
Potential incompatibilities are clearly marked in the detailed release notes
(CHANGES files).
</p>
@ -206,33 +187,20 @@ Note: The version symbol is not defined in the generated SWIG
wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
</p>
<H2><a name="Preface_nn10"></a>1.9 Credits</H2>
<H2><a name="Preface_nn10"></a>1.8 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, John Lenz, and Surendra Singhi.
contributions of many people working in their spare time.
If you have benefitted from using SWIG, please consider
<a href="http://www.swig.org/donate.html">Donating to SWIG</a> to keep development going.
There have been a large varied number of people
who have made contributions at all levels over time. Contributors
are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
</p>
<p>
Historically, the following people contributed to early versions of SWIG.
Peter Lomdahl, Brad Holian, Shujia Zhou, Niels Jensen, and Tim Germann
at Los Alamos National Laboratory were the first users. Patrick
Tullmann at the University of Utah suggested the idea of automatic
documentation generation. John Schmidt and Kurtis Bleeker at the
University of Utah tested out the early versions. Chris Johnson
supported SWIG's developed at the University of Utah. John Buckman,
Larry Virden, and Tom Schwaller provided valuable input on the first
releases and improving the portability of SWIG. David Fletcher and
Gary Holt have provided a great deal of input on improving SWIG's
Perl5 implementation. Kevin Butler contributed the first Windows NT
port.
<H2><a name="Preface_nn11"></a>1.10 Bug reports</H2>
<H2><a name="Preface_nn11"></a>1.9 Bug reports</H2>
<p>

6
Doc/Manual/Preprocessor.html
View file

@ -81,7 +81,7 @@ Such information generally includes type declarations (e.g., <tt>typedef</tt>) a
C++ classes that might be used as base-classes for class declarations in the interface.
The use of <tt>%import</tt> is also important when SWIG is used to generate
extensions as a collection of related modules. This is an advanced topic and is described
in later in the <a href="Modules.html">Working with Modules</a> chapter.
in later in the <a href="Modules.html#Modules">Working with Modules</a> chapter.
</p>
<P>
@ -102,7 +102,7 @@ by SWIG when it is parsing the interface:
<div class="code"><pre>
SWIG Always defined when SWIG is processing a file
SWIGIMPORTED Defined when SWIG is importing a file with <tt>%import</tt>
SWIG_VERSION Hexadecimal number containing SWIG version,
SWIG_VERSION Hexadecimal (binary-coded decimal) number containing SWIG version,
such as 0x010311 (corresponding to SWIG-1.3.11).
SWIGALLEGROCL Defined when using Allegro CL
@ -377,7 +377,7 @@ SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the
<p>
<a href="Typemaps.html">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
<a href="Typemaps.html#Typemaps">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
but the delimiters are not actually generated into the code.
The effect is then similar to using "" or %{ %} delimiters but the code <b>is</b> run through the preprocessor. For example:
</p>

181
Doc/Manual/Python.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Python"></a>31 SWIG and Python</H1>
<H1><a name="Python"></a>32 SWIG and Python</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -128,7 +128,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG
Basics</a>" chapter.
</p>
<H2><a name="Python_nn2"></a>31.1 Overview</H2>
<H2><a name="Python_nn2"></a>32.1 Overview</H2>
<p>
@ -155,10 +155,10 @@ described followed by a discussion of low-level implementation
details.
</p>
<H2><a name="Python_nn3"></a>31.2 Preliminaries</H2>
<H2><a name="Python_nn3"></a>32.2 Preliminaries</H2>
<H3><a name="Python_nn4"></a>31.2.1 Running SWIG</H3>
<H3><a name="Python_nn4"></a>32.2.1 Running SWIG</H3>
<p>
@ -256,7 +256,7 @@ The following sections have further practical examples and details on
how you might go about compiling and using the generated files.
</p>
<H3><a name="Python_nn6"></a>31.2.2 Using distutils</H3>
<H3><a name="Python_nn6"></a>32.2.2 Using distutils</H3>
<p>
@ -348,7 +348,7 @@ This same approach works on all platforms if the appropriate compiler is install
can even build extensions to the standard Windows Python using MingGW)
</p>
<H3><a name="Python_nn7"></a>31.2.3 Hand compiling a dynamic module</H3>
<H3><a name="Python_nn7"></a>32.2.3 Hand compiling a dynamic module</H3>
<p>
@ -396,7 +396,7 @@ module actually consists of two files; <tt>socket.py</tt> and
</p>
<H3><a name="Python_nn8"></a>31.2.4 Static linking</H3>
<H3><a name="Python_nn8"></a>32.2.4 Static linking</H3>
<p>
@ -475,7 +475,7 @@ If using static linking, you might want to rely on a different approach
(perhaps using distutils).
</p>
<H3><a name="Python_nn9"></a>31.2.5 Using your module</H3>
<H3><a name="Python_nn9"></a>32.2.5 Using your module</H3>
<p>
@ -632,7 +632,7 @@ system configuration (this requires root access and you will need to
read the man pages).
</p>
<H3><a name="Python_nn10"></a>31.2.6 Compilation of C++ extensions</H3>
<H3><a name="Python_nn10"></a>32.2.6 Compilation of C++ extensions</H3>
<p>
@ -724,7 +724,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Python_nn11"></a>31.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Python_nn11"></a>32.2.7 Compiling for 64-bit platforms</H3>
<p>
@ -761,7 +761,7 @@ and -m64 allow you to choose the desired binary format for your python
extension.
</p>
<H3><a name="Python_nn12"></a>31.2.8 Building Python Extensions under Windows</H3>
<H3><a name="Python_nn12"></a>32.2.8 Building Python Extensions under Windows</H3>
<p>
@ -870,7 +870,7 @@ SWIG Wiki</a>.
</p>
<H2><a name="Python_nn13"></a>31.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Python_nn13"></a>32.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -879,7 +879,7 @@ to your C/C++ code. Functions are wrapped as functions, classes are wrapped as
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Python_nn14"></a>31.3.1 Modules</H3>
<H3><a name="Python_nn14"></a>32.3.1 Modules</H3>
<p>
@ -892,7 +892,7 @@ module name, make sure you don't use the same name as a built-in
Python command or standard module name.
</p>
<H3><a name="Python_nn15"></a>31.3.2 Functions</H3>
<H3><a name="Python_nn15"></a>32.3.2 Functions</H3>
<p>
@ -916,7 +916,7 @@ like you think it does:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn16"></a>31.3.3 Global variables</H3>
<H3><a name="Python_nn16"></a>32.3.3 Global variables</H3>
<p>
@ -1054,7 +1054,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.
</p>
<H3><a name="Python_nn17"></a>31.3.4 Constants and enums</H3>
<H3><a name="Python_nn17"></a>32.3.4 Constants and enums</H3>
<p>
@ -1094,7 +1094,7 @@ other object. Unfortunately, there is no easy way for SWIG to
generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Python_nn18"></a>31.3.5 Pointers</H3>
<H3><a name="Python_nn18"></a>32.3.5 Pointers</H3>
<p>
@ -1235,7 +1235,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Python_nn19"></a>31.3.6 Structures</H3>
<H3><a name="Python_nn19"></a>32.3.6 Structures</H3>
<p>
@ -1282,7 +1282,7 @@ something like this:
<p>
This object is actually a Python instance that has been wrapped around a pointer to the low-level
C structure. This instance doesn't actually do anything--it just serves as a proxy.
The pointer to the C object can be found in the the <tt>.this</tt>
The pointer to the C object can be found in the <tt>.this</tt>
attribute. For example:
</p>
@ -1424,7 +1424,7 @@ everything works just like you would expect. For example:
</pre>
</div>
<H3><a name="Python_nn20"></a>31.3.7 C++ classes</H3>
<H3><a name="Python_nn20"></a>32.3.7 C++ classes</H3>
<p>
@ -1513,7 +1513,7 @@ they are accessed through <tt>cvar</tt> like this:
</pre>
</div>
<H3><a name="Python_nn21"></a>31.3.8 C++ inheritance</H3>
<H3><a name="Python_nn21"></a>32.3.8 C++ inheritance</H3>
<p>
@ -1568,7 +1568,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Python_nn22"></a>31.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Python_nn22"></a>32.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1629,7 +1629,7 @@ treated as a returning value, and it will follow the same
allocation/deallocation process.
</p>
<H3><a name="Python_nn23"></a>31.3.10 C++ overloaded functions</H3>
<H3><a name="Python_nn23"></a>32.3.10 C++ overloaded functions</H3>
<p>
@ -1752,7 +1752,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Python_nn24"></a>31.3.11 C++ operators</H3>
<H3><a name="Python_nn24"></a>32.3.11 C++ operators</H3>
<p>
@ -1841,7 +1841,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance
overloaded assignment operators don't map to Python semantics and will be ignored.
</p>
<H3><a name="Python_nn25"></a>31.3.12 C++ namespaces</H3>
<H3><a name="Python_nn25"></a>32.3.12 C++ namespaces</H3>
<p>
@ -1908,7 +1908,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Python_nn26"></a>31.3.13 C++ templates</H3>
<H3><a name="Python_nn26"></a>32.3.13 C++ templates</H3>
<p>
@ -1962,7 +1962,7 @@ Some more complicated
examples will appear later.
</p>
<H3><a name="Python_nn27"></a>31.3.14 C++ Smart Pointers</H3>
<H3><a name="Python_nn27"></a>32.3.14 C++ Smart Pointers</H3>
<p>
@ -2047,7 +2047,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</div>
<H3><a name="Python_nn27a"></a>31.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<H3><a name="Python_nn27a"></a>32.3.15 C++ Reference Counted Objects (ref/unref)</H3>
<p>
@ -2124,8 +2124,8 @@ Object 'RCObj', which implements the ref/unref idiom.
<p>
To tell SWIG that 'RCObj' and all its derived classes are reference
counted objects, you use the "ref" and "unref" features, or
<tt>%ref</tt> and <tt>%unref</tt> directives (since 1.3.28). For example:
counted objects, you use the "ref" and "unref" features.
For example:
</p>
@ -2143,25 +2143,6 @@ counted objects, you use the "ref" and "unref" features, or
</pre>
</div>
or, using the directive form:
<div class="code">
<pre>
%module example
...
%ref RCObj "$this-&gt;ref();"
%unref RCObj "$this-&gt;unref();"
%include "rcobj.h"
%include "A.h"
...
</pre>
</div>
<p>
where the code passed to the "ref" and "unref" features will be
executed as needed whenever a new object is passed to python, or when
@ -2209,7 +2190,7 @@ python releases the proxy instance.
</p>
<H2><a name="Python_nn28"></a>31.4 Further details on the Python class interface</H2>
<H2><a name="Python_nn28"></a>32.4 Further details on the Python class interface</H2>
<p>
@ -2222,7 +2203,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Python_nn29"></a>31.4.1 Proxy classes</H3>
<H3><a name="Python_nn29"></a>32.4.1 Proxy classes</H3>
<p>
@ -2311,7 +2292,7 @@ you can attach new Python methods to the class and you can even inherit from it
by Python built-in types until Python 2.2).
</p>
<H3><a name="Python_nn30"></a>31.4.2 Memory management</H3>
<H3><a name="Python_nn30"></a>32.4.2 Memory management</H3>
<p>
@ -2503,7 +2484,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
</p>
<H3><a name="Python_nn31"></a>31.4.3 Python 2.2 and classic classes</H3>
<H3><a name="Python_nn31"></a>32.4.3 Python 2.2 and classic classes</H3>
<p>
@ -2513,7 +2494,7 @@ in Python-2.2, an entirely new type of class system was introduced.
This new-style class system offers many enhancements including static
member functions, properties (managed attributes), and class methods.
Details about all of these changes can be found on <a
href="//www.python.org">www.python.org</a> and is not repeated here.
href="http://www.python.org">www.python.org</a> and is not repeated here.
</p>
<p>
@ -2540,7 +2521,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global
function or through an instance (see the earlier section).
</p>
<H2><a name="Python_directors"></a>31.5 Cross language polymorphism</H2>
<H2><a name="Python_directors"></a>32.5 Cross language polymorphism</H2>
<p>
@ -2574,7 +2555,7 @@ proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
</p>
<H3><a name="Python_nn33"></a>31.5.1 Enabling directors</H3>
<H3><a name="Python_nn33"></a>32.5.1 Enabling directors</H3>
<p>
@ -2667,7 +2648,7 @@ class MyFoo(mymodule.Foo):
</div>
<H3><a name="Python_nn34"></a>31.5.2 Director classes</H3>
<H3><a name="Python_nn34"></a>32.5.2 Director classes</H3>
@ -2749,7 +2730,7 @@ so there is no need for the extra overhead involved with routing the
calls through Python.
</p>
<H3><a name="Python_nn35"></a>31.5.3 Ownership and object destruction</H3>
<H3><a name="Python_nn35"></a>32.5.3 Ownership and object destruction</H3>
<p>
@ -2801,12 +2782,12 @@ public:
<div class="targetlang">
<pre>
&gt;&gt;&gt; c = FooContainer()
&gt;&gt;&gt; a = Foo().__disown()__
&gt;&gt;&gt; a = Foo().__disown__()
&gt;&gt;&gt; c.addFoo(a)
&gt;&gt;&gt; b = Foo()
&gt;&gt;&gt; b = b.__disown()__
&gt;&gt;&gt; b = b.__disown__()
&gt;&gt;&gt; c.addFoo(b)
&gt;&gt;&gt; c.addFoo(Foo().__disown()__)
&gt;&gt;&gt; c.addFoo(Foo().__disown__())
</pre>
</div>
@ -2816,7 +2797,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard
references to the Foo objects remain in Python.
</p>
<H3><a name="Python_nn36"></a>31.5.4 Exception unrolling</H3>
<H3><a name="Python_nn36"></a>32.5.4 Exception unrolling</H3>
<p>
@ -2875,7 +2856,7 @@ Swig::DirectorMethodException is thrown, Python will register the
exception as soon as the C wrapper function returns.
</p>
<H3><a name="Python_nn37"></a>31.5.5 Overhead and code bloat</H3>
<H3><a name="Python_nn37"></a>32.5.5 Overhead and code bloat</H3>
<p>
@ -2909,7 +2890,7 @@ directive) for only those methods that are likely to be extended in
Python.
</p>
<H3><a name="Python_nn38"></a>31.5.6 Typemaps</H3>
<H3><a name="Python_nn38"></a>32.5.6 Typemaps</H3>
<p>
@ -2923,7 +2904,7 @@ need to be supported.
</p>
<H3><a name="Python_nn39"></a>31.5.7 Miscellaneous</H3>
<H3><a name="Python_nn39"></a>32.5.7 Miscellaneous</H3>
<p>
@ -2970,7 +2951,7 @@ methods that return const references.
</p>
<H2><a name="Python_nn40"></a>31.6 Common customization features</H2>
<H2><a name="Python_nn40"></a>32.6 Common customization features</H2>
<p>
@ -2983,7 +2964,7 @@ This section describes some common SWIG features that are used to
improve your the interface to an extension module.
</p>
<H3><a name="Python_nn41"></a>31.6.1 C/C++ helper functions</H3>
<H3><a name="Python_nn41"></a>32.6.1 C/C++ helper functions</H3>
<p>
@ -3064,7 +3045,7 @@ hard to implement. It is possible to clean this up using Python code, typemaps,
customization features as covered in later sections.
</p>
<H3><a name="Python_nn42"></a>31.6.2 Adding additional Python code</H3>
<H3><a name="Python_nn42"></a>32.6.2 Adding additional Python code</H3>
<p>
@ -3120,7 +3101,7 @@ customization features.
<p>Sometimes you may want to replace or modify the wrapper function
that SWIG creates in the proxy <tt>.py</tt> file. The Python module
in SWIG provides some features that enable you do do this. First, to
in SWIG provides some features that enable you to do this. First, to
entirely replace a proxy function you can use
<tt>%feature("shadow")</tt>. For example:</p>
@ -3213,7 +3194,7 @@ public:
<H3><a name="Python_nn43"></a>31.6.3 Class extension with %extend</H3>
<H3><a name="Python_nn43"></a>32.6.3 Class extension with %extend</H3>
<p>
@ -3302,7 +3283,7 @@ Vector(12,14,16)
in any way---the extensions only show up in the Python interface.
</p>
<H3><a name="Python_nn44"></a>31.6.4 Exception handling with %exception</H3>
<H3><a name="Python_nn44"></a>32.6.4 Exception handling with %exception</H3>
<p>
@ -3428,7 +3409,7 @@ The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> chapter.
</p>
<H2><a name="Python_nn45"></a>31.7 Tips and techniques</H2>
<H2><a name="Python_nn45"></a>32.7 Tips and techniques</H2>
<p>
@ -3438,7 +3419,7 @@ strings, binary data, and arrays. This chapter discusses the common techniques
solving these problems.
</p>
<H3><a name="Python_nn46"></a>31.7.1 Input and output parameters</H3>
<H3><a name="Python_nn46"></a>32.7.1 Input and output parameters</H3>
<p>
@ -3651,7 +3632,7 @@ void foo(Bar *OUTPUT);
may not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
<H3><a name="Python_nn47"></a>31.7.2 Simple pointers</H3>
<H3><a name="Python_nn47"></a>32.7.2 Simple pointers</H3>
<p>
@ -3720,7 +3701,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Python_nn48"></a>31.7.3 Unbounded C Arrays</H3>
<H3><a name="Python_nn48"></a>32.7.3 Unbounded C Arrays</H3>
<p>
@ -3782,7 +3763,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Python_nn49"></a>31.7.4 String handling</H3>
<H3><a name="Python_nn49"></a>32.7.4 String handling</H3>
<p>
@ -3851,7 +3832,7 @@ If you need to return binary data, you might use the
also be used to extra binary data from arbitrary pointers.
</p>
<H2><a name="Python_nn53"></a>31.8 Typemaps</H2>
<H2><a name="Python_nn53"></a>32.8 Typemaps</H2>
<p>
@ -3868,7 +3849,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Python interface or if you want to elevate your guru status.
</p>
<H3><a name="Python_nn54"></a>31.8.1 What is a typemap?</H3>
<H3><a name="Python_nn54"></a>32.8.1 What is a typemap?</H3>
<p>
@ -3984,7 +3965,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Python_nn55"></a>31.8.2 Python typemaps</H3>
<H3><a name="Python_nn55"></a>32.8.2 Python typemaps</H3>
<p>
@ -4025,7 +4006,7 @@ a look at the SWIG library version 1.3.20 or so.
</p>
<H3><a name="Python_nn56"></a>31.8.3 Typemap variables</H3>
<H3><a name="Python_nn56"></a>32.8.3 Typemap variables</H3>
<p>
@ -4096,7 +4077,7 @@ properly assigned.
The Python name of the wrapper function being created.
</div>
<H3><a name="Python_nn57"></a>31.8.4 Useful Python Functions</H3>
<H3><a name="Python_nn57"></a>32.8.4 Useful Python Functions</H3>
<p>
@ -4224,7 +4205,7 @@ write me
</pre>
</div>
<H2><a name="Python_nn58"></a>31.9 Typemap Examples</H2>
<H2><a name="Python_nn58"></a>32.9 Typemap Examples</H2>
<p>
@ -4233,7 +4214,7 @@ might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
</p>
<H3><a name="Python_nn59"></a>31.9.1 Converting Python list to a char ** </H3>
<H3><a name="Python_nn59"></a>32.9.1 Converting Python list to a char ** </H3>
<p>
@ -4313,7 +4294,7 @@ memory allocation is used to allocate memory for the array, the
the C function.
</p>
<H3><a name="Python_nn60"></a>31.9.2 Expanding a Python object into multiple arguments</H3>
<H3><a name="Python_nn60"></a>32.9.2 Expanding a Python object into multiple arguments</H3>
<p>
@ -4392,7 +4373,7 @@ to supply the argument count. This is automatically set by the typemap code. F
</pre>
</div>
<H3><a name="Python_nn61"></a>31.9.3 Using typemaps to return arguments</H3>
<H3><a name="Python_nn61"></a>32.9.3 Using typemaps to return arguments</H3>
<p>
@ -4481,7 +4462,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></div>
<H3><a name="Python_nn62"></a>31.9.4 Mapping Python tuples into small arrays</H3>
<H3><a name="Python_nn62"></a>32.9.4 Mapping Python tuples into small arrays</H3>
<p>
@ -4530,7 +4511,7 @@ array, such an approach would not be recommended for huge arrays, but
for small structures, this approach works fine.
</p>
<H3><a name="Python_nn63"></a>31.9.5 Mapping sequences to C arrays</H3>
<H3><a name="Python_nn63"></a>32.9.5 Mapping sequences to C arrays</H3>
<p>
@ -4619,7 +4600,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</div>
<H3><a name="Python_nn64"></a>31.9.6 Pointer handling</H3>
<H3><a name="Python_nn64"></a>32.9.6 Pointer handling</H3>
<p>
@ -4716,7 +4697,7 @@ class object (if applicable).
<H2><a name="Python_nn65"></a>31.10 Docstring Features</H2>
<H2><a name="Python_nn65"></a>32.10 Docstring Features</H2>
<p>
@ -4744,7 +4725,7 @@ of your users much simpler.
</p>
<H3><a name="Python_nn66"></a>31.10.1 Module docstring</H3>
<H3><a name="Python_nn66"></a>32.10.1 Module docstring</H3>
<p>
@ -4778,7 +4759,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
</div>
<H3><a name="Python_nn67"></a>31.10.2 %feature("autodoc")</H3>
<H3><a name="Python_nn67"></a>32.10.2 %feature("autodoc")</H3>
<p>
@ -4805,7 +4786,7 @@ names, default values if any, and return type if any. There are also
three options for autodoc controlled by the value given to the
feature, described below.
<H4><a name="Python_nn68"></a>31.10.2.1 %feature("autodoc", "0")</H4>
<H4><a name="Python_nn68"></a>32.10.2.1 %feature("autodoc", "0")</H4>
<p>
@ -4834,7 +4815,7 @@ def function_name(*args, **kwargs):
</div>
<H4><a name="Python_nn69"></a>31.10.2.2 %feature("autodoc", "1")</H4>
<H4><a name="Python_nn69"></a>32.10.2.2 %feature("autodoc", "1")</H4>
<p>
@ -4859,7 +4840,7 @@ def function_name(*args, **kwargs):
<H4><a name="Python_nn70"></a>31.10.2.3 %feature("autodoc", "docstring")</H4>
<H4><a name="Python_nn70"></a>32.10.2.3 %feature("autodoc", "docstring")</H4>
<p>
@ -4878,7 +4859,7 @@ void GetPosition(int* OUTPUT, int* OUTPUT);
</div>
<H3><a name="Python_nn71"></a>31.10.3 %feature("docstring")</H3>
<H3><a name="Python_nn71"></a>32.10.3 %feature("docstring")</H3>
<p>
@ -4910,7 +4891,7 @@ with more than one line.
</pre>
</div>
<H2><a name="Python_nn72"></a>31.11 Python Packages</H2>
<H2><a name="Python_nn72"></a>32.11 Python Packages</H2>
<p>
@ -4937,7 +4918,7 @@ and also in base class declarations, etc. if the package name is
different than its own.
</p>
<H2><a name="Python_python3support"></a>31.12 Python 3 Support</H2>
<H2><a name="Python_python3support"></a>32.12 Python 3 Support</H2>
<p>
@ -4964,7 +4945,7 @@ The following are Python 3.0 new features that are currently supported by
SWIG.
</p>
<H3><a name="Python_nn74"></a>31.12.1 Function annotation</H3>
<H3><a name="Python_nn74"></a>32.12.1 Function annotation</H3>
<p>
@ -4996,7 +4977,7 @@ all overloaded functions share the same function in SWIG generated proxy class.
For detailed usage of function annotation, see PEP 3107.
</p>
<H3><a name="Python_nn75"></a>31.12.2 Buffer interface</H3>
<H3><a name="Python_nn75"></a>32.12.2 Buffer interface</H3>
<p>
@ -5148,7 +5129,7 @@ modify the buffer.
</div>
<H3><a name="Python_nn76"></a>31.12.3 Abstract base classes</H3>
<H3><a name="Python_nn76"></a>32.12.3 Abstract base classes</H3>
<p>

50
Doc/Manual/R.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="R"></a>34 SWIG and R</H1>
<H1><a name="R"></a>35 SWIG and R</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -33,7 +33,7 @@ compile and run an R interface to QuantLib running on Mandriva Linux
with gcc. The R bindings also work on Microsoft Windows using Visual C++.
</p>
<H2><a name="R_nn2"></a>34.1 Bugs</H2>
<H2><a name="R_nn2"></a>35.1 Bugs</H2>
<p>
@ -45,7 +45,7 @@ Currently the following features are not implemented or broken:
<li>C Array wrappings
</ul>
<H2><a name="R_nn3"></a>34.2 Using R and SWIG</H2>
<H2><a name="R_nn3"></a>35.2 Using R and SWIG</H2>
<p>
@ -56,28 +56,48 @@ example.c is the name of the file with the functions in them
<div class="shell">
<pre>
swig -r example.i
PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
R CMD SHLIB example_wrap.c example.c
</pre>
</div>
<p>
The corresponding comments for C++ mode are
The corresponding options for C++ mode are
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
R CMD SHLIB example_wrap.cpp example.cpp
</pre>
</div>
<p>
Note that R is sensitive to the name of the file and to the file
extension in C and C++ mode. The name of the wrapper file must be the
name of the library. Also in C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it.
Note that R is sensitive to the names of the files.
The name of the wrapper file must be the
name of the library unless you use the -o option to R when building the library, for example:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
R CMD SHLIB -o example.so example_wrap.cpp example.cpp
</pre>
</div>
<p>
R is also sensitive to the name of the file
extension in C and C++ mode. In C++ mode, the file extension must be .cpp
rather than .cxx for the R compile command to recognize it. If your C++ code is
in a file using something other than a .cpp extension, then it may still work using PKG_LIBS:
</p>
<div class="shell">
<pre>
swig -c++ -r -o example_wrap.cpp example.i
PKG_LIBS="example.cxx" R CMD SHLIB -o example example_wrap.cpp
</pre>
</div>
<p>
The commands produces two files. A dynamic shared object file called
example.so, or example.dll, and an R wrapper file called example.R. To load these
@ -99,7 +119,7 @@ Without it, inheritance of wrapped objects may fail.
These two files can be loaded in any order
</p>
<H2><a name="R_nn4"></a>34.3 Precompiling large R files</H2>
<H2><a name="R_nn4"></a>35.3 Precompiling large R files</H2>
In cases where the R file is large, one make save a lot of loading
@ -117,7 +137,7 @@ will save a large amount of loading time.
<H2><a name="R_nn5"></a>34.4 General policy</H2>
<H2><a name="R_nn5"></a>35.4 General policy</H2>
<p>
@ -126,7 +146,7 @@ wrapping over the underlying functions and rely on the R type system
to provide R syntax.
</p>
<H2><a name="R_language_conventions"></a>34.5 Language conventions</H2>
<H2><a name="R_language_conventions"></a>35.5 Language conventions</H2>
<p>
@ -135,7 +155,7 @@ and [ are overloaded to allow for R syntax (one based indices and
slices)
</p>
<H2><a name="R_nn6"></a>34.6 C++ classes</H2>
<H2><a name="R_nn6"></a>35.6 C++ classes</H2>
<p>
@ -147,7 +167,7 @@ keep track of the pointer object which removes the necessity for a lot
of the proxy class baggage you see in other languages.
</p>
<H2><a name="R_nn7"></a>34.7 Enumerations</H2>
<H2><a name="R_nn7"></a>35.7 Enumerations</H2>
<p>

220
Doc/Manual/Ruby.html
View file

@ -26,7 +26,7 @@
<H1><a name="Ruby"></a>32 SWIG and Ruby</H1>
<H1><a name="Ruby"></a>33 SWIG and Ruby</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -58,7 +58,7 @@
<li><a href="#Ruby_nn22">C++ namespaces</a>
<li><a href="#Ruby_nn23">C++ templates</a>
<li><a href="#Ruby_nn23_1">C++ Standard Template Library (STL)</a>
<li><a href="#C_STL_Functors">C++ STL Functors</a>
<li><a href="#Ruby_C_STL_Functors">C++ STL Functors</a>
<li><a href="#Ruby_C_Iterators">C++ STL Iterators</a>
<li><a href="#Ruby_nn24">C++ Smart Pointers</a>
<li><a href="#Ruby_nn25">Cross-Language Polymorphism</a>
@ -142,7 +142,7 @@
</ul>
<li><a href="#Ruby_nn53">Advanced Topics</a>
<ul>
<li><a href="#Ruby_nn54">Operator overloading</a>
<li><a href="#Ruby_operator_overloading">Operator overloading</a>
<li><a href="#Ruby_nn55">Creating Multi-Module Packages</a>
<li><a href="#Ruby_nn56">Specifying Mixin Modules</a>
</ul>
@ -167,7 +167,7 @@
<H2><a name="Ruby_nn2"></a>32.1 Preliminaries</H2>
<H2><a name="Ruby_nn2"></a>33.1 Preliminaries</H2>
<p> SWIG 1.3 is known to work with Ruby versions 1.6 and later.
@ -190,7 +190,7 @@ of Ruby. </p>
<H3><a name="Ruby_nn3"></a>32.1.1 Running SWIG</H3>
<H3><a name="Ruby_nn3"></a>33.1.1 Running SWIG</H3>
<p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
@ -244,7 +244,7 @@ to compile this file and link it with the rest of your program. </p>
<H3><a name="Ruby_nn4"></a>32.1.2 Getting the right header files</H3>
<H3><a name="Ruby_nn4"></a>33.1.2 Getting the right header files</H3>
<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@ -288,7 +288,7 @@ installed, you can run Ruby to find out. For example: </p>
<H3><a name="Ruby_nn5"></a>32.1.3 Compiling a dynamic module</H3>
<H3><a name="Ruby_nn5"></a>33.1.3 Compiling a dynamic module</H3>
<p> Ruby extension modules are typically compiled into shared
@ -443,7 +443,7 @@ manual pages for your compiler and linker to determine the correct set
of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a>
for additional information. </p>
<H3><a name="Ruby_nn6"></a>32.1.4 Using your module</H3>
<H3><a name="Ruby_nn6"></a>33.1.4 Using your module</H3>
<p> Ruby <i>module</i> names must be capitalized,
@ -498,7 +498,7 @@ begins with: </p>
<H3><a name="Ruby_nn7"></a>32.1.5 Static linking</H3>
<H3><a name="Ruby_nn7"></a>33.1.5 Static linking</H3>
<p> An alternative approach to dynamic linking is to rebuild the
@ -519,7 +519,7 @@ finally rebuilding Ruby. </p>
<H3><a name="Ruby_nn8"></a>32.1.6 Compilation of C++ extensions</H3>
<H3><a name="Ruby_nn8"></a>33.1.6 Compilation of C++ extensions</H3>
<p> On most machines, C++ extension modules should be linked
@ -571,7 +571,7 @@ extension, e.g. </p>
<H2><a name="Ruby_nn9"></a>32.2 Building Ruby Extensions under Windows 95/NT</H2>
<H2><a name="Ruby_nn9"></a>33.2 Building Ruby Extensions under Windows 95/NT</H2>
<p> Building a SWIG extension to Ruby under Windows 95/NT is
@ -610,7 +610,7 @@ files. </p>
<H3><a name="Ruby_nn10"></a>32.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Ruby_nn10"></a>33.2.1 Running SWIG from Developer Studio</H3>
<p> If you are developing your application within Microsoft
@ -752,7 +752,7 @@ directory, then run the Ruby script from the DOS/Command prompt: </p>
<H2><a name="Ruby_nn11"></a>32.3 The Ruby-to-C/C++ Mapping</H2>
<H2><a name="Ruby_nn11"></a>33.3 The Ruby-to-C/C++ Mapping</H2>
<p> This section describes the basics of how SWIG maps C or C++
@ -762,7 +762,7 @@ declarations in your SWIG interface files to Ruby constructs. </p>
<H3><a name="Ruby_nn12"></a>32.3.1 Modules</H3>
<H3><a name="Ruby_nn12"></a>33.3.1 Modules</H3>
<p> The SWIG <tt>%module</tt> directive specifies
@ -931,7 +931,7 @@ Ruby's built-in names. </p>
<H3><a name="Ruby_nn13"></a>32.3.2 Functions</H3>
<H3><a name="Ruby_nn13"></a>33.3.2 Functions</H3>
<p> Global functions are wrapped as Ruby module methods. For
@ -994,7 +994,7 @@ module that can be used like so: </p>
<H3><a name="Ruby_nn14"></a>32.3.3 Variable Linking</H3>
<H3><a name="Ruby_nn14"></a>33.3.3 Variable Linking</H3>
<p> C/C++ global variables are wrapped as a pair of singleton
@ -1094,7 +1094,7 @@ effect until it is explicitly disabled using <tt>%mutable</tt>.
<H3><a name="Ruby_nn15"></a>32.3.4 Constants</H3>
<H3><a name="Ruby_nn15"></a>33.3.4 Constants</H3>
<p> C/C++ constants are wrapped as module constants initialized
@ -1138,7 +1138,7 @@ constant values, e.g. </p>
<H3><a name="Ruby_nn16"></a>32.3.5 Pointers</H3>
<H3><a name="Ruby_nn16"></a>33.3.5 Pointers</H3>
<p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
@ -1190,7 +1190,7 @@ the Ruby <tt>nil</tt> object. </p>
<H3><a name="Ruby_nn17"></a>32.3.6 Structures</H3>
<H3><a name="Ruby_nn17"></a>33.3.6 Structures</H3>
<p> C/C++ structs are wrapped as Ruby classes, with accessor
@ -1317,7 +1317,7 @@ this code: </p>
<p> If you want to set an array member, you will need to supply a
"memberin" typemap described in the <a href="#ruby_cpp_smart_pointers">section on typemaps</a>.
"memberin" typemap described in the <a href="#Ruby_memberin_typemap">section on typemaps</a>.
As a special case, SWIG does generate code to set array members of type
<tt>char</tt> (allowing you to store a Ruby string in the
structure). </p>
@ -1365,7 +1365,7 @@ pointers. For example, </p>
<H3><a name="Ruby_nn18"></a>32.3.7 C++ classes</H3>
<H3><a name="Ruby_nn18"></a>33.3.7 C++ classes</H3>
<p> Like structs, C++ classes are wrapped by creating a new Ruby
@ -1451,7 +1451,7 @@ class. </li>
<H3><a name="Ruby_nn19"></a>32.3.8 C++ Inheritance</H3>
<H3><a name="Ruby_nn19"></a>33.3.8 C++ Inheritance</H3>
<p> The SWIG type-checker is fully aware of C++ inheritance.
@ -1682,7 +1682,7 @@ Typing"</a>). </p>
<H3><a name="Ruby_nn20"></a>32.3.9 C++ Overloaded Functions</H3>
<H3><a name="Ruby_nn20"></a>33.3.9 C++ Overloaded Functions</H3>
<p> C++ overloaded functions, methods, and constructors are
@ -1882,7 +1882,7 @@ and C++"</a> chapter for more information about overloading. </p>
<H3><a name="Ruby_nn21"></a>32.3.10 C++ Operators</H3>
<H3><a name="Ruby_nn21"></a>33.3.10 C++ Operators</H3>
<p> For the most part, overloaded operators are handled
@ -1956,14 +1956,14 @@ example: </p>
<p> More details about wrapping C++ operators into Ruby operators
is discussed in the <a href="#ruby_operator_overloading">section
is discussed in the <a href="#Ruby_operator_overloading">section
on operator overloading</a>. </p>
<H3><a name="Ruby_nn22"></a>32.3.11 C++ namespaces</H3>
<H3><a name="Ruby_nn22"></a>33.3.11 C++ namespaces</H3>
<p> SWIG is aware of C++ namespaces, but namespace names do not
@ -2039,7 +2039,7 @@ identical symbol names, well, then you get what you deserve. </p>
<H3><a name="Ruby_nn23"></a>32.3.12 C++ templates</H3>
<H3><a name="Ruby_nn23"></a>33.3.12 C++ templates</H3>
<p> C++ templates don't present a huge problem for SWIG. However,
@ -2083,7 +2083,7 @@ directive. For example: </p>
<H3><a name="Ruby_nn23_1"></a>32.3.13 C++ Standard Template Library (STL)</H3>
<H3><a name="Ruby_nn23_1"></a>33.3.13 C++ Standard Template Library (STL)</H3>
<p> On a related note, the standard SWIG library contains a
@ -2336,7 +2336,7 @@ chapter.</p>
<H3><a name="C_STL_Functors"></a>32.3.14 C++ STL Functors</H3>
<H3><a name="Ruby_C_STL_Functors"></a>33.3.14 C++ STL Functors</H3>
<p>Some containers in the STL allow you to modify their default
@ -2536,7 +2536,7 @@ b<br style="font-weight: bold;">
<H3><a name="Ruby_C_Iterators"></a>32.3.15 C++ STL Iterators</H3>
<H3><a name="Ruby_C_Iterators"></a>33.3.15 C++ STL Iterators</H3>
<p>The STL is well known for the use of iterators. &nbsp;There
@ -2747,7 +2747,7 @@ i<br>
<H3><a name="Ruby_nn24"></a>32.3.16 C++ Smart Pointers</H3>
<H3><a name="Ruby_nn24"></a>33.3.16 C++ Smart Pointers</H3>
<p> In certain C++ programs, it is common to use classes that
@ -2872,12 +2872,12 @@ method. For example: </p>
<H3><a name="Ruby_nn25"></a>32.3.17 Cross-Language Polymorphism</H3>
<H3><a name="Ruby_nn25"></a>33.3.17 Cross-Language Polymorphism</H3>
<p> SWIG's Ruby module supports cross-language polymorphism
(a.k.a. the "directors" feature) similar to that for SWIG's Python
module. Rather than duplicate the information presented in the <a href="Ruby">Python</a> chapter, this
module. Rather than duplicate the information presented in the <a href="Python.html#Python">Python</a> chapter, this
section just notes the differences that you need to be aware of when
using this feature with Ruby. </p>
@ -2885,7 +2885,7 @@ using this feature with Ruby. </p>
<H4><a name="Ruby_nn26"></a>32.3.17.1 Exception Unrolling</H4>
<H4><a name="Ruby_nn26"></a>33.3.17.1 Exception Unrolling</H4>
<p> Whenever a C++ director class routes one of its virtual
@ -2923,7 +2923,7 @@ caught here and a C++ exception is raised in its place. </p>
<H2><a name="Ruby_nn27"></a>32.4 Naming</H2>
<H2><a name="Ruby_nn27"></a>33.4 Naming</H2>
<p>Ruby has several common naming conventions. Constants are
@ -3019,7 +3019,7 @@ planned to become the default option in future releases.</p>
<H3><a name="Ruby_nn28"></a>32.4.1 Defining Aliases</H3>
<H3><a name="Ruby_nn28"></a>33.4.1 Defining Aliases</H3>
<p> It's a fairly common practice in the Ruby built-ins and
@ -3111,7 +3111,7 @@ Features"</a>) for more details).</p>
<H3><a name="Ruby_nn29"></a>32.4.2 Predicate Methods</H3>
<H3><a name="Ruby_nn29"></a>33.4.2 Predicate Methods</H3>
<p> Ruby methods that return a boolean value and end in a
@ -3200,7 +3200,7 @@ Features"</a>) for more details). </p>
<H3><a name="Ruby_nn30"></a>32.4.3 Bang Methods</H3>
<H3><a name="Ruby_nn30"></a>33.4.3 Bang Methods</H3>
<p> Ruby methods that modify an object in-place and end in an
@ -3264,7 +3264,7 @@ Features"</a>) for more details). </p>
<H3><a name="Ruby_nn31"></a>32.4.4 Getters and Setters</H3>
<H3><a name="Ruby_nn31"></a>33.4.4 Getters and Setters</H3>
<p> Often times a C++ library will expose properties through
@ -3334,7 +3334,7 @@ methods to be exposed in Ruby as <tt>value</tt> and <tt>value=.
<H2><a name="Ruby_nn32"></a>32.5 Input and output parameters</H2>
<H2><a name="Ruby_nn32"></a>33.5 Input and output parameters</H2>
<p> A common problem in some C programs is handling parameters
@ -3585,10 +3585,10 @@ of <tt>%apply</tt> </p>
<H2><a name="Ruby_nn33"></a>32.6 Exception handling </H2>
<H2><a name="Ruby_nn33"></a>33.6 Exception handling </H2>
<H3><a name="Ruby_nn34"></a>32.6.1 Using the %exception directive </H3>
<H3><a name="Ruby_nn34"></a>33.6.1 Using the %exception directive </H3>
<p>The SWIG <tt>%exception</tt> directive can be
@ -3683,7 +3683,7 @@ Features</a> for more examples.</p>
<H3><a name="Ruby_nn34_2"></a>32.6.2 Handling Ruby Blocks </H3>
<H3><a name="Ruby_nn34_2"></a>33.6.2 Handling Ruby Blocks </H3>
<p>One of the highlights of Ruby and most of its standard library
@ -3864,7 +3864,7 @@ RUBY_YIELD_SELF );<br>
<p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
<H3><a name="Ruby_nn35"></a>32.6.3 Raising exceptions </H3>
<H3><a name="Ruby_nn35"></a>33.6.3 Raising exceptions </H3>
<p>There are three ways to raise exceptions from C++ code to
@ -4625,7 +4625,7 @@ the built-in Ruby exception types.</p>
<H3><a name="Ruby_nn36"></a>32.6.4 Exception classes </H3>
<H3><a name="Ruby_nn36"></a>33.6.4 Exception classes </H3>
<p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
@ -4683,7 +4683,7 @@ providing for a more natural integration between C++ code and Ruby code.</p>
<H2><a name="Ruby_nn37"></a>32.7 Typemaps</H2>
<H2><a name="Ruby_nn37"></a>33.7 Typemaps</H2>
<p> This section describes how you can modify SWIG's default
@ -4706,7 +4706,7 @@ of the primitive C-Ruby interface.</p>
<H3><a name="Ruby_nn38"></a>32.7.1 What is a typemap?</H3>
<H3><a name="Ruby_nn38"></a>33.7.1 What is a typemap?</H3>
<p> A typemap is nothing more than a code generation rule that is
@ -4968,7 +4968,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
<H3><a name="Ruby_Typemap_scope"></a>32.7.2 Typemap scope</H3>
<H3><a name="Ruby_Typemap_scope"></a>33.7.2 Typemap scope</H3>
<p> Once defined, a typemap remains in effect for all of the
@ -5016,7 +5016,7 @@ where the class itself is defined. For example:</p>
<H3><a name="Ruby_Copying_a_typemap"></a>32.7.3 Copying a typemap</H3>
<H3><a name="Ruby_Copying_a_typemap"></a>33.7.3 Copying a typemap</H3>
<p> A typemap is copied by using assignment. For example:</p>
@ -5118,7 +5118,7 @@ rules as for <tt>
<H3><a name="Ruby_Deleting_a_typemap"></a>32.7.4 Deleting a typemap</H3>
<H3><a name="Ruby_Deleting_a_typemap"></a>33.7.4 Deleting a typemap</H3>
<p> A typemap can be deleted by simply defining no code. For
@ -5170,7 +5170,7 @@ typemaps immediately after the clear operation.</p>
<H3><a name="Ruby_Placement_of_typemaps"></a>32.7.5 Placement of typemaps</H3>
<H3><a name="Ruby_Placement_of_typemaps"></a>33.7.5 Placement of typemaps</H3>
<p> Typemap declarations can be declared in the global scope,
@ -5254,7 +5254,7 @@ string</tt>
<H3><a name="Ruby_nn39"></a>32.7.6 Ruby typemaps</H3>
<H3><a name="Ruby_nn39"></a>33.7.6 Ruby typemaps</H3>
<p>The following list details all of the typemap methods that
@ -5264,7 +5264,7 @@ can be used by the Ruby module: </p>
<H4><a name="Ruby_in_typemap"></a>32.7.6.1 &nbsp;"in" typemap</H4>
<H4><a name="Ruby_in_typemap"></a>33.7.6.1 &nbsp;"in" typemap</H4>
<p>Converts Ruby objects to input
@ -5507,7 +5507,7 @@ arguments to be specified. For example:</p>
<H4><a name="Ruby_typecheck_typemap"></a>32.7.6.2 "typecheck" typemap</H4>
<H4><a name="Ruby_typecheck_typemap"></a>33.7.6.2 "typecheck" typemap</H4>
<p> The "typecheck" typemap is used to support overloaded
@ -5548,7 +5548,7 @@ on "Typemaps and Overloading."</p>
<H4><a name="Ruby_out_typemap"></a>32.7.6.3 &nbsp;"out" typemap</H4>
<H4><a name="Ruby_out_typemap"></a>33.7.6.3 &nbsp;"out" typemap</H4>
<p>Converts return value of a C function
@ -5780,7 +5780,7 @@ version of the C datatype matched by the typemap.</td>
<H4><a name="Ruby_arginit_typemap"></a>32.7.6.4 "arginit" typemap</H4>
<H4><a name="Ruby_arginit_typemap"></a>33.7.6.4 "arginit" typemap</H4>
<p> The "arginit" typemap is used to set the initial value of a
@ -5805,7 +5805,7 @@ applications. For example:</p>
<H4><a name="Ruby_default_typemap"></a>32.7.6.5 "default" typemap</H4>
<H4><a name="Ruby_default_typemap"></a>33.7.6.5 "default" typemap</H4>
<p> The "default" typemap is used to turn an argument into a
@ -5847,7 +5847,7 @@ default argument wrapping.</p>
<H4><a name="Ruby_check_typemap"></a>32.7.6.6 "check" typemap</H4>
<H4><a name="Ruby_check_typemap"></a>33.7.6.6 "check" typemap</H4>
<p> The "check" typemap is used to supply value checking code
@ -5871,7 +5871,7 @@ arguments have been converted. For example:</p>
<H4><a name="Ruby_argout_typemap_"></a>32.7.6.7 "argout" typemap</H4>
<H4><a name="Ruby_argout_typemap_"></a>33.7.6.7 "argout" typemap</H4>
<p> The "argout" typemap is used to return values from arguments.
@ -6029,7 +6029,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
<H4><a name="Ruby_freearg_typemap_"></a>32.7.6.8 "freearg" typemap</H4>
<H4><a name="Ruby_freearg_typemap_"></a>33.7.6.8 "freearg" typemap</H4>
<p> The "freearg" typemap is used to cleanup argument data. It is
@ -6065,7 +6065,7 @@ abort prematurely.</p>
<H4><a name="Ruby_newfree_typemap"></a>32.7.6.9 "newfree" typemap</H4>
<H4><a name="Ruby_newfree_typemap"></a>33.7.6.9 "newfree" typemap</H4>
<p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
@ -6089,14 +6089,14 @@ a function. For example:</p>
<p> See <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#ownership">Object
<p> See <a href="Customization.html#Customization_ownership">Object
ownership and %newobject</a> for further details.</p>
<H4><a name="Ruby_memberin_typemap"></a>32.7.6.10 "memberin" typemap</H4>
<H4><a name="Ruby_memberin_typemap"></a>33.7.6.10 "memberin" typemap</H4>
<p> The "memberin" typemap is used to copy data from<em> an
@ -6129,7 +6129,7 @@ other objects.</p>
<H4><a name="Ruby_varin_typemap"></a>32.7.6.11 "varin" typemap</H4>
<H4><a name="Ruby_varin_typemap"></a>33.7.6.11 "varin" typemap</H4>
<p> The "varin" typemap is used to convert objects in the target
@ -6140,7 +6140,7 @@ This is implementation specific.</p>
<H4><a name="Ruby_varout_typemap_"></a>32.7.6.12 "varout" typemap</H4>
<H4><a name="Ruby_varout_typemap_"></a>33.7.6.12 "varout" typemap</H4>
<p> The "varout" typemap is used to convert a C/C++ object to an
@ -6151,7 +6151,7 @@ This is implementation specific.</p>
<H4><a name="Ruby_throws_typemap"></a>32.7.6.13 "throws" typemap</H4>
<H4><a name="Ruby_throws_typemap"></a>33.7.6.13 "throws" typemap</H4>
<p> The "throws" typemap is only used when SWIG parses a C++
@ -6210,7 +6210,7 @@ handling with %exception</a> section.</p>
<H4><a name="Ruby_directorin_typemap"></a>32.7.6.14 directorin typemap</H4>
<H4><a name="Ruby_directorin_typemap"></a>33.7.6.14 directorin typemap</H4>
<p>Converts C++ objects in director
@ -6464,7 +6464,7 @@ referring to the class itself.</td>
<H4><a name="Ruby_directorout_typemap"></a>32.7.6.15 directorout typemap</H4>
<H4><a name="Ruby_directorout_typemap"></a>33.7.6.15 directorout typemap</H4>
<p>Converts Ruby objects in director
@ -6724,7 +6724,7 @@ exception.<br>
<H4><a name="Ruby_directorargout_typemap"></a>32.7.6.16 directorargout typemap</H4>
<H4><a name="Ruby_directorargout_typemap"></a>33.7.6.16 directorargout typemap</H4>
<p>Output argument processing in director
@ -6964,7 +6964,7 @@ referring to the instance of the class itself</td>
<H4><a name="Ruby_ret_typemap"></a>32.7.6.17 ret typemap</H4>
<H4><a name="Ruby_ret_typemap"></a>33.7.6.17 ret typemap</H4>
<p>Cleanup of function return values
@ -6974,7 +6974,7 @@ referring to the instance of the class itself</td>
<H4><a name="Ruby_globalin_typemap"></a>32.7.6.18 globalin typemap</H4>
<H4><a name="Ruby_globalin_typemap"></a>33.7.6.18 globalin typemap</H4>
<p>Setting of C global variables
@ -6984,7 +6984,7 @@ referring to the instance of the class itself</td>
<H3><a name="Ruby_nn40"></a>32.7.7 Typemap variables</H3>
<H3><a name="Ruby_nn40"></a>33.7.7 Typemap variables</H3>
<p>
@ -7094,13 +7094,13 @@ being created. </div>
<H3><a name="Ruby_nn41"></a>32.7.8 Useful Functions</H3>
<H3><a name="Ruby_nn41"></a>33.7.8 Useful Functions</H3>
<p> When you write a typemap, you usually have to work directly
with Ruby objects. The following functions may prove to be useful.
(These functions plus many more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
Ruby</em></a>, by David Thomas and Andrew Hunt.)&nbsp;</p>
(These functions plus many more can be found in <em>Programming
Ruby</em> book, by David Thomas and Andrew Hunt.)&nbsp;</p>
<p>In addition, we list equivalent functions that SWIG defines, which
provide a language neutral conversion (these functions are defined for
each swig language supported). &nbsp;If you are trying to create a swig
@ -7118,7 +7118,7 @@ across multiple languages.</p>
<H4><a name="Ruby_nn42"></a>32.7.8.1 C Datatypes to Ruby Objects</H4>
<H4><a name="Ruby_nn42"></a>33.7.8.1 C Datatypes to Ruby Objects</H4>
<div class="diagram">
@ -7174,7 +7174,7 @@ SWIG_From_float(float)</td>
<H4><a name="Ruby_nn43"></a>32.7.8.2 Ruby Objects to C Datatypes</H4>
<H4><a name="Ruby_nn43"></a>33.7.8.2 Ruby Objects to C Datatypes</H4>
<p>Here, while the Ruby versions return the value directly, the SWIG
@ -7263,7 +7263,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
<H4><a name="Ruby_nn44"></a>32.7.8.3 Macros for VALUE</H4>
<H4><a name="Ruby_nn44"></a>33.7.8.3 Macros for VALUE</H4>
<p> <tt>RSTRING_LEN(str)</tt> </p>
@ -7326,7 +7326,7 @@ Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input
<H4><a name="Ruby_nn45"></a>32.7.8.4 Exceptions</H4>
<H4><a name="Ruby_nn45"></a>33.7.8.4 Exceptions</H4>
<p> <tt>void rb_raise(VALUE exception, const char *fmt,
@ -7493,7 +7493,7 @@ arguments are interpreted as with <tt>printf()</tt>. </div>
<H4><a name="Ruby_nn46"></a>32.7.8.5 Iterators</H4>
<H4><a name="Ruby_nn46"></a>33.7.8.5 Iterators</H4>
<p> <tt>void rb_iter_break()</tt> </p>
@ -7595,7 +7595,7 @@ VALUE), VALUE value)</tt></p>
<H3><a name="Ruby_nn47"></a>32.7.9 Typemap Examples</H3>
<H3><a name="Ruby_nn47"></a>33.7.9 Typemap Examples</H3>
<p> This section includes a few examples of typemaps. For more
@ -7606,7 +7606,7 @@ directory. </p>
<H3><a name="Ruby_nn48"></a>32.7.10 Converting a Ruby array to a char **</H3>
<H3><a name="Ruby_nn48"></a>33.7.10 Converting a Ruby array to a char **</H3>
<p> A common problem in many C programs is the processing of
@ -7661,7 +7661,7 @@ after the execution of the C function. </p>
<H3><a name="Ruby_nn49"></a>32.7.11 Collecting arguments in a hash</H3>
<H3><a name="Ruby_nn49"></a>33.7.11 Collecting arguments in a hash</H3>
<p> Ruby's solution to the "keyword arguments" capability of some
@ -7940,7 +7940,7 @@ directory of the SWIG distribution. </p>
<H3><a name="Ruby_nn50"></a>32.7.12 Pointer handling</H3>
<H3><a name="Ruby_nn50"></a>33.7.12 Pointer handling</H3>
<p> Occasionally, it might be necessary to convert pointer values
@ -8039,7 +8039,7 @@ For example: </p>
<H4><a name="Ruby_nn51"></a>32.7.12.1 Ruby Datatype Wrapping</H4>
<H4><a name="Ruby_nn51"></a>33.7.12.1 Ruby Datatype Wrapping</H4>
<p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
@ -8090,7 +8090,7 @@ and assigns that pointer to <i>ptr</i>. </div>
<H3><a name="Ruby_nn52"></a>32.7.13 Example: STL Vector to Ruby Array</H3>
<H3><a name="Ruby_nn52"></a>33.7.13 Example: STL Vector to Ruby Array</H3>
<p>Another use for macros and type maps is to create a Ruby array
@ -8199,7 +8199,7 @@ the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.<br>
<H2><a name="Ruby_nn65"></a>32.8 Docstring Features</H2>
<H2><a name="Ruby_nn65"></a>33.8 Docstring Features</H2>
<p>
@ -8260,7 +8260,7 @@ generate ri documentation from a c wrap file, you could do:</p>
<H3><a name="Ruby_nn66"></a>32.8.1 Module docstring</H3>
<H3><a name="Ruby_nn66"></a>33.8.1 Module docstring</H3>
<p>
@ -8311,7 +8311,7 @@ macro. For example:
<H3><a name="Ruby_nn67"></a>32.8.2 %feature("autodoc")</H3>
<H3><a name="Ruby_nn67"></a>33.8.2 %feature("autodoc")</H3>
<p>Since SWIG does know everything about the function it wraps,
@ -8340,7 +8340,7 @@ feature, described below.
<H4><a name="Ruby_nn68"></a>32.8.2.1 %feature("autodoc", "0")</H4>
<H4><a name="Ruby_nn68"></a>33.8.2.1 %feature("autodoc", "0")</H4>
<p>
@ -8388,7 +8388,7 @@ Then Ruby code like this will be generated:
<H4><a name="Ruby_autodoc1"></a>32.8.2.2 %feature("autodoc", "1")</H4>
<H4><a name="Ruby_autodoc1"></a>33.8.2.2 %feature("autodoc", "1")</H4>
<p>
@ -8420,7 +8420,7 @@ this:
<H4><a name="Ruby_autodoc2"></a>32.8.2.3 %feature("autodoc", "2")</H4>
<H4><a name="Ruby_autodoc2"></a>33.8.2.3 %feature("autodoc", "2")</H4>
<p>
@ -8436,7 +8436,7 @@ this:
<H4><a name="Ruby_feature_autodoc3"></a>32.8.2.4 %feature("autodoc", "3")</H4>
<H4><a name="Ruby_feature_autodoc3"></a>33.8.2.4 %feature("autodoc", "3")</H4>
<p>
@ -8464,7 +8464,7 @@ this:
<H4><a name="Ruby_nn70"></a>32.8.2.5 %feature("autodoc", "docstring")</H4>
<H4><a name="Ruby_nn70"></a>33.8.2.5 %feature("autodoc", "docstring")</H4>
<p>
@ -8492,7 +8492,7 @@ generated string. For example:
<H3><a name="Ruby_nn71"></a>32.8.3 %feature("docstring")</H3>
<H3><a name="Ruby_nn71"></a>33.8.3 %feature("docstring")</H3>
<p>
@ -8507,10 +8507,10 @@ docstring and they are output together. </p>
<H2><a name="Ruby_nn53"></a>32.9 Advanced Topics</H2>
<H2><a name="Ruby_nn53"></a>33.9 Advanced Topics</H2>
<H3><a name="Ruby_nn54"></a>32.9.1 Operator overloading</H3>
<H3><a name="Ruby_operator_overloading"></a>33.9.1 Operator overloading</H3>
<p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
@ -9527,10 +9527,10 @@ parses the expression <i>a != b</i> as <i>!(a == b)</i>.
<H3><a name="Ruby_nn55"></a>32.9.2 Creating Multi-Module Packages</H3>
<H3><a name="Ruby_nn55"></a>33.9.2 Creating Multi-Module Packages</H3>
<p> The chapter on <a href="Modules.html">Working
<p> The chapter on <a href="Modules.html#Modules">Working
with Modules</a> discusses the basics of creating multi-module
extensions with SWIG, and in particular the considerations for sharing
runtime type information among the different modules. </p>
@ -9708,7 +9708,7 @@ initialized: </p>
<H3><a name="Ruby_nn56"></a>32.9.3 Specifying Mixin Modules</H3>
<H3><a name="Ruby_nn56"></a>33.9.3 Specifying Mixin Modules</H3>
<p> The Ruby language doesn't support multiple inheritance, but
@ -9806,7 +9806,7 @@ Features"</a>) for more details). </p>
<H2><a name="Ruby_nn57"></a>32.10 Memory Management</H2>
<H2><a name="Ruby_nn57"></a>33.10 Memory Management</H2>
<p>One of the most common issues in generating SWIG bindings for
@ -9853,7 +9853,7 @@ understanding of how the underlying library manages memory.</p>
<H3><a name="Ruby_nn58"></a>32.10.1 Mark and Sweep Garbage Collector </H3>
<H3><a name="Ruby_nn58"></a>33.10.1 Mark and Sweep Garbage Collector </H3>
<p>Ruby uses a mark and sweep garbage collector. When the garbage
@ -9901,7 +9901,7 @@ this memory. </p>
<H3><a name="Ruby_nn59"></a>32.10.2 Object Ownership</H3>
<H3><a name="Ruby_nn59"></a>33.10.2 Object Ownership</H3>
<p>As described above, memory management depends on clearly
@ -10050,7 +10050,7 @@ above. For example:</p>
<p>In this case, the default SWIG behavior for calling member
functions is incorrect. The Ruby object should assume ownership of the
returned object. This can be done by using the %newobject directive.
See <a href="file:///d:/msys/1.0/src/SWIG/Doc/Manual/Customization.html#ownership">
See <a href="Customization.html#Customization_ownership">
Object ownership and %newobject</a> for more information. </p>
@ -10128,7 +10128,7 @@ classes is:</p>
<H3><a name="Ruby_nn60"></a>32.10.3 Object Tracking</H3>
<H3><a name="Ruby_nn60"></a>33.10.3 Object Tracking</H3>
<p>The remaining parts of this section will use the class library
@ -10204,7 +10204,7 @@ the same underlying C++ object. This can cause problems. For example:<br>
<p>After the the garbage collector runs, as a result of our call
<p>After the garbage collector runs, as a result of our call
to <tt>GC.start</tt>, calling<tt>tiger2.get_name()</tt>
causes a segmentation fault. The problem is that when <tt>tiger1</tt>
is garbage collected, it frees the underlying C++ object. Thus, when <tt>tiger2</tt>
@ -10342,7 +10342,7 @@ methods.</p>
<H3><a name="Ruby_nn61"></a>32.10.4 Mark Functions</H3>
<H3><a name="Ruby_nn61"></a>33.10.4 Mark Functions</H3>
<p>With a bit more testing, we see that our class library still
@ -10460,7 +10460,7 @@ test suite.</p>
<H3><a name="Ruby_nn62"></a>32.10.5 Free Functions</H3>
<H3><a name="Ruby_nn62"></a>33.10.5 Free Functions</H3>
<p>By default, SWIG creates a "free" function that is called when
@ -10615,7 +10615,7 @@ been freed, and thus raises a runtime exception.</p>
<H3><a name="Ruby_nn63"></a>32.10.6 Embedded Ruby and the C++ Stack</H3>
<H3><a name="Ruby_nn63"></a>33.10.6 Embedded Ruby and the C++ Stack</H3>
<p>As has been said, the Ruby GC runs and marks objects before
@ -10649,7 +10649,7 @@ initialization a normal Ruby interpreter will call the ruby_init()
function which in turn will call a function called Init_stack or
similar. &nbsp;This function will store a pointer to the location
where
the stack points at at that point in time.</p>
the stack points at that point in time.</p>

20
Doc/Manual/SWIG.html
View file

@ -13,7 +13,7 @@
<li><a href="#SWIG_nn2">Running SWIG</a>
<ul>
<li><a href="#SWIG_nn3">Input format</a>
<li><a href="#output">SWIG Output</a>
<li><a href="#SWIG_output">SWIG Output</a>
<li><a href="#SWIG_nn5">Comments</a>
<li><a href="#SWIG_nn6">C Preprocessor</a>
<li><a href="#SWIG_nn7">SWIG Directives</a>
@ -92,7 +92,7 @@ chapters.
<p>
To run SWIG, use the <tt>swig</tt> command with options options and a filename like this:
To run SWIG, use the <tt>swig</tt> command with options and a filename like this:
</p>
<div class="shell"><pre>
@ -113,6 +113,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-clisp Generate CLISP wrappers
-cffi Generate CFFI wrappers
-csharp Generate C# wrappers
-go Generate Go wrappers
-guile Generate Guile wrappers
-java Generate Java wrappers
-lua Generate Lua wrappers
@ -193,7 +194,7 @@ semantics in SWIG is analogous to that of the declarations section
used in input files to parser generation tools such as yacc or bison.
</p>
<H3><a name="output"></a>5.1.2 SWIG Output</H3>
<H3><a name="SWIG_output"></a>5.1.2 SWIG Output</H3>
<p>
@ -1618,7 +1619,7 @@ double y; // Read-write
<p>
The <tt>%mutable</tt> and <tt>%immutable</tt> directives are actually
<a href="Customization.html#features">%feature directives</a> defined like this:
<a href="Customization.html#Customization_features">%feature directives</a> defined like this:
</p>
<div class="code"><pre>
@ -1672,7 +1673,7 @@ directive as shown :</p>
// interface.i
%rename(my_print) print;
extern void print(char *);
extern void print(const char *);
%rename(foo) a_really_long_and_annoying_name;
extern int a_really_long_and_annoying_name;
@ -1725,9 +1726,10 @@ to ignore declarations that match a given identifier. For example:
<div class="code">
<pre>
%ignore print; // Ignore all declarations named print
%ignore _HAVE_FOO_H; // Ignore an include guard constant
%ignore MYMACRO; // Ignore a macro
...
%include "foo.h" // Grab a header file
#define MYMACRO 123
void print(const char *);
...
</pre>
</div>
@ -1742,7 +1744,7 @@ declarations. If you need to remove a whole section of problematic code, the SW
<p>
More powerful variants of <tt>%rename</tt> and <tt>%ignore</tt> directives can be used to help
wrap C++ overloaded functions and methods or C++ methods which use default arguments. This is described in the
<a href="SWIGPlus.html#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
<a href="SWIGPlus.html#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<p>
@ -1752,7 +1754,7 @@ For example:
<div class="code">
<pre>
%name(output) extern void print(char *);
%name(output) extern void print(const char *);
</pre>
</div>

108
Doc/Manual/SWIGPlus.html
View file

@ -42,18 +42,21 @@
<ul>
<li><a href="#SWIGPlus_nn24">Dispatch function generation</a>
<li><a href="#SWIGPlus_nn25">Ambiguity in Overloading</a>
<li><a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a>
<li><a href="#SWIGPlus_nn27">Comments on overloading</a>
</ul>
<li><a href="#SWIGPlus_nn28">Wrapping overloaded operators</a>
<li><a href="#SWIGPlus_class_extension">Class extension</a>
<li><a href="#SWIGPlus_nn30">Templates</a>
<li><a href="#SWIGPlus_nn31">Namespaces</a>
<li><a href="#SWIGPlus_namespaces">Namespaces</a>
<ul>
<li><a href="#SWIGPlus_nspace">The nspace feature for namespaces</a>
</ul>
<li><a href="#SWIGPlus_renaming_templated_types_namespaces">Renaming templated types in namespaces</a>
<li><a href="#SWIGPlus_exception_specifications">Exception specifications</a>
<li><a href="#SWIGPlus_catches">Exception handling with %catches</a>
<li><a href="#SWIGPlus_nn33">Pointers to Members</a>
<li><a href="#SWIGPlus_nn34">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_smart_pointers">Smart pointers and operator-&gt;()</a>
<li><a href="#SWIGPlus_nn35">Using declarations and inheritance</a>
<li><a href="#SWIGPlus_nested_classes">Nested classes</a>
<li><a href="#SWIGPlus_const">A brief rant about const-correctness</a>
@ -1125,7 +1128,7 @@ For example if a method has ten default arguments, then eleven wrapper methods a
<p>
Please see the <a href="Customization.html#Customization_features_default_args">Features and default arguments</a>
section for more information on using <tt>%feature</tt> with functions with default arguments.
The <a href="#ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
The <a href="#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section
also deals with using <tt>%rename</tt> and <tt>%ignore</tt> on methods with default arguments.
If you are writing your own typemaps for types used in methods with default arguments, you may also need to write a <tt>typecheck</tt> typemap.
See the <a href="Typemaps.html#Typemaps_overloading">Typemaps and overloading</a> section for details or otherwise
@ -2124,7 +2127,7 @@ it means that the target language module has not yet implemented support for ove
functions and methods. The only way to fix the problem is to read the next section.
</p>
<H3><a name="ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<H3><a name="SWIGPlus_ambiguity_resolution_renaming"></a>6.15.3 Ambiguity resolution and renaming</H3>
<p>
@ -3647,12 +3650,16 @@ as the class name. For example:
Similar changes apply to typemaps and other customization features.
</p>
<H2><a name="SWIGPlus_nn31"></a>6.19 Namespaces</H2>
<H2><a name="SWIGPlus_namespaces"></a>6.19 Namespaces</H2>
<p>
Support for C++ namespaces is a relatively late addition to SWIG,
first appearing in SWIG-1.3.12. Before describing the implementation,
Support for C++ namespaces is comprehensive, but by default simple, however,
some target languages can turn on more advanced namespace support via the
<a href="#SWIGPlus_nspace">nspace feature</a>, described later.
Code within unnamed namespaces is ignored as there is no external
access to symbols declared within the unnamed namespace.
Before detailing the default implementation for named namespaces,
it is worth noting that the semantics of C++ namespaces is extremely
non-trivial--especially with regard to the C++ type system and class
machinery. At a most basic level, namespaces are sometimes used to
@ -4092,6 +4099,87 @@ with any namespace awareness. In the future, language modules may or may not p
more advanced namespace support.
</p>
<H3><a name="SWIGPlus_nspace"></a>6.19.1 The nspace feature for namespaces</H3>
<p>
Some target languages provide support for the <tt>nspace</tt> <a href="Customization.html#Customization_features">feature</a>.
The feature can be applied to any class, struct, union or enum declared within a named namespace.
The feature wraps the type within the target language specific concept of a namespace,
for example, a Java package or C# namespace.
Please see the language specific sections to see if the target language you are interested in supports the nspace feature.
</p>
<p>
The feature is demonstrated below for C# using the following example:
</p>
<div class="code">
<pre>
%feature("nspace") MyWorld::Material::Color;
%nspace MyWorld::Wrapping::Color; // %nspace is a macro for %feature("nspace")
namespace MyWorld {
namespace Material {
class Color {
...
};
}
namespace Wrapping {
class Color {
...
};
}
}
</pre>
</div>
<p>
Without the <tt>nspace</tt> feature directives above or <tt>%rename</tt>, you would get the following warning resulting in just one of the <tt>Color</tt> classes being available for use from the target language:
</p>
<div class="shell">
<pre>
example.i:9: Error: 'Color' is multiply defined in the generated target language module.
example.i:5: Error: Previous declaration of 'Color'
</pre>
</div>
<p>
With the <tt>nspace</tt> feature the two <tt>Color</tt> classes are wrapped into the equivalent C# namespaces.
A fully qualified constructor call of each these two types in C# is then:
</p>
<div class="targetlang">
<pre>
MyWorld.Material.Color materialColor = new MyWorld.Material.Color();
MyWorld.Wrapping.Color wrappingColor = new MyWorld.Wrapping.Color();
</pre>
</div>
<p>
Note that the <tt>nspace</tt> feature does not apply to variables and functions simply declared in a namespace. For example, the following symbols cannot co-exist in the target language without renaming. This may change in a future version.
</p>
<div class="code">
<pre>
namespace MyWorld {
namespace Material {
int quantity;
void dispatch();
}
namespace Wrapping {
int quantity;
void dispatch();
}
}
</pre>
</div>
<p>
<b>Compatibility Note:</b> The nspace feature was first introduced in SWIG-2.0.0.
</p>
<H2><a name="SWIGPlus_renaming_templated_types_namespaces"></a>6.20 Renaming templated types in namespaces</H2>
@ -4216,7 +4304,7 @@ is outlined in the <a href="Typemaps.html#throws_typemap">"throws" typemap</a> s
<p>
Since exception specifications are sometimes only used sparingly, this alone may not be enough to
properly handle C++ exceptions. To do that, a different set of special SWIG directives are used.
Consult the "<a href="Customization.html#exception">Exception handling with %exception</a>" section for details.
Consult the "<a href="Customization.html#Customization_exception">Exception handling with %exception</a>" section for details.
The next section details a way of simulating an exception specification or replacing an existing one.
</p>
@ -4320,7 +4408,7 @@ when checking types. However, no such support is currently provided
for member pointers.
</p>
<H2><a name="SWIGPlus_nn34"></a>6.24 Smart pointers and operator-&gt;()</H2>
<H2><a name="SWIGPlus_smart_pointers"></a>6.24 Smart pointers and operator-&gt;()</H2>
<p>

36
Doc/Manual/Sections.html
View file

@ -1,23 +1,15 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-1.3 Development Documentation</H1>
<H1><a name="Sections"></a>SWIG-2.0 Documentation</H1>
Last update : SWIG-2.0.0 (in progress)
Last update : SWIG-2.0.1 (in progress)
<H2>Sections</H2>
<p>
The SWIG documentation is being updated to reflect new SWIG
features and enhancements. However, this update process is not quite
finished--there is a lot of old SWIG-1.1 documentation and it is taking
some time to update all of it. Please pardon our dust (or volunteer
to help!).
</p>
<H3>SWIG Core Documentation</H3>
<ul>
<li><a href="Preface.html#Preface">Preface</a></li>
@ -41,13 +33,14 @@ to help!).
<H3>Language Module Documentation</H3>
<ul>
<li><a href="Allegrocl.html#Allegrocl_nn1">Allegro CL support</a></li>
<li><a href="Allegrocl.html#Allegrocl">Allegro CL support</a></li>
<li><a href="CSharp.html#CSharp">C# support</a></li>
<li><a href="Chicken.html#Chicken">Chicken support</a></li>
<li><a href="Go.html#Go">Go support</a></li>
<li><a href="Guile.html#Guile">Guile support</a></li>
<li><a href="Java.html#Java">Java support</a></li>
<li><a href="Lua.html#Lua_nn1">Lua support</a></li>
<li><a href="Lisp.html#Lisp_nn1">Common Lisp support</a></li>
<li><a href="Lua.html#Lua">Lua support</a></li>
<li><a href="Lisp.html#Lisp">Common Lisp support</a></li>
<li><a href="Modula3.html#Modula3">Modula3 support</a></li>
<li><a href="Mzscheme.html#MzScheme">MzScheme support</a></li>
<li><a href="Ocaml.html#Ocaml">Ocaml support</a></li>
@ -67,20 +60,5 @@ to help!).
<li><a href="Extending.html#Extending">Extending SWIG</a></li>
</ul>
<H3>Documentation that has not yet been updated</H3>
<p>
This documentation has not been completely updated from SWIG-1.1, but most of the topics
still apply to the current release. Make sure you read the
<a href="SWIG.html#SWIG">SWIG Basics</a> chapter before reading
any of these chapters. Also, SWIG-1.3.10 features extensive changes to the
implementation of typemaps. Make sure you read the <a href="Typemaps.html#Typemaps">Typemaps</a>
chapter above if you are using this feature.
</p>
<ul>
<li><a href="Advanced.html#Advanced">Advanced topics</a> (see <a href="Modules.html#Modules">Modules</a> for updated information).</li>
</ul>
</body>
</html>

92
Doc/Manual/Tcl.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl"></a>33 SWIG and Tcl</H1>
<H1><a name="Tcl"></a>34 SWIG and Tcl</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -83,7 +83,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
</p>
<H2><a name="Tcl_nn2"></a>33.1 Preliminaries</H2>
<H2><a name="Tcl_nn2"></a>34.1 Preliminaries</H2>
<p>
@ -109,7 +109,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3"></a>33.1.1 Getting the right header files</H3>
<H3><a name="Tcl_nn3"></a>34.1.1 Getting the right header files</H3>
<p>
@ -127,7 +127,7 @@ this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt
header file.
</p>
<H3><a name="Tcl_nn4"></a>33.1.2 Compiling a dynamic module</H3>
<H3><a name="Tcl_nn4"></a>34.1.2 Compiling a dynamic module</H3>
<p>
@ -162,7 +162,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the
<tt> -module</tt> command line option.
</p>
<H3><a name="Tcl_nn5"></a>33.1.3 Static linking</H3>
<H3><a name="Tcl_nn5"></a>34.1.3 Static linking</H3>
<p>
@ -228,7 +228,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6"></a>33.1.4 Using your module</H3>
<H3><a name="Tcl_nn6"></a>34.1.4 Using your module</H3>
<p>
@ -356,7 +356,7 @@ to the default system configuration (this requires root access and you will need
the man pages).
</p>
<H3><a name="Tcl_nn7"></a>33.1.5 Compilation of C++ extensions</H3>
<H3><a name="Tcl_nn7"></a>34.1.5 Compilation of C++ extensions</H3>
<p>
@ -439,7 +439,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8"></a>33.1.6 Compiling for 64-bit platforms</H3>
<H3><a name="Tcl_nn8"></a>34.1.6 Compiling for 64-bit platforms</H3>
<p>
@ -466,7 +466,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9"></a>33.1.7 Setting a package prefix</H3>
<H3><a name="Tcl_nn9"></a>34.1.7 Setting a package prefix</H3>
<p>
@ -485,7 +485,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10"></a>33.1.8 Using namespaces</H3>
<H3><a name="Tcl_nn10"></a>34.1.8 Using namespaces</H3>
<p>
@ -507,7 +507,7 @@ When the<tt> -namespace</tt> option is used, objects in the module
are always accessed with the namespace name such as <tt>Foo::bar</tt>.
</p>
<H2><a name="Tcl_nn11"></a>33.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<H2><a name="Tcl_nn11"></a>34.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<p>
@ -518,7 +518,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12"></a>33.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Tcl_nn12"></a>34.2.1 Running SWIG from Developer Studio</H3>
<p>
@ -576,7 +576,7 @@ MSDOS &gt; tclsh80
%
</pre></div>
<H3><a name="Tcl_nn13"></a>33.2.2 Using NMAKE</H3>
<H3><a name="Tcl_nn13"></a>34.2.2 Using NMAKE</H3>
<p>
@ -639,7 +639,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14"></a>33.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Tcl_nn14"></a>34.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -650,7 +650,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15"></a>33.3.1 Modules</H3>
<H3><a name="Tcl_nn15"></a>34.3.1 Modules</H3>
<p>
@ -684,7 +684,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</div>
<H3><a name="Tcl_nn16"></a>33.3.2 Functions</H3>
<H3><a name="Tcl_nn16"></a>34.3.2 Functions</H3>
<p>
@ -709,7 +709,7 @@ like you think it does:
%
</pre></div>
<H3><a name="Tcl_nn17"></a>33.3.3 Global variables</H3>
<H3><a name="Tcl_nn17"></a>34.3.3 Global variables</H3>
<p>
@ -789,7 +789,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</div>
<H3><a name="Tcl_nn18"></a>33.3.4 Constants and enums</H3>
<H3><a name="Tcl_nn18"></a>34.3.4 Constants and enums</H3>
<p>
@ -873,7 +873,7 @@ When an identifier name is given, it is used to perform an implicit hash-table l
conversion. This allows the <tt>global</tt> statement to be omitted.
</p>
<H3><a name="Tcl_nn19"></a>33.3.5 Pointers</H3>
<H3><a name="Tcl_nn19"></a>34.3.5 Pointers</H3>
<p>
@ -969,7 +969,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20"></a>33.3.6 Structures</H3>
<H3><a name="Tcl_nn20"></a>34.3.6 Structures</H3>
<p>
@ -1251,7 +1251,7 @@ Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
</p>
<H3><a name="Tcl_nn21"></a>33.3.7 C++ classes</H3>
<H3><a name="Tcl_nn21"></a>34.3.7 C++ classes</H3>
<p>
@ -1318,7 +1318,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</div>
<H3><a name="Tcl_nn22"></a>33.3.8 C++ inheritance</H3>
<H3><a name="Tcl_nn22"></a>34.3.8 C++ inheritance</H3>
<p>
@ -1367,7 +1367,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23"></a>33.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Tcl_nn23"></a>34.3.9 Pointers, references, values, and arrays</H3>
<p>
@ -1421,7 +1421,7 @@ to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
</p>
<H3><a name="Tcl_nn24"></a>33.3.10 C++ overloaded functions</H3>
<H3><a name="Tcl_nn24"></a>34.3.10 C++ overloaded functions</H3>
<p>
@ -1544,7 +1544,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25"></a>33.3.11 C++ operators</H3>
<H3><a name="Tcl_nn25"></a>34.3.11 C++ operators</H3>
<p>
@ -1646,7 +1646,7 @@ There are ways to make this operator appear as part of the class using the <tt>%
Keep reading.
</p>
<H3><a name="Tcl_nn26"></a>33.3.12 C++ namespaces</H3>
<H3><a name="Tcl_nn26"></a>34.3.12 C++ namespaces</H3>
<p>
@ -1710,7 +1710,7 @@ utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
</p>
<H3><a name="Tcl_nn27"></a>33.3.13 C++ templates</H3>
<H3><a name="Tcl_nn27"></a>34.3.13 C++ templates</H3>
<p>
@ -1762,7 +1762,7 @@ More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</
examples will appear later.
</p>
<H3><a name="Tcl_nn28"></a>33.3.14 C++ Smart Pointers</H3>
<H3><a name="Tcl_nn28"></a>34.3.14 C++ Smart Pointers</H3>
<p>
@ -1846,7 +1846,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</div>
<H2><a name="Tcl_nn29"></a>33.4 Further details on the Tcl class interface</H2>
<H2><a name="Tcl_nn29"></a>34.4 Further details on the Tcl class interface</H2>
<p>
@ -1859,7 +1859,7 @@ of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
</p>
<H3><a name="Tcl_nn30"></a>33.4.1 Proxy classes</H3>
<H3><a name="Tcl_nn30"></a>34.4.1 Proxy classes</H3>
<p>
@ -1924,7 +1924,7 @@ function. This allows objects to be encapsulated objects that look a lot like
as shown in the last section.
</p>
<H3><a name="Tcl_nn31"></a>33.4.2 Memory management</H3>
<H3><a name="Tcl_nn31"></a>34.4.2 Memory management</H3>
<p>
@ -2112,7 +2112,7 @@ typemaps--an advanced topic discussed later.
</p>
<H2><a name="Tcl_nn32"></a>33.5 Input and output parameters</H2>
<H2><a name="Tcl_nn32"></a>34.5 Input and output parameters</H2>
<p>
@ -2300,7 +2300,7 @@ set c [lindex $dim 1]
</pre>
</div>
<H2><a name="Tcl_nn33"></a>33.6 Exception handling </H2>
<H2><a name="Tcl_nn33"></a>34.6 Exception handling </H2>
<p>
@ -2434,7 +2434,7 @@ Since SWIG's exception handling is user-definable, you are not limited to C++ ex
See the chapter on "<a href="Customization.html#Customization">Customization Features</a>" for more examples.
</p>
<H2><a name="Tcl_nn34"></a>33.7 Typemaps</H2>
<H2><a name="Tcl_nn34"></a>34.7 Typemaps</H2>
<p>
@ -2451,7 +2451,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35"></a>33.7.1 What is a typemap?</H3>
<H3><a name="Tcl_nn35"></a>34.7.1 What is a typemap?</H3>
<p>
@ -2568,7 +2568,7 @@ parameter is omitted):
</pre>
</div>
<H3><a name="Tcl_nn36"></a>33.7.2 Tcl typemaps</H3>
<H3><a name="Tcl_nn36"></a>34.7.2 Tcl typemaps</H3>
<p>
@ -2706,7 +2706,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37"></a>33.7.3 Typemap variables</H3>
<H3><a name="Tcl_nn37"></a>34.7.3 Typemap variables</H3>
<p>
@ -2777,7 +2777,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</div>
<H3><a name="Tcl_nn38"></a>33.7.4 Converting a Tcl list to a char ** </H3>
<H3><a name="Tcl_nn38"></a>34.7.4 Converting a Tcl list to a char ** </H3>
<p>
@ -2839,7 +2839,7 @@ argv[2] = Larry
3
</pre></div>
<H3><a name="Tcl_nn39"></a>33.7.5 Returning values in arguments</H3>
<H3><a name="Tcl_nn39"></a>34.7.5 Returning values in arguments</H3>
<p>
@ -2881,7 +2881,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></div>
<H3><a name="Tcl_nn40"></a>33.7.6 Useful functions</H3>
<H3><a name="Tcl_nn40"></a>34.7.6 Useful functions</H3>
<p>
@ -2958,7 +2958,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</div>
<H3><a name="Tcl_nn41"></a>33.7.7 Standard typemaps</H3>
<H3><a name="Tcl_nn41"></a>34.7.7 Standard typemaps</H3>
<p>
@ -3042,7 +3042,7 @@ work)
</pre>
</div>
<H3><a name="Tcl_nn42"></a>33.7.8 Pointer handling</H3>
<H3><a name="Tcl_nn42"></a>34.7.8 Pointer handling</H3>
<p>
@ -3118,7 +3118,7 @@ For example:
</pre>
</div>
<H2><a name="Tcl_nn43"></a>33.8 Turning a SWIG module into a Tcl Package.</H2>
<H2><a name="Tcl_nn43"></a>34.8 Turning a SWIG module into a Tcl Package.</H2>
<p>
@ -3190,7 +3190,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44"></a>33.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<H2><a name="Tcl_nn44"></a>34.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<p>
@ -3289,7 +3289,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45"></a>33.9.1 Proxy classes</H3>
<H3><a name="Tcl_nn45"></a>34.9.1 Proxy classes</H3>
<p>
@ -3410,7 +3410,7 @@ short, but clever Tcl script can be combined with SWIG to do many
interesting things.
</p>
<H2><a name="Tcl_nn46"></a>33.10 Tcl/Tk Stubs</H2>
<H2><a name="Tcl_nn46"></a>34.10 Tcl/Tk Stubs</H2>
<p>

851
Doc/Manual/Typemaps.html
View file

File diff suppressed because it is too large Load diff

2
Doc/Manual/Warnings.html
View file

@ -102,7 +102,7 @@ int foo(double); // Silently ignored.
<p>
The <tt>%warnfilter</tt> directive has the same semantics as other declaration modifiers like
<tt>%rename</tt>, <tt>%ignore</tt> and <tt>%feature</tt>, see the
<a href="Customization.html#features">%feature directive</a> section. For example, if you wanted to
<a href="Customization.html#Customization_features">%feature directive</a> section. For example, if you wanted to
suppress a warning for a method in a class hierarchy, you could do this:
</p>

6
Doc/Manual/Windows.html
View file

@ -67,7 +67,7 @@ SWIG does not come with the usual Windows type installation program, however it
<p>
The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95/98/ME/NT/2000/XP.
The swigwin distribution contains the SWIG Windows executable, swig.exe, which will run on 32 bit versions of Windows, ie Windows 95 and later.
If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe">Building swig.exe on Windows</a>.
</p>
@ -78,7 +78,7 @@ If you want to build your own swig.exe have a look at <a href="#Windows_swig_exe
<p>
Using Microsoft Visual C++ is the most common approach to compiling and linking SWIG's output.
The Examples directory has a few Visual C++ project files (.dsp files).
These were produced by Visual C++ 6, although they should also work in Visual C++ 5.
These were produced by Visual C++ 6.
Later versions of Visual Studio should also be able to open and convert these project files.
The C# examples come with .NET 2003 solution (.sln) and project files instead of Visual C++ 6 project files.
The project files have been set up to execute SWIG in a custom build rule for the SWIG interface (.i) file.
@ -272,7 +272,7 @@ Execute the steps in the order shown and don't use spaces in path names. In fact
<ul>
<li>Answer y to the "do you wish to continue with the post install?"</li>
<li>Answer y to the "do you have MinGW installed?"</li>
<li>Type in the the folder in which you installed MinGW (C:/MinGW is default)</li>
<li>Type in the folder in which you installed MinGW (C:/MinGW is default)</li>
</ul>
</li>

1
Doc/Manual/chapters
View file

@ -18,6 +18,7 @@ CCache.html
Allegrocl.html
CSharp.html
Chicken.html
Go.html
Guile.html
Java.html
Lisp.html

4
Doc/Manual/index.html
View file

@ -1,10 +1,10 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG-1.3 Documentation</title>
<title>SWIG-2.0 Documentation</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="index"></a>SWIG-1.3 Development Documentation</h1>
<H1><a name="index"></a>SWIG-2.0 Documentation</h1>
The SWIG documentation is available in one of the following formats.
<ul>