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

Merge from trunk

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2009-sploving@12270 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Sylvestre Ledru 2010-10-14 14:15:42 +00:00
commit 1842244c93
530 changed files with 22854 additions and 11740 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Manual/Allegrocl.html
View file

@ -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>

35
Doc/Manual/CSharp.html
View file

@ -38,6 +38,7 @@
<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>
@ -511,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>
@ -2400,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>

117
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>
@ -153,6 +152,11 @@
<li><a href="SWIG.html#SWIG_nn26">Arrays</a>
<li><a href="SWIG.html#SWIG_readonly_variables">Creating read-only variables</a>
<li><a href="SWIG.html#SWIG_rename_ignore">Renaming and ignoring declarations</a>
<ul>
<li><a href="SWIG.html#SWIG_nn29">Simple renaming of specific identifiers</a>
<li><a href="SWIG.html#SWIG_advanced_renaming">Advanced renaming support</a>
<li><a href="SWIG.html#SWIG_limiting_renaming">Limiting global renaming rules</a>
</ul>
<li><a href="SWIG.html#SWIG_default_args">Default/optional arguments</a>
<li><a href="SWIG.html#SWIG_nn30">Pointers to functions and callbacks</a>
</ul>
@ -237,7 +241,7 @@
<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_const">A brief rant about const-correctness</a>
@ -288,9 +292,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>
@ -336,6 +341,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>
@ -351,8 +357,8 @@
<li><a href="Typemaps.html#Typemaps_nn17">Basic matching rules</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_matching_template_comparison">Matching comparison with C++ templates</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>
@ -488,7 +494,7 @@
<li><a href="Warnings.html#Warnings_nn12">C/C++ Parser (300-399)</a>
<li><a href="Warnings.html#Warnings_nn13">Types and typemaps (400-499) </a>
<li><a href="Warnings.html#Warnings_nn14">Code generation (500-599)</a>
<li><a href="Warnings.html#Warnings_nn15">Language module specific (800-899) </a>
<li><a href="Warnings.html#Warnings_nn15">Language module specific (700-899) </a>
<li><a href="Warnings.html#Warnings_nn16">User defined (900-999)</a>
</ul>
<li><a href="Warnings.html#Warnings_nn17">History</a>
@ -656,6 +662,7 @@
<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>
@ -699,7 +706,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">
@ -734,7 +770,7 @@
</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">
@ -876,7 +912,7 @@
</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">
@ -899,7 +935,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">
@ -956,17 +992,14 @@
</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_modula3_overview">Overview</a>
<ul>
<li><a href="Modula3.html#Modula3_whyscripting">Why not scripting ?</a>
<li><a href="Modula3.html#Modula3_whymodula3">Why Modula-3 ?</a>
<li><a href="Modula3.html#Modula3_whycpp">Why C / C++ ?</a>
<li><a href="Modula3.html#Modula3_whyswig">Why SWIG ?</a>
<li><a href="Modula3.html#Modula3_motivation">Motivation</a>
</ul>
<li><a href="Modula3.html#Modula3_conception">Conception</a>
<ul>
@ -997,7 +1030,7 @@
</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">
@ -1007,7 +1040,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">
@ -1058,7 +1091,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">
@ -1093,7 +1126,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">
@ -1160,7 +1193,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">
@ -1200,7 +1233,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">
@ -1224,7 +1257,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">
@ -1327,7 +1360,23 @@
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">32 SWIG and Ruby</a></h3>
<h3><a href="R.html#R">33 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="R.html#R_nn2">Bugs</a>
<li><a href="R.html#R_nn3">Using R and SWIG</a>
<li><a href="R.html#R_nn4">Precompiling large R files</a>
<li><a href="R.html#R_nn5">General policy</a>
<li><a href="R.html#R_language_conventions">Language conventions</a>
<li><a href="R.html#R_nn6">C++ classes</a>
<li><a href="R.html#R_nn7">Enumerations</a>
</ul>
</div>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">34 SWIG and Ruby</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1461,7 +1510,7 @@
</div>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">33 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html#Tcl">35 SWIG and Tcl</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
@ -1527,23 +1576,7 @@
</div>
<!-- INDEX -->
<h3><a href="R.html#R">34 SWIG and R</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="R.html#R_nn2">Bugs</a>
<li><a href="R.html#R_nn3">Using R and SWIG</a>
<li><a href="R.html#R_nn4">Precompiling large R files</a>
<li><a href="R.html#R_nn5">General policy</a>
<li><a href="R.html#R_language_conventions">Language conventions</a>
<li><a href="R.html#R_nn6">C++ classes</a>
<li><a href="R.html#R_nn7">Enumerations</a>
</ul>
</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">

4
Doc/Manual/Customization.html
View file

@ -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>
@ -775,7 +775,7 @@ involving <tt>%feature</tt>:
<p>
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.

110
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>
@ -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_configuration_files"></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 -->
@ -3193,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>
@ -3202,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>
@ -3221,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>
@ -3250,7 +3250,7 @@ during this process, see the section on <a href="#Extending_configuration_files"
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>
@ -3309,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>
@ -3469,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>
@ -3501,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>
@ -3558,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>
@ -3582,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>
@ -3601,13 +3609,15 @@ There are various command line options which can aid debugging a SWIG interface
-debug-top &lt;n&gt; - Display entire parse tree at stages 1-4, &lt;n&gt; is a csv list of stages
-debug-typedef - Display information about the types and typedefs in the interface
-debug-typemap - Display information for debugging typemaps
-debug-tmsearch - Display typemap search debugging information
-debug-tmused - Display typemaps used debugging information
</pre></div>
<p>
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>
@ -4015,7 +4025,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>

44
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
@ -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>
@ -412,7 +412,7 @@ constant will appear as a scheme variable. See
<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
@ -491,7 +491,7 @@ 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>

223
Doc/Manual/Java.html
View file

@ -5,7 +5,7 @@
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#FFFFFF">
<H1><a name="Java"></a>21 SWIG and Java</H1>
<H1><a name="Java"></a>22 SWIG and Java</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -154,7 +154,7 @@ It covers most SWIG features, but certain low-level details are covered in less
</p>
<H2><a name="Java_overview"></a>21.1 Overview</H2>
<H2><a name="Java_overview"></a>22.1 Overview</H2>
<p>
@ -166,7 +166,7 @@ SWIG wraps C/C++ code using Java proxy classes and is very useful if you want to
If only one or two JNI functions are needed then using SWIG may be overkill.
SWIG enables a Java program to easily call into C/C++ code from Java.
Historically, SWIG was not able to generate any code to call into Java code from C++.
However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods.
However, SWIG now supports full cross language polymorphism and code is generated to call up from C++ to Java when wrapping C++ virtual methods via the director feature.
</p>
<p>
@ -189,7 +189,7 @@ Various customisation tips and techniques using SWIG directives are covered.
The latter sections cover the advanced techniques of using typemaps for complete control of the wrapping process.
</p>
<H2><a name="Java_preliminaries"></a>21.2 Preliminaries</H2>
<H2><a name="Java_preliminaries"></a>22.2 Preliminaries</H2>
<p>
@ -205,7 +205,7 @@ Run <tt>make -k check</tt> from the SWIG root directory after installing SWIG on
The Java module requires your system to support shared libraries and dynamic loading.
This is the commonly used method to load JNI code so your system will more than likely support this.</p>
<H3><a name="Java_running_swig"></a>21.2.1 Running SWIG</H3>
<H3><a name="Java_running_swig"></a>22.2.1 Running SWIG</H3>
<p>
@ -264,7 +264,7 @@ The following sections have further practical examples and details on how you mi
compiling and using the generated files.
</p>
<H3><a name="Java_commandline"></a>21.2.2 Additional Commandline Options</H3>
<H3><a name="Java_commandline"></a>22.2.2 Additional Commandline Options</H3>
<p>
@ -301,7 +301,7 @@ swig -java -help
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
</p>
<H3><a name="Java_getting_right_headers"></a>21.2.3 Getting the right header files</H3>
<H3><a name="Java_getting_right_headers"></a>22.2.3 Getting the right header files</H3>
<p>
@ -316,7 +316,7 @@ They are usually in directories like this:</p>
<p>
The exact location may vary on your machine, but the above locations are typical. </p>
<H3><a name="Java_compiling_dynamic"></a>21.2.4 Compiling a dynamic module</H3>
<H3><a name="Java_compiling_dynamic"></a>22.2.4 Compiling a dynamic module</H3>
<p>
@ -352,7 +352,7 @@ The name of the shared library output file is important.
If the name of your SWIG module is "<tt>example</tt>", the name of the corresponding shared library file should be "<tt>libexample.so</tt>" (or equivalent depending on your machine, see <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a> for more information).
The name of the module is specified using the <tt>%module</tt> directive or<tt> -module</tt> command line option.</p>
<H3><a name="Java_using_module"></a>21.2.5 Using your module</H3>
<H3><a name="Java_using_module"></a>22.2.5 Using your module</H3>
<p>
@ -363,7 +363,7 @@ To load your shared native library module in Java, simply use Java's <tt>System.
public class runme {
static {
  System.loadLibrary("example");
  System.loadLibrary("example");
}
public static void main(String argv[]) {
@ -387,7 +387,7 @@ $
If it doesn't work have a look at the following section which discusses problems loading the shared library.
</p>
<H3><a name="Java_dynamic_linking_problems"></a>21.2.6 Dynamic linking problems</H3>
<H3><a name="Java_dynamic_linking_problems"></a>22.2.6 Dynamic linking problems</H3>
<p>
@ -474,7 +474,7 @@ The following section also contains some C++ specific linking problems and solut
</p>
<H3><a name="Java_compilation_problems_cpp"></a>21.2.7 Compilation problems and compiling with C++</H3>
<H3><a name="Java_compilation_problems_cpp"></a>22.2.7 Compilation problems and compiling with C++</H3>
<p>
@ -527,7 +527,7 @@ Finally make sure the version of JDK header files matches the version of Java th
</p>
<H3><a name="Java_building_windows"></a>21.2.8 Building on Windows</H3>
<H3><a name="Java_building_windows"></a>22.2.8 Building on Windows</H3>
<p>
@ -536,7 +536,7 @@ You will want to produce a DLL that can be loaded by the Java Virtual Machine.
This section covers the process of using SWIG with Microsoft Visual C++ 6 although the procedure may be similar with other compilers.
In order for everything to work, you will need to have a JDK installed on your machine in order to read the JNI header files.</p>
<H4><a name="Java_visual_studio"></a>21.2.8.1 Running SWIG from Visual Studio</H4>
<H4><a name="Java_visual_studio"></a>22.2.8.1 Running SWIG from Visual Studio</H4>
<p>
@ -575,7 +575,7 @@ To run the native code in the DLL (example.dll), make sure that it is in your pa
If the library fails to load have a look at <a href="#Java_dynamic_linking_problems">Dynamic linking problems</a>.
</p>
<H4><a name="Java_nmake"></a>21.2.8.2 Using NMAKE</H4>
<H4><a name="Java_nmake"></a>22.2.8.2 Using NMAKE</H4>
<p>
@ -634,7 +634,7 @@ Of course you may want to make changes for it to work for C++ by adding in the -
</p>
<H2><a name="Java_basic_tour"></a>21.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Java_basic_tour"></a>22.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -644,7 +644,7 @@ variables are wrapped with JavaBean type getters and setters and so forth.
This section briefly covers the essential aspects of this wrapping.
</p>
<H3><a name="Java_module_packages_classes"></a>21.3.1 Modules, packages and generated Java classes</H3>
<H3><a name="Java_module_packages_classes"></a>22.3.1 Modules, packages and generated Java classes</H3>
<p>
@ -680,7 +680,7 @@ swig -java -package com.bloggs.swig -outdir com/bloggs/swig example.i
SWIG won't create the directory, so make sure it exists beforehand.
</p>
<H3><a name="Java_functions"></a>21.3.2 Functions</H3>
<H3><a name="Java_functions"></a>22.3.2 Functions</H3>
<p>
@ -714,7 +714,7 @@ System.out.println(example.fact(4));
</pre></div>
<H3><a name="Java_global_variables"></a>21.3.3 Global variables</H3>
<H3><a name="Java_global_variables"></a>22.3.3 Global variables</H3>
<p>
@ -801,7 +801,7 @@ extern char *path; // Read-only (due to %immutable)
</div>
<H3><a name="Java_constants"></a>21.3.4 Constants</H3>
<H3><a name="Java_constants"></a>22.3.4 Constants</H3>
<p>
@ -941,7 +941,7 @@ Or if you decide this practice isn't so bad and your own class implements <tt>ex
</p>
<H3><a name="Java_enumerations"></a>21.3.5 Enumerations</H3>
<H3><a name="Java_enumerations"></a>22.3.5 Enumerations</H3>
<p>
@ -955,7 +955,7 @@ The final two approaches use simple integers for each enum item.
Before looking at the various approaches for wrapping named C/C++ enums, anonymous enums are considered.
</p>
<H4><a name="Java_anonymous_enums"></a>21.3.5.1 Anonymous enums</H4>
<H4><a name="Java_anonymous_enums"></a>22.3.5.1 Anonymous enums</H4>
<p>
@ -1018,7 +1018,7 @@ As in the case of constants, you can access them through either the module class
</p>
<H4><a name="Java_typesafe_enums"></a>21.3.5.2 Typesafe enums</H4>
<H4><a name="Java_typesafe_enums"></a>22.3.5.2 Typesafe enums</H4>
<p>
@ -1094,10 +1094,11 @@ C++ enums defined within a C++ class are generated into a static final inner Jav
</p>
<p>
Typesafe enums have their advantages over using plain integers in that they they can be used in a typesafe manner.
Typesafe enums have their advantages over using plain integers in that they can be used in a typesafe manner.
However, there are limitations. For example, they cannot be used in switch statements and serialization is an issue.
Please look at the following references for further information:
http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums
<a href="http://java.sun.com/developer/Books/shiftintojava/page1.html#replaceenums">Replace Enums with Classes</a> in <i>Effective Java Programming</i> on the Sun website,
<a href="http://www.javaworld.com/javaworld/jw-07-1997/jw-07-enumerated.html">Create enumerated constants in Java</a> JavaWorld article,
<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip133.html">Java Tip 133: More on typesafe enums</a> and
@ -1111,7 +1112,7 @@ When upgrading to JDK 1.5 or later, proper Java enums could be used instead, wit
The following section details proper Java enum generation.
</p>
<H4><a name="Java_proper_enums"></a>21.3.5.3 Proper Java enums</H4>
<H4><a name="Java_proper_enums"></a>22.3.5.3 Proper Java enums</H4>
<p>
@ -1164,7 +1165,7 @@ The additional support methods need not be generated if none of the enum items h
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section.
</p>
<H4><a name="Java_typeunsafe_enums"></a>21.3.5.4 Type unsafe enums</H4>
<H4><a name="Java_typeunsafe_enums"></a>22.3.5.4 Type unsafe enums</H4>
<p>
@ -1212,7 +1213,7 @@ Note that unlike typesafe enums, this approach requires users to mostly use diff
Thus the upgrade path to proper enums provided in JDK 1.5 is more painful.
</p>
<H4><a name="Java_simple_enums"></a>21.3.5.5 Simple enums</H4>
<H4><a name="Java_simple_enums"></a>22.3.5.5 Simple enums</H4>
<p>
@ -1231,7 +1232,7 @@ SWIG-1.3.21 and earlier versions wrapped all enums using this approach.
The type unsafe approach is preferable to this one and this simple approach is only included for backwards compatibility with these earlier versions of SWIG.
</p>
<H3><a name="Java_pointers"></a>21.3.6 Pointers</H3>
<H3><a name="Java_pointers"></a>22.3.6 Pointers</H3>
<p>
@ -1319,7 +1320,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
a NULL pointer if the conversion can't be performed.
</p>
<H3><a name="Java_structures"></a>21.3.7 Structures</H3>
<H3><a name="Java_structures"></a>22.3.7 Structures</H3>
<p>
@ -1487,7 +1488,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a
</div>
<H3><a name="Java_classes"></a>21.3.8 C++ classes</H3>
<H3><a name="Java_classes"></a>22.3.8 C++ classes</H3>
<p>
@ -1550,7 +1551,7 @@ int bar = Spam.getBar();
</div>
<H3><a name="Java_inheritance"></a>21.3.9 C++ inheritance</H3>
<H3><a name="Java_inheritance"></a>22.3.9 C++ inheritance</H3>
<p>
@ -1611,7 +1612,7 @@ Note that Java does not support multiple inheritance so any multiple inheritance
A warning is given when multiple inheritance is detected and only the first base class is used.
</p>
<H3><a name="Java_pointers_refs_arrays"></a>21.3.10 Pointers, references, arrays and pass by value</H3>
<H3><a name="Java_pointers_refs_arrays"></a>22.3.10 Pointers, references, arrays and pass by value</H3>
<p>
@ -1666,7 +1667,7 @@ to hold the result and a pointer is returned (Java will release this memory
when the returned object's finalizer is run by the garbage collector).
</p>
<H4><a name="Java_null_pointers"></a>21.3.10.1 Null pointers</H4>
<H4><a name="Java_null_pointers"></a>22.3.10.1 Null pointers</H4>
<p>
@ -1690,7 +1691,7 @@ For <tt>spam1</tt> and <tt>spam4</tt> above the Java <tt>null</tt> gets translat
The converse also occurs, that is, NULL pointers are translated into <tt>null</tt> Java objects when returned from a C/C++ function.
</p>
<H3><a name="Java_overloaded_functions"></a>21.3.11 C++ overloaded functions</H3>
<H3><a name="Java_overloaded_functions"></a>22.3.11 C++ overloaded functions</H3>
<p>
@ -1805,7 +1806,7 @@ void spam(unsigned short); // Ignored
</pre>
</div>
<H3><a name="Java_default_arguments"></a>21.3.12 C++ default arguments</H3>
<H3><a name="Java_default_arguments"></a>22.3.12 C++ default arguments</H3>
<p>
@ -1848,7 +1849,7 @@ Further details on default arguments and how to restore this approach are given
</p>
<H3><a name="Java_namespaces"></a>21.3.13 C++ namespaces</H3>
<H3><a name="Java_namespaces"></a>22.3.13 C++ namespaces</H3>
<p>
@ -1926,7 +1927,7 @@ with -package - Java does not support types declared in a named package accessin
</pre>
</div>
<H3><a name="Java_templates"></a>21.3.14 C++ templates</H3>
<H3><a name="Java_templates"></a>22.3.14 C++ templates</H3>
<p>
@ -1975,7 +1976,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter.
</p>
<H3><a name="Java_smart_pointers"></a>21.3.15 C++ Smart Pointers</H3>
<H3><a name="Java_smart_pointers"></a>22.3.15 C++ Smart Pointers</H3>
<p>
@ -2059,7 +2060,7 @@ Foo f = p.__deref__(); // Returns underlying Foo *
</pre>
</div>
<H2><a name="Java_further_details"></a>21.4 Further details on the generated Java classes</H2>
<H2><a name="Java_further_details"></a>22.4 Further details on the generated Java classes</H2>
<p>
@ -2074,7 +2075,7 @@ Finally enum classes are covered.
First, the crucial intermediary JNI class is considered.
</p>
<H3><a name="Java_imclass"></a>21.4.1 The intermediary JNI class</H3>
<H3><a name="Java_imclass"></a>22.4.1 The intermediary JNI class</H3>
<p>
@ -2194,7 +2195,7 @@ If <tt>name</tt> is the same as <tt>modulename</tt> then the module class name g
from <tt>modulename</tt> to <tt>modulenameModule</tt>.
</p>
<H4><a name="Java_imclass_pragmas"></a>21.4.1.1 The intermediary JNI class pragmas</H4>
<H4><a name="Java_imclass_pragmas"></a>22.4.1.1 The intermediary JNI class pragmas</H4>
<p>
@ -2270,10 +2271,10 @@ For example, let's change the intermediary JNI class access to just the default
</div>
<p>
All the methods in the intermediary JNI class will then not be be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions.
All the methods in the intermediary JNI class will then not be callable outside of the package as the method modifiers have been changed from public access to default access. This is useful if you want to prevent users calling these low level functions.
</p>
<H3><a name="Java_module_class"></a>21.4.2 The Java module class</H3>
<H3><a name="Java_module_class"></a>22.4.2 The Java module class</H3>
<p>
@ -2304,7 +2305,7 @@ example.egg(new Foo());
The primary reason for having the module class wrapping the calls in the intermediary JNI class is to implement static type checking. In this case only a <tt>Foo</tt> can be passed to the <tt>egg</tt> function, whereas any <tt>long</tt> can be passed to the <tt>egg</tt> function in the intermediary JNI class.
</p>
<H4><a name="Java_module_class_pragmas"></a>21.4.2.1 The Java module class pragmas</H4>
<H4><a name="Java_module_class_pragmas"></a>22.4.2.1 The Java module class pragmas</H4>
<p>
@ -2355,12 +2356,12 @@ See <a href="#Java_imclass_pragmas">The intermediary JNI class pragmas</a> secti
</p>
<H3><a name="Java_proxy_classes"></a>21.4.3 Java proxy classes</H3>
<H3><a name="Java_proxy_classes"></a>22.4.3 Java proxy classes</H3>
<p>
A Java proxy class is generated for each structure, union or C++ class that is wrapped.
Proxy classes have also been called <a href="http://java.sun.com/developer/JDCTechTips/2001/tt0612.html#tip2">peer classes</a>.
Proxy classes have also been called <a href="http://java.sun.com/docs/books/jni/html/stubs.html">peer classes</a>.
The default proxy class for our previous example looks like this:
</p>
@ -2431,7 +2432,7 @@ int y = f.spam(5, new Foo());
</pre>
</div>
<H4><a name="Java_memory_management"></a>21.4.3.1 Memory management</H4>
<H4><a name="Java_memory_management"></a>22.4.3.1 Memory management</H4>
<p>
@ -2593,7 +2594,7 @@ and
</p>
<H4><a name="Java_inheritance_mirroring"></a>21.4.3.2 Inheritance</H4>
<H4><a name="Java_inheritance_mirroring"></a>22.4.3.2 Inheritance</H4>
<p>
@ -2709,7 +2710,7 @@ However, true cross language polymorphism can be achieved using the <a href="#Ja
</p>
<H4><a name="Java_proxy_classes_gc"></a>21.4.3.3 Proxy classes and garbage collection</H4>
<H4><a name="Java_proxy_classes_gc"></a>22.4.3.3 Proxy classes and garbage collection</H4>
<p>
@ -2758,7 +2759,7 @@ You can encourage the garbage collector to call the finalizers, for example, add
}
</pre></div>
<p>Although this usually works, the documentation doesn't guarantee that <tt>runFinalization()</tt> will actually call the finalizers.
As the the shutdown hook is guaranteed you could also make a JNI call to clean up any resources that are being tracked by the C/C++ code.</p>
As the shutdown hook is guaranteed you could also make a JNI call to clean up any resources that are being tracked by the C/C++ code.</p>
</li>
<li>
@ -2792,7 +2793,7 @@ The section on <a href="#Java_typemaps">Java typemaps</a> details how to specify
See the <a href="http://www.devx.com/Java/Article/30192">How to Handle Java Finalization's Memory-Retention Issues</a> article for alternative approaches to managing memory by avoiding finalizers altogether.
</p>
<H4><a name="Java_pgcpp"></a>21.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</H4>
<H4><a name="Java_pgcpp"></a>22.4.3.4 The premature garbage collection prevention parameter for proxy class marshalling</H4>
<p>
@ -2914,7 +2915,7 @@ For example:
<b>Compatibility note:</b> The generation of this additional parameter did not occur in versions prior to SWIG-1.3.30.
</p>
<H4><a name="Java_multithread_libraries"></a>21.4.3.5 Single threaded applications and thread safety</H4>
<H4><a name="Java_multithread_libraries"></a>22.4.3.5 Single threaded applications and thread safety</H4>
<p>
@ -3002,7 +3003,7 @@ for (int i=0; i&lt;100000; i++) {
</pre></div>
<H3><a name="Java_type_wrapper_classes"></a>21.4.4 Type wrapper classes</H3>
<H3><a name="Java_type_wrapper_classes"></a>22.4.4 Type wrapper classes</H3>
<p>
@ -3089,7 +3090,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
</div>
<H3><a name="Java_enum_classes"></a>21.4.5 Enum classes</H3>
<H3><a name="Java_enum_classes"></a>22.4.5 Enum classes</H3>
<p>
@ -3098,7 +3099,7 @@ The <a href="#Java_enumerations">Enumerations</a> section discussed these but om
The following sub-sections detail the various types of enum classes that can be generated.
</p>
<H4><a name="Java_typesafe_enums_classes"></a>21.4.5.1 Typesafe enum classes</H4>
<H4><a name="Java_typesafe_enums_classes"></a>22.4.5.1 Typesafe enum classes</H4>
<p>
@ -3182,7 +3183,7 @@ The <tt>swigValue</tt> method is used for marshalling in the other direction.
The <tt>toString</tt> method is overridden so that the enum name is available.
</p>
<H4><a name="Java_proper_enums_classes"></a>21.4.5.2 Proper Java enum classes</H4>
<H4><a name="Java_proper_enums_classes"></a>22.4.5.2 Proper Java enum classes</H4>
<p>
@ -3260,7 +3261,7 @@ These needn't be generated if the enum being wrapped does not have any initializ
<a href="#Java_simpler_enum_classes">Simpler Java enums for enums without initializers</a> section describes how typemaps can be used to achieve this.
</p>
<H4><a name="Java_typeunsafe_enums_classes"></a>21.4.5.3 Type unsafe enum classes</H4>
<H4><a name="Java_typeunsafe_enums_classes"></a>22.4.5.3 Type unsafe enum classes</H4>
<p>
@ -3291,7 +3292,7 @@ public final class Beverage {
</pre>
</div>
<H2><a name="Java_directors"></a>21.5 Cross language polymorphism using directors</H2>
<H2><a name="Java_directors"></a>22.5 Cross language polymorphism using directors</H2>
<p>
@ -3313,7 +3314,7 @@ The upshot is that C++ classes can be extended in Java and from C++ these extens
Neither C++ code nor Java code needs to know where a particular method is implemented: the combination of proxy classes, director classes, and C wrapper functions transparently takes care of all the cross-language method routing.
</p>
<H3><a name="Java_enabling_directors"></a>21.5.1 Enabling directors</H3>
<H3><a name="Java_enabling_directors"></a>22.5.1 Enabling directors</H3>
<p>
@ -3384,7 +3385,7 @@ public:
</pre>
</div>
<H3><a name="Java_directors_classes"></a>21.5.2 Director classes</H3>
<H3><a name="Java_directors_classes"></a>22.5.2 Director classes</H3>
<p>
@ -3411,7 +3412,7 @@ If the correct implementation is in Java, the Java API is used to call the metho
</p>
<H3><a name="Java_directors_overhead"></a>21.5.3 Overhead and code bloat</H3>
<H3><a name="Java_directors_overhead"></a>22.5.3 Overhead and code bloat</H3>
<p>
@ -3429,7 +3430,7 @@ This situation can be optimized by selectively enabling director methods (using
</p>
<H3><a name="Java_directors_example"></a>21.5.4 Simple directors example</H3>
<H3><a name="Java_directors_example"></a>22.5.4 Simple directors example</H3>
<p>
@ -3494,7 +3495,7 @@ DirectorDerived::upcall_method() invoked.
</pre>
</div>
<H3><a name="Java_directors_threading"></a>21.5.5 Director threading issues</H3>
<H3><a name="Java_directors_threading"></a>22.5.5 Director threading issues</H3>
<p>
@ -3514,7 +3515,7 @@ Macros can be defined on the commandline when compiling your C++ code, or altern
</pre>
</div>
<H2><a name="Java_allprotected"></a>21.6 Accessing protected members</H2>
<H2><a name="Java_allprotected"></a>22.6 Accessing protected members</H2>
<p>
@ -3610,7 +3611,7 @@ class MyProtectedBase extends ProtectedBase
<H2><a name="Java_common_customization"></a>21.7 Common customization features</H2>
<H2><a name="Java_common_customization"></a>22.7 Common customization features</H2>
<p>
@ -3622,7 +3623,7 @@ be awkward. This section describes some common SWIG features that are used
to improve the interface to existing C/C++ code.
</p>
<H3><a name="Java_helper_functions"></a>21.7.1 C/C++ helper functions</H3>
<H3><a name="Java_helper_functions"></a>22.7.1 C/C++ helper functions</H3>
<p>
@ -3688,7 +3689,7 @@ hard to implement. It is possible to improve on this using Java code, typemaps,
customization features as covered in later sections, but sometimes helper functions are a quick and easy solution to difficult cases.
</p>
<H3><a name="Java_class_extension"></a>21.7.2 Class extension with %extend</H3>
<H3><a name="Java_class_extension"></a>22.7.2 Class extension with %extend</H3>
<p>
@ -3751,7 +3752,7 @@ Vector(2,3,4)
in any way---the extensions only show up in the Java interface.
</p>
<H3><a name="Java_exception_handling"></a>21.7.3 Exception handling with %exception and %javaexception</H3>
<H3><a name="Java_exception_handling"></a>22.7.3 Exception handling with %exception and %javaexception</H3>
<p>
@ -3910,7 +3911,7 @@ to raise exceptions. See the <a href="Library.html#Library">SWIG Library</a> ch
The typemap example <a href="#Java_exception_typemap">Handling C++ exception specifications as Java exceptions</a> provides further exception handling capabilities.
</p>
<H3><a name="Java_method_access"></a>21.7.4 Method access with %javamethodmodifiers</H3>
<H3><a name="Java_method_access"></a>22.7.4 Method access with %javamethodmodifiers</H3>
<p>
@ -3936,7 +3937,7 @@ protected static void protect_me() {
</pre>
</div>
<H2><a name="Java_tips_techniques"></a>21.8 Tips and techniques</H2>
<H2><a name="Java_tips_techniques"></a>22.8 Tips and techniques</H2>
<p>
@ -3946,7 +3947,7 @@ strings and arrays. This chapter discusses the common techniques for
solving these problems.
</p>
<H3><a name="Java_input_output_parameters"></a>21.8.1 Input and output parameters using primitive pointers and references</H3>
<H3><a name="Java_input_output_parameters"></a>22.8.1 Input and output parameters using primitive pointers and references</H3>
<p>
@ -4120,7 +4121,7 @@ void foo(Bar *OUTPUT);
will not have the intended effect since <tt>typemaps.i</tt> does not define an OUTPUT rule for <tt>Bar</tt>.
</p>
<H3><a name="Java_simple_pointers"></a>21.8.2 Simple pointers</H3>
<H3><a name="Java_simple_pointers"></a>22.8.2 Simple pointers</H3>
<p>
@ -4186,7 +4187,7 @@ System.out.println("3 + 4 = " + result);
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
</p>
<H3><a name="Java_c_arrays"></a>21.8.3 Wrapping C arrays with Java arrays</H3>
<H3><a name="Java_c_arrays"></a>22.8.3 Wrapping C arrays with Java arrays</H3>
<p>
@ -4253,7 +4254,7 @@ Please be aware that the typemaps in this library are not efficient as all the e
There is an alternative approach using the SWIG array library and this is covered in the next section.
</p>
<H3><a name="Java_unbounded_c_arrays"></a>21.8.4 Unbounded C Arrays</H3>
<H3><a name="Java_unbounded_c_arrays"></a>22.8.4 Unbounded C Arrays</H3>
<p>
@ -4398,7 +4399,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
</p>
<H3><a name="Java_heap_allocations"></a>21.8.5 Overriding new and delete to allocate from Java heap</H3>
<H3><a name="Java_heap_allocations"></a>22.8.5 Overriding new and delete to allocate from Java heap</H3>
<p>
@ -4515,13 +4516,13 @@ model and use these functions in place of malloc and free in your own
code.
</p>
<H2><a name="Java_typemaps"></a>21.9 Java typemaps</H2>
<H2><a name="Java_typemaps"></a>22.9 Java 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.
You are advised to be familiar with the the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
You are advised to be familiar with the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" chapter.
While not absolutely essential knowledge, this section assumes some familiarity with the Java Native Interface (JNI).
JNI documentation can be consulted either online at <a href="http://java.sun.com">Sun's Java web site</a> or from a good JNI book.
The following two books are recommended:</p>
@ -4536,7 +4537,7 @@ Before proceeding, it should be stressed that typemaps are not a required
part of using SWIG---the default wrapping behavior is enough in most cases.
Typemaps are only used if you want to change some aspect of the generated code.
<H3><a name="Java_default_primitive_type_mappings"></a>21.9.1 Default primitive type mappings</H3>
<H3><a name="Java_default_primitive_type_mappings"></a>22.9.1 Default primitive type mappings</H3>
<p>
@ -4688,7 +4689,7 @@ However, the mappings allow the full range of values for each C type from Java.
</p>
<H3><a name="Java_default_non_primitive_typemaps"></a>21.9.2 Default typemaps for non-primitive types</H3>
<H3><a name="Java_default_non_primitive_typemaps"></a>22.9.2 Default typemaps for non-primitive types</H3>
<p>
@ -4703,7 +4704,7 @@ So in summary, the C/C++ pointer to non-primitive types is cast into the 64 bit
The Java type is either the proxy class or type wrapper class.
</p>
<H3><a name="Java_jvm64"></a>21.9.3 Sixty four bit JVMs</H3>
<H3><a name="Java_jvm64"></a>22.9.3 Sixty four bit JVMs</H3>
<p>
@ -4716,7 +4717,7 @@ Unfortunately it won't of course hold true for JNI code.
</p>
<H3><a name="Java_what_is_typemap"></a>21.9.4 What is a typemap?</H3>
<H3><a name="Java_what_is_typemap"></a>22.9.4 What is a typemap?</H3>
<p>
@ -4839,7 +4840,7 @@ int c = example.count('e',"Hello World");
</pre>
</div>
<H3><a name="Java_typemaps_c_to_java_types"></a>21.9.5 Typemaps for mapping C/C++ types to Java types</H3>
<H3><a name="Java_typemaps_c_to_java_types"></a>22.9.5 Typemaps for mapping C/C++ types to Java types</H3>
<p>
@ -5099,7 +5100,7 @@ These are listed below:
</table>
<H3><a name="Java_typemap_attributes"></a>21.9.6 Java typemap attributes</H3>
<H3><a name="Java_typemap_attributes"></a>22.9.6 Java typemap attributes</H3>
<p>
@ -5145,7 +5146,7 @@ The "javain" typemap has the optional 'pre', 'post' and 'pgcppname' attributes.
Note that when the 'pre' or 'post' attributes are specified and the associated type is used in a constructor, a constructor helper function is generated. This is necessary as the Java proxy constructor wrapper makes a call to a support constructor using a <i>this</i> call. In Java the <i>this</i> call must be the first statement in the constructor body. The constructor body thus calls the helper function and the helper function instead makes the JNI call, ensuring the 'pre' code is called before the JNI call is made. There is a <a href="#Java_date_marshalling">Date marshalling</a> example showing 'pre', 'post' and 'pgcppname' attributes in action.
</p>
<H3><a name="Java_special_variables"></a>21.9.7 Java special variables</H3>
<H3><a name="Java_special_variables"></a>22.9.7 Java special variables</H3>
<p>
@ -5296,7 +5297,7 @@ This special variable expands to the intermediary class name. Usually this is th
unless the jniclassname attribute is specified in the <a href="Java.html#Java_module_directive">%module directive</a>.
</p>
<H3><a name="Java_typemaps_for_c_and_cpp"></a>21.9.8 Typemaps for both C and C++ compilation</H3>
<H3><a name="Java_typemaps_for_c_and_cpp"></a>22.9.8 Typemaps for both C and C++ compilation</H3>
<p>
@ -5333,7 +5334,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps
</p>
<H3><a name="Java_code_typemaps"></a>21.9.9 Java code typemaps</H3>
<H3><a name="Java_code_typemaps"></a>22.9.9 Java code typemaps</H3>
<p>
@ -5539,7 +5540,7 @@ For the typemap to be used in all type wrapper classes, all the different types
Again this is the same that is in "<tt>java.swg</tt>", barring the method modifier for <tt>getCPtr</tt>.
</p>
<H3><a name="Java_directors_typemaps"></a>21.9.10 Director specific typemaps</H3>
<H3><a name="Java_directors_typemaps"></a>22.9.10 Director specific typemaps</H3>
<p>
@ -5764,7 +5765,7 @@ The basic strategy here is to provide a default package typemap for the majority
</div>
<H2><a name="Java_typemap_examples"></a>21.10 Typemap Examples</H2>
<H2><a name="Java_typemap_examples"></a>22.10 Typemap Examples</H2>
<p>
@ -5774,7 +5775,7 @@ the SWIG library.
</p>
<H3><a name="Java_simpler_enum_classes"></a>21.10.1 Simpler Java enums for enums without initializers</H3>
<H3><a name="Java_simpler_enum_classes"></a>22.10.1 Simpler Java enums for enums without initializers</H3>
<p>
@ -5853,7 +5854,7 @@ This would be done by using the original versions of these typemaps in "enums.sw
</p>
<H3><a name="Java_exception_typemap"></a>21.10.2 Handling C++ exception specifications as Java exceptions</H3>
<H3><a name="Java_exception_typemap"></a>22.10.2 Handling C++ exception specifications as Java exceptions</H3>
<p>
@ -5978,7 +5979,7 @@ We could alternatively have used <tt>%rename</tt> to rename <tt>what()</tt> into
</p>
<H3><a name="Java_nan_exception_typemap"></a>21.10.3 NaN Exception - exception handling for a particular type</H3>
<H3><a name="Java_nan_exception_typemap"></a>22.10.3 NaN Exception - exception handling for a particular type</H3>
<p>
@ -6133,7 +6134,7 @@ If we were a martyr to the JNI cause, we could replace the succinct code within
If we had, we would have put it in the "in" typemap which, like all JNI and Java typemaps, also supports the 'throws' attribute.
</p>
<H3><a name="Java_converting_java_string_arrays"></a>21.10.4 Converting Java String arrays to char ** </H3>
<H3><a name="Java_converting_java_string_arrays"></a>22.10.4 Converting Java String arrays to char ** </H3>
<p>
@ -6233,7 +6234,7 @@ public class runme {
static {
try {
  System.loadLibrary("example");
  System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
@ -6277,7 +6278,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify
what Java types to use.
</p>
<H3><a name="Java_expanding_java_object"></a>21.10.5 Expanding a Java object to multiple arguments</H3>
<H3><a name="Java_expanding_java_object"></a>22.10.5 Expanding a Java object to multiple arguments</H3>
<p>
@ -6359,7 +6360,7 @@ example.foo(new String[]{"red", "green", "blue", "white"});
</div>
<H3><a name="Java_using_typemaps_return_arguments"></a>21.10.6 Using typemaps to return arguments</H3>
<H3><a name="Java_using_typemaps_return_arguments"></a>22.10.6 Using typemaps to return arguments</H3>
<p>
@ -6452,7 +6453,7 @@ public class runme {
static {
try {
  System.loadLibrary("example");
  System.loadLibrary("example");
} catch (UnsatisfiedLinkError e) {
System.err.println("Native code library failed to load. " + e);
System.exit(1);
@ -6477,7 +6478,7 @@ $ java runme
1 12.0 340.0
</pre></div>
<H3><a name="Java_adding_downcasts"></a>21.10.7 Adding Java downcasts to polymorphic return types</H3>
<H3><a name="Java_adding_downcasts"></a>22.10.7 Adding Java downcasts to polymorphic return types</H3>
<p>
@ -6683,7 +6684,7 @@ SWIG usually generates code which constructs the proxy classes using Java code a
Note that the JNI code above uses a number of string lookups to call a constructor, whereas this would not occur using byte compiled Java code.
</p>
<H3><a name="Java_adding_equals_method"></a>21.10.8 Adding an equals method to the Java classes</H3>
<H3><a name="Java_adding_equals_method"></a>22.10.8 Adding an equals method to the Java classes</H3>
<p>
@ -6727,7 +6728,7 @@ System.out.println("foo1? " + foo1.equals(foo2));
</div>
<H3><a name="Java_void_pointers"></a>21.10.9 Void pointers and a common Java base class</H3>
<H3><a name="Java_void_pointers"></a>22.10.9 Void pointers and a common Java base class</H3>
<p>
@ -6786,7 +6787,7 @@ This example contains some useful functionality which you may want in your code.
<li> It also has a function which effectively implements a cast from the type of the proxy/type wrapper class to a void pointer. This is necessary for passing a proxy class or a type wrapper class to a function that takes a void pointer.
</ul>
<H3><a name="Java_struct_pointer_pointer"></a>21.10.10 Struct pointer to pointer</H3>
<H3><a name="Java_struct_pointer_pointer"></a>22.10.10 Struct pointer to pointer</H3>
<p>
@ -6966,7 +6967,7 @@ The C functional interface has been completely morphed into an object-oriented i
the Butler class would behave much like any pure Java class and feel more natural to Java users.
</p>
<H3><a name="Java_memory_management_member_variables"></a>21.10.11 Memory management when returning references to member variables</H3>
<H3><a name="Java_memory_management_member_variables"></a>22.10.11 Memory management when returning references to member variables</H3>
<p>
@ -7089,7 +7090,7 @@ public class Bike {
Note the <tt>addReference</tt> call.
</p>
<H3><a name="Java_memory_management_objects"></a>21.10.12 Memory management for objects passed to the C++ layer</H3>
<H3><a name="Java_memory_management_objects"></a>22.10.12 Memory management for objects passed to the C++ layer</H3>
<p>
@ -7205,7 +7206,7 @@ The 'javacode' typemap simply adds in the specified code into the Java proxy cla
</div>
<H3><a name="Java_date_marshalling"></a>21.10.13 Date marshalling using the javain typemap and associated attributes</H3>
<H3><a name="Java_date_marshalling"></a>22.10.13 Date marshalling using the javain typemap and associated attributes</H3>
<p>
@ -7382,7 +7383,7 @@ A few things to note:
<H2><a name="Java_directors_faq"></a>21.11 Living with Java Directors</H2>
<H2><a name="Java_directors_faq"></a>22.11 Living with Java Directors</H2>
<p>
@ -7563,10 +7564,10 @@ public abstract class UserVisibleFoo extends Foo {
</li>
</ol>
<H2><a name="Java_odds_ends"></a>21.12 Odds and ends</H2>
<H2><a name="Java_odds_ends"></a>22.12 Odds and ends</H2>
<H3><a name="Java_javadoc_comments"></a>21.12.1 JavaDoc comments</H3>
<H3><a name="Java_javadoc_comments"></a>22.12.1 JavaDoc comments</H3>
<p>
@ -7622,7 +7623,7 @@ public class Barmy {
<H3><a name="Java_functional_interface"></a>21.12.2 Functional interface without proxy classes</H3>
<H3><a name="Java_functional_interface"></a>22.12.2 Functional interface without proxy classes</H3>
<p>
@ -7683,7 +7684,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</
</p>
<H3><a name="Java_using_own_jni_functions"></a>21.12.3 Using your own JNI functions</H3>
<H3><a name="Java_using_own_jni_functions"></a>22.12.3 Using your own JNI functions</H3>
<p>
@ -7733,7 +7734,7 @@ This directive is only really useful if you want to mix your own hand crafted JN
</p>
<H3><a name="Java_performance"></a>21.12.4 Performance concerns and hints</H3>
<H3><a name="Java_performance"></a>22.12.4 Performance concerns and hints</H3>
<p>
@ -7754,7 +7755,7 @@ However, you will have to be careful about memory management and make sure that
This method normally calls the C++ destructor or <tt>free()</tt> for C code.
</p>
<H3><a name="Java_debugging"></a>21.12.5 Debugging</H3>
<H3><a name="Java_debugging"></a>22.12.5 Debugging</H3>
<p>
@ -7776,7 +7777,7 @@ The -verbose:jni and -verbose:gc are also useful options for monitoring code beh
</p>
<H2><a name="Java_examples"></a>21.13 Examples</H2>
<H2><a name="Java_examples"></a>22.13 Examples</H2>
<p>

140
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>
@ -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>

22
Doc/Manual/Lisp.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lisp"></a>22 SWIG and Common Lisp</H1>
<H1><a name="Lisp"></a>23 SWIG and Common Lisp</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
@ -41,7 +41,7 @@
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>
@ -50,7 +50,7 @@
<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>
@ -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
@ -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>

78
Doc/Manual/Lua.html
View file

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Lua"></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,7 +1099,7 @@ 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>
@ -1110,12 +1110,12 @@ 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
@ -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>

6
Doc/Manual/Makefile
View file

@ -15,7 +15,7 @@
# Note the # and " are escaped
HTMLDOC_OPTIONS = "--book --toclevels 4 --no-numbered --toctitle \"Table of Contents\" --title --titleimage swig16.png --linkcolor \#0000ff --linkstyle underline --size Universal --left 0.50in --right 0.50in --top 0.50in --bottom 0.50in --header .t. --footer h.1 --nup 1 --tocheader .t. --tocfooter ..i --portrait --color --no-pscommands --no-xrxcomments --compression=1 --jpeg=0 --fontsize 10.0 --fontspacing 1.2 --headingfont Helvetica --bodyfont Times --headfootsize 10.0 --headfootfont Helvetica --charset iso-8859-1 --links --no-embedfonts --pagemode outline --pagelayout single --firstpage c1 --pageeffect none --pageduration 10 --effectduration 1.0 --no-encryption --permissions all --owner-password \"\" --user-password \"\" --browserwidth 680"
.PHONY: maketoc check generate all clean validate test
.PHONY: maketoc check generate all maintainer-clean validate test
all: maketoc check generate
@ -38,13 +38,13 @@ generate: swightml.book swigpdf.book
htmldoc --batch swigpdf.book || true
python fixstyle.py SWIGDocumentation.html
swigpdf.book:
swigpdf.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swigpdf.book
echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) --stylesheet style.css >> swigpdf.book
echo "Sections.html" >> swigpdf.book
cat chapters >> swigpdf.book
swightml.book:
swightml.book: chapters Sections.html
echo "#HTMLDOC 1.8.24" > swightml.book
echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book
echo "Sections.html" >> swightml.book

231
Doc/Manual/Modula3.html
View file

@ -5,16 +5,13 @@
<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_modula3_overview">Overview</a>
<ul>
<li><a href="#Modula3_whyscripting">Why not scripting ?</a>
<li><a href="#Modula3_whymodula3">Why Modula-3 ?</a>
<li><a href="#Modula3_whycpp">Why C / C++ ?</a>
<li><a href="#Modula3_whyswig">Why SWIG ?</a>
<li><a href="#Modula3_motivation">Motivation</a>
</ul>
<li><a href="#Modula3_conception">Conception</a>
<ul>
@ -49,7 +46,7 @@
<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,
@ -57,16 +54,21 @@ especially
<a href="Typemaps.html#Typemaps">typemaps</a>.
</p>
<H2><a name="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_conception"></a>24.2 Conception</H2>
<H2><a name="Modula3_conception"></a>25.2 Conception</H2>
<H3><a name="Modula3_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="Modula3_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">
@ -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="Modula3_preliminaries"></a>24.3 Preliminaries</H2>
<H2><a name="Modula3_preliminaries"></a>25.3 Preliminaries</H2>
<H3><a name="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_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="Modula3_features"></a>24.5.1 Features</H3>
<H3><a name="Modula3_features"></a>25.5.1 Features</H3>
<table border summary="Modula-3 features">
@ -1029,7 +908,7 @@ where almost everything is generated by a typemap:
</tr>
</table>
<H3><a name="Modula3_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="Modula3_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>

4
Doc/Manual/Modules.html
View file

@ -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.
@ -244,7 +244,7 @@ is empty. Only modules compiled with the same pair will share type information.
<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>

94
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,7 +2916,7 @@ 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>
@ -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>

54
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>
@ -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>

2
Doc/Manual/Preprocessor.html
View file

@ -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

156
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>
@ -2190,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>
@ -2203,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>
@ -2292,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>
@ -2484,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>
@ -2521,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>
@ -2555,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>
@ -2648,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>
@ -2730,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>
@ -2782,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>
@ -2797,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>
@ -2856,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>
@ -2890,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>
@ -2904,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>
@ -2951,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>
@ -2964,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>
@ -3045,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>
@ -3101,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>
@ -3194,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>
@ -3283,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>
@ -3409,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>
@ -3419,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>
@ -3632,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>
@ -3701,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>
@ -3763,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>
@ -3832,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>
@ -3849,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>
@ -3965,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>
@ -4006,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>
@ -4077,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>
@ -4205,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>
@ -4214,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>
@ -4294,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>
@ -4373,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>
@ -4462,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>
@ -4511,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>
@ -4600,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>
@ -4697,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>
@ -4725,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>
@ -4759,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>
@ -4786,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>
@ -4815,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>
@ -4840,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>
@ -4859,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>
@ -4891,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>
@ -4918,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>
@ -4945,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>
@ -4977,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>
@ -5129,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>33 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>33.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>33.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>33.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>33.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>33.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>33.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>33.7 Enumerations</H2>
<p>

449
Doc/Manual/Ruby.html
View file

File diff suppressed because it is too large Load diff

316
Doc/Manual/SWIG.html
View file

@ -44,6 +44,11 @@
<li><a href="#SWIG_nn26">Arrays</a>
<li><a href="#SWIG_readonly_variables">Creating read-only variables</a>
<li><a href="#SWIG_rename_ignore">Renaming and ignoring declarations</a>
<ul>
<li><a href="#SWIG_nn29">Simple renaming of specific identifiers</a>
<li><a href="#SWIG_advanced_renaming">Advanced renaming support</a>
<li><a href="#SWIG_limiting_renaming">Limiting global renaming rules</a>
</ul>
<li><a href="#SWIG_default_args">Default/optional arguments</a>
<li><a href="#SWIG_nn30">Pointers to functions and callbacks</a>
</ul>
@ -92,7 +97,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 +118,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
@ -141,6 +147,7 @@ can be obtained by typing <tt>swig -help</tt> or <tt>swig
-o <em>outfile</em> Name of output file
-outcurrentdir Set default output dir to current dir instead of input file's path
-outdir <em>dir</em> Set language specific files output directory
-pcreversion Display PCRE version information
-swiglib Show location of SWIG library
-version Show SWIG version number
@ -1661,6 +1668,9 @@ generate a warning message. Simply change the directives to <tt>%immutable;</t
<H3><a name="SWIG_rename_ignore"></a>5.4.7 Renaming and ignoring declarations</H3>
<H4><a name="SWIG_nn29"></a>5.4.7.1 Simple renaming of specific identifiers</H4>
<p>
Normally, the name of a C declaration is used when that declaration is
wrapped into the target language. However, this may generate a
@ -1740,12 +1750,6 @@ to add conditional compilation to the header. However, it should be stressed t
declarations. If you need to remove a whole section of problematic code, the SWIG preprocessor should be used instead.
</p>
<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#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<p>
<b>Compatibility note: </b> Older versions of SWIG provided a special <tt>%name</tt> directive for renaming declarations.
For example:
@ -1762,6 +1766,298 @@ This directive is still supported, but it is deprecated and should probably be a
directive is more powerful and better supports wrapping of raw header file information.
</p>
<H4><a name="SWIG_advanced_renaming"></a>5.4.7.2 Advanced renaming support</H4>
<p>
While writing <tt>%rename</tt> for specific declarations is simple enough,
sometimes the same renaming rule needs to be applied to many, maybe all,
identifiers in the SWIG input. For example, it may be necessary to apply some
transformation to all the names in the target language to better follow its
naming conventions, like adding a specific prefix to all wrapped functions. Doing it individually
for each function is impractical so SWIG supports applying a renaming rule to
all declarations if the name of the identifier to be renamed is not specified:
</p>
<div class="code">
<pre>
%rename("myprefix_%s") ""; // print&nbsp;-&gt;&nbsp;myprefix_print
</pre>
</div>
<p>
This also shows that the argument of <tt>%rename</tt> doesn't have to be a
literal string but can be a <tt>printf()</tt>-like format string. In the
simplest form, <tt>"%s"</tt> is replaced with the name of the original
declaration, as shown above. However this is not always enough and SWIG
provides extensions to the usual format string syntax to allow applying a
(SWIG-defined) function to the argument. For example, to wrap all C functions
<tt>do_something_long()</tt> as more Java-like <tt>doSomethingLong()</tt> you
can use the <tt>"lowercamelcase"</tt> extended format specifier like this:
</p>
<div class="code">
<pre>
%rename("%(lowercamelcase)s") ""; // foo_bar -&gt; fooBar; FooBar -&gt; fooBar
</pre>
</div>
<p>
Some functions can be parametrized, for example the <tt>"strip"</tt> one
strips the provided prefix from its argument. The prefix is specified as part
of the format string, following a colon after the function name:
</p>
<div class="code">
<pre>
%rename("%(strip:[wx])s") ""; // wxHello -&gt; Hello; FooBar -&gt; FooBar
</pre>
</div>
<p>
Below is the table summarizing all currently defined functions with an example
of applying each one. Note that some of them have two names, a shorter one
and a more descriptive one, but the two functions are otherwise equivalent:
</p>
<table summary="Format string functions" border="1" cellpadding="5">
<tr>
<th>Function</th><th>Returns</th><th colspan=2>Example (in/out)</th>
</tr>
<tr>
<td><tt>uppercase</tt> or <tt>upper</tt></td>
<td>Upper case version of the string.</td>
<td><tt>Print</tt></td><td><tt>PRINT</tt></td>
</tr>
<tr>
<td><tt>lowercase</tt> or <tt>lower</tt></td>
<td>Lower case version of the string.</td>
<td><tt>Print</tt></td><td><tt>print</tt></td>
</tr>
<tr>
<td><tt>title</tt></td>
<td>String with first letter capitalized and the rest in lower case.</td>
<td><tt>print</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><tt>firstuppercase</tt></td>
<td>String with the first letter capitalized and the rest unchanged.</td>
<td><tt>printIt</tt></td><td><tt>PrintIt</tt></td>
</tr>
<tr>
<td><tt>firstlowercase</tt></td>
<td>String with the first letter in lower case and the rest unchanged.</td>
<td><tt>PrintIt</tt></td><td><tt>printIt</tt></td>
</tr>
<tr>
<td><tt>camelcase</tt> or <tt>ctitle</tt></td>
<td>String with capitalized first letter and any letter following an
underscore (which are removed in the process) and rest in lower case.</td>
<td><tt>print_it</tt></td><td><tt>PrintIt</tt></td>
</tr>
<tr>
<td><tt>lowercamelcase</tt> or <tt>lctitle</tt></td>
<td>String with every letter following an underscore (which is removed in
the process) capitalized and rest, including the first letter, in lower
case.</td>
<td><tt>print_it</tt></td><td><tt>printIt</tt></td>
</tr>
<tr>
<td><tt>undercase</tt> or <tt>utitle</tt></td>
<td>Lower case string with underscores inserted before every upper case
letter in the original string and any number not at the end of string.
Logically, this is the reverse of <tt>camelcase</tt>.</td>
<td><tt>PrintIt</tt></td><td><tt>print_it</tt></td>
</tr>
<tr>
<td><tt>schemify</tt></td>
<td>String with all underscores replaced with dashes, resulting in more
Lispers/Schemers-pleasing name.</td>
<td><tt>print_it</tt></td><td><tt>print-it</tt></td>
</tr>
<tr>
<td><tt>strip:[prefix]</tt></td>
<td>String without the given prefix or the original string if it doesn't
start with this prefix. Note that square brackets should be used
literally, e.g. <tt>%rename("strip:[wx]")</tt></td>
<td><tt>wxPrint</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><span style="white-space: nowrap;"><tt>regex:/pattern/subst/</tt></span></td>
<td>String after (Perl-like) regex substitution operation. This function
allows to apply arbitrary regular expressions to the identifier names. The
<i>pattern</i> part is a regular expression in Perl syntax (as supported
by the <a href="http://www.pcre.org/">Perl Compatible Regular Expressions (PCRE)</a>)
library and the <i>subst</i> string
can contain back-references introduced by <tt>'\'</tt> or, as backslashes need
to be escaped in C strings, rather by <tt>"\\"</tt>. For example, to remove
any alphabetic prefix before an underscore you could use the following directive:
<tt>%rename("regex:/(\\w+)_(.*)/\\2/")</tt></td>
<td><tt>Prefix_Print</tt></td><td><tt>Print</tt></td>
</tr>
<tr>
<td><tt>command:cmd</tt></td>
<td>Output of an external command <tt>cmd</tt> with the string passed to
it as input. Notice that this function is extremely slow compared to all
the other ones as it involves spawning a separate process and using it for
many declarations is not recommended. The <i>cmd</i> is not enclosed in
square brackets but must be terminated with a triple <tt>'&lt;'</tt> sign,
e.g. <tt>%rename("command:tr&nbsp;-d&nbsp;aeiou &lt;&lt;&lt;")</tt>
(nonsensical example removing all vowels)</td>
<td><tt>Print</tt></td><td><tt>Prnt</tt></td>
</tr>
</table>
<p>
The most general function of all of the above ones (not counting
<tt>command</tt> which is even more powerful in principle but which should
generally be avoided because of performance considerations) is the
<tt>regex</tt> one. Here are some more examples of its use:
</p>
<div class="code">
<pre>
// Strip the wx prefix from all identifiers except those starting with wxEVT
%rename("%(regex:/wx(?!EVT)(.*)/\\1/)s") ""; // wxSomeWidget -&gt; SomeWidget
// wxEVT_PAINT -&gt; wxEVT_PAINT
// Apply a rule for renaming the enum elements to avoid the common prefixes
// which are redundant in C#/Java
%rename("%(regex:/^([A-Z][a-z]+)+_(.*)/\\2/)s", %$isenumitem) ""; // Colour_Red -&gt; Red
// Remove all "Set/Get" prefixes.
%rename("%(regex:/^(Set|Get)(.*)/\\2/)s") ""; // SetValue -&gt; Value
// GetValue -&gt; Value
</pre>
</div>
<p>
As before, everything that was said above about <tt>%rename</tt> also applies to
<tt>%ignore</tt>. In fact, the latter is just a special case of the former and
ignoring an identifier is the same as renaming it to the special
<tt>"$ignore"</tt> value. So the following snippets
</p>
<div class="code">
<pre>
%ignore print;
</pre>
</div>
<p>
and
</p>
<div class="code">
<pre>
%rename("$ignore") print;
</pre>
</div>
<p>
are exactly equivalent and <tt>%rename</tt> can be used to selectively ignore
multiple declarations using the previously described matching possibilities.
</p>
<H4><a name="SWIG_limiting_renaming"></a>5.4.7.3 Limiting global renaming rules</H4>
<p>
As explained in the previous sections, it is possible to either rename
individual declarations or apply a rename rule to all of them at once. In
practice, the latter is however rarely appropriate as there are always some
exceptions to the general rules. To deal with them, the scope of an unnamed
<tt>%rename</tt> can be limited using subsequent <tt>match</tt> parameters.
They can be applied to any of the attributes associated by SWIG with the
declarations appearing in its input. For example:
</p>
<div class="code">
<pre>
%rename("foo", match$name="bar") "";
</pre>
</div>
<p>
can be used to achieve the same effect as the simpler
</p>
<div class="code">
<pre>
%rename("foo") bar;
</pre>
</div>
<p>
and so is not very interesting on its own. However <tt>match</tt> can also be
applied to the declaration type, for example <tt>match="class"</tt> restricts
the match to class declarations only (in C++) and <tt>match="enumitem"</tt>
restricts it to the enum elements. SWIG also provides convenience macros for
such match expressions, for example
</p>
<div class="code">
<pre>
%rename("%(title)s", %$isenumitem) "";
</pre>
</div>
<p>
will capitalize the names of all the enum elements but not change the case of
the other declarations. Similarly, <tt>%$isclass</tt>, <tt>%$isfunction</tt>
and <tt>%$isvariable</tt> can be used. Many other checks are possible and this
documentation is not exhaustive, see "%rename predicates" section of
<tt>swig.swg</tt> for the full list of supported match expressions.
</p>
<p>
Another important feature of <tt>match</tt> is that it can be applied not
only to the declaration itself but also to its enclosing declaration. So
<tt>match$parentNode$name="SomeClass"</tt> would be true only for members of
the C++ class with the specified name. This can, of course, be combined with
more complicated matches making it possible to write
</p>
<div class="code">
<pre>
%rename("%(lowercase)s", match$parentNode$name="SomeClass", %$isenum) "";
</pre>
</div>
<p>
to rename all enums nested in the given class to lower case.
</p>
<p>
In addition to literally matching some string with <tt>match</tt> you can
also use <tt>regexmatch</tt> or <tt>notregexmatch</tt> to match a string
against a regular expression. For example, to ignore all functions having
"Old" as a suffix you could use
</p>
<div class="code">
<pre>
%rename("$ignore", regexmatch$name="Old$") "";
</pre>
</div>
<p>
For simple cases like this, specifying the regular expression for the
declaration name directly can be preferable and can also be done using
<tt>regextarget</tt>:
</p>
<div class="code">
<pre>
%rename("$ignore", regextarget=1) "Old$";
</pre>
</div>
<p>
As for <tt>notregexmatch</tt>, it restricts the match only to the strings not
matching the specified regular expression. So to rename all declarations to lower case
except those consisting of capital letters only:
</p>
<div class="code">
<pre>
%rename("$(lower)s", notregexmatch$name="^[A-Z]+$") "";
</pre>
</div>
<p>
Finally, 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#SWIGPlus_ambiguity_resolution_renaming">Ambiguity resolution and renaming</a> section in the C++ chapter.
</p>
<H3><a name="SWIG_default_args"></a>5.4.8 Default/optional arguments</H3>
@ -1925,13 +2221,13 @@ normally, just use the original function name such as <tt>add()</tt>.
<p>
SWIG provides a number of extensions to standard C printf formatting
that may be useful in this context. For instance, the following
variation installs the callbacks as all upper-case constants such as
variation installs the callbacks as all upper case constants such as
<tt>ADD</tt>, <tt>SUB</tt>, and <tt>MUL</tt>:
</p>
<div class="code"><pre>
/* Some callback functions */
%callback("%(upper)s");
%callback("%(uppercase)s");
int add(int,int);
int sub(int,int);
int mul(int,int);
@ -1939,7 +2235,7 @@ int mul(int,int);
</pre></div>
<p>
A format string of <tt>"%(lower)s"</tt> converts all characters to lower-case.
A format string of <tt>"%(lowercase)s"</tt> converts all characters to lower case.
A string of <tt>"%(title)s"</tt> capitalizes the first character and converts the
rest to lower case.
</p>

4
Doc/Manual/SWIGPlus.html
View file

@ -56,7 +56,7 @@
<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>
@ -4408,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>

32
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.2 (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>
@ -27,7 +19,7 @@ to help!).
<li><a href="SWIG.html#SWIG">SWIG Basics</a> (Read this!)</li>
<li><a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a></li>
<li><a href="Preprocessor.html#Preprocessor">The SWIG preprocessor</a></li>
<li><a href="Library.html#Library">The SWIG Library</a></li>
<li><a href="Library.html#Library">The SWIG library</a></li>
<li><a href="Arguments.html#Arguments">Argument handling</a></li>
<li><a href="Typemaps.html#Typemaps">Typemaps</a></li>
<li><a href="Customization.html#Customization">Customization features</a></li>
@ -44,10 +36,11 @@ to help!).
<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">Lua support</a></li>
<li><a href="Lisp.html#Lisp">Common Lisp support</a></li>
<li><a href="Lua.html#Lua">Lua 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>
@ -56,8 +49,8 @@ to help!).
<li><a href="Php.html#Php">PHP support</a></li>
<li><a href="Pike.html#Pike">Pike support</a></li>
<li><a href="Python.html#Python">Python support</a></li>
<li><a href="Ruby.html#Ruby">Ruby support</a></li>
<li><a href="R.html#R">R support</a></li>
<li><a href="Ruby.html#Ruby">Ruby support</a></li>
<li><a href="Tcl.html#Tcl">Tcl support</a></li>
</ul>
@ -67,16 +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>
</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>35 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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.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>35.10 Tcl/Tk Stubs</H2>
<p>

33
Doc/Manual/Typemaps.html
View file

@ -18,6 +18,7 @@
<li><a href="#Typemaps_nn6">Reusing typemaps</a>
<li><a href="#Typemaps_nn7">What can be done with typemaps?</a>
<li><a href="#Typemaps_nn8">What can't be done with typemaps?</a>
<li><a href="#Typemaps_aspects">Similarities to Aspect Oriented Programming</a>
<li><a href="#Typemaps_nn9">The rest of this chapter</a>
</ul>
<li><a href="#Typemaps_nn10">Typemap specifications</a>
@ -33,8 +34,8 @@
<li><a href="#Typemaps_nn17">Basic matching rules</a>
<li><a href="#Typemaps_typedef_reductions">Typedef reductions matching</a>
<li><a href="#Typemaps_nn19">Default typemap matching rules</a>
<li><a href="#Typemaps_matching_template_comparison">Matching comparison with C++ templates</a>
<li><a href="#Typemaps_multi_argument_typemaps_patterns">Multi-arguments typemaps</a>
<li><a href="#Typemaps_matching_template_comparison">Matching rules compared to C++ templates</a>
<li><a href="#Typemaps_debugging_search">Debugging typemap pattern matching</a>
</ul>
<li><a href="#Typemaps_nn21">Code generation rules</a>
@ -115,7 +116,7 @@ chapter with only a vague idea of what SWIG already does by default.
<p>
One of the most important problems in wrapper code generation is the
conversion of datatypes between programming languages. Specifically,
conversion or marshalling of datatypes between programming languages. Specifically,
for every C/C++ declaration, SWIG must somehow generate wrapper code
that allows values to be passed back and forth between languages.
Since every programming language represents data differently, this is
@ -637,7 +638,25 @@ void wrap_foo(char *s, int x) {
</pre>
</div>
<H3><a name="Typemaps_nn9"></a>10.1.7 The rest of this chapter</H3>
<H3><a name="Typemaps_aspects"></a>10.1.7 Similarities to Aspect Oriented Programming</H3>
<p>
SWIG has parallels to <a href="http://en.wikipedia.org/wiki/Aspect-oriented_programming">Aspect Oriented Software Development (AOP)</a>.
The <a href="http://en.wikipedia.org/wiki/Aspect-oriented_programming#Terminology">AOP terminology</a> with respect to SWIG typemaps can be viewed as follows:
</p>
<ul>
<li> <b>Cross-cutting concerns</b>: The cross-cutting concerns are the modularization of the functionality that the typemaps implement, which is primarily marshalling of types from/to the target language and C/C++.
<li> <b>Advice</b>: The typemap body contains code which is executed whenever the marshalling is required.
<li> <b>Pointcut</b>: The pointcuts are the positions in the wrapper code that the typemap code is generated into.
<li> <b>Aspect</b>: Aspects are the combination of the pointcut and the advice, hence each typemap is an aspect.
</ul>
<p>
SWIG can also be viewed as has having a second set of aspects based around <a href="Customization.html">%feature</a>.
Features such as <tt>%exception</tt> are also cross-cutting concerns as they encapsulate code that can be used to add logging or exception handling to any function.
</p>
<H3><a name="Typemaps_nn9"></a>10.1.8 The rest of this chapter</H3>
<p>
@ -1418,7 +1437,7 @@ Finally the best way to view the typemap matching rules in action is via the <a
simpler scheme to match the current C++ class template partial specialization matching rules.
</p>
<H3><a name="Typemaps_multi_argument_typemaps_patterns"></a>10.3.5 Multi-arguments typemaps</H3>
<H3><a name="Typemaps_multi_argument_typemaps_patterns"></a>10.3.4 Multi-arguments typemaps</H3>
<p>
@ -1448,7 +1467,8 @@ but all subsequent arguments must match exactly.
</p>
<H3><a name="Typemaps_matching_template_comparison"></a>10.3.4 Matching rules compared to C++ templates</H3>
<H3><a name="Typemaps_matching_template_comparison"></a>10.3.5 Matching rules compared to C++ templates</H3>
<p>
For those intimately familiar with C++ templates, a comparison of the typemap matching rules and template type deduction is interesting.
@ -1671,7 +1691,8 @@ example.h:3: Searching for a suitable 'in' typemap for: Row4 rows[10]
<p>
showing that the best default match supplied by SWIG is the <tt>SWIGTYPE []</tt> typemap.
As the example shows, the successful match displays the used typemap source including typemap method, type and optional name in one of these simplified formats: <p>
As the example shows, the successful match displays the used typemap source including typemap method, type and optional name in one of these simplified formats:
</p>
<ul>
<li> <tt>Using: %typemap(method) type name</tt>

4
Doc/Manual/Warnings.html
View file

@ -25,7 +25,7 @@
<li><a href="#Warnings_nn12">C/C++ Parser (300-399)</a>
<li><a href="#Warnings_nn13">Types and typemaps (400-499) </a>
<li><a href="#Warnings_nn14">Code generation (500-599)</a>
<li><a href="#Warnings_nn15">Language module specific (800-899) </a>
<li><a href="#Warnings_nn15">Language module specific (700-899) </a>
<li><a href="#Warnings_nn16">User defined (900-999)</a>
</ul>
<li><a href="#Warnings_nn17">History</a>
@ -515,7 +515,7 @@ example.i(4) : Syntax error in input.
<li>519. %template() contains no name. Template method ignored: <em>declaration</em>
</ul>
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (800-899) </H3>
<H3><a name="Warnings_nn15"></a>14.9.6 Language module specific (700-899) </H3>
<ul>

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>

4
Doc/Manual/chapters
View file

@ -17,6 +17,7 @@ CCache.html
Allegrocl.html
CSharp.html
Chicken.html
Go.html
Guile.html
Java.html
Lisp.html
@ -29,8 +30,7 @@ Perl5.html
Php.html
Pike.html
Python.html
R.html
Ruby.html
Tcl.html
R.html
Extending.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>