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

Doc update

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5411 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2003-11-25 21:18:30 +00:00
commit eca80d3999
20 changed files with 760 additions and 488 deletions
Download patch file Download diff file Expand all files Collapse all files

24
SWIG/Doc/Manual/Advanced.html
View file

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>13 Advanced Topics</H1>
<a name="n1"></a><H1>15 Advanced Topics</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Creating multi-module packages</a>
@ -32,12 +32,12 @@
<b>Caution: This chapter is under repair!</b>
<a name="n2"></a><H2>13.1 Creating multi-module packages</H2>
<a name="n2"></a><H2>15.1 Creating multi-module packages</H2>
SWIG can be used to create packages consisting of many different modules. However, there are some technical aspects of doing this and techniques for managing the problem.<p>
This chapter doesn't apply to those languages that use static type checking, rather than runtime type checking, such as Java and C#.
<a name="n3"></a><H3>13.1.1 Runtime support (and potential problems)</H3>
<a name="n3"></a><H3>15.1.1 Runtime support (and potential problems)</H3>
Most SWIG generated modules rely upon a small collection of functions that are used during run-time.
@ -47,7 +47,7 @@ If you create a system consisting of many modules, each one will have an identic
<center><img src="ch11.1.png"></center><p>
<p>
This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next).<p>
<a name="n4"></a><H3>13.1.2 Why doesn't C++ inheritance work between modules?</H3>
<a name="n4"></a><H3>15.1.2 Why doesn't C++ inheritance work between modules?</H3>
Consider for a moment the following two interface files :<p>
@ -101,7 +101,7 @@ However, from our class definitions we know that "b" is an "a" by inheritance an
The type information listed shows the acceptable values for various C datatypes. In the "a" module, we see that "a" can only accept instances of itself. In the "b" module, we see that "a" can accept both "a" and "b" instances--which is correct given that a "b" is an "a" by inheritance.<p>
<p>
Unfortunately, this problem is inherent in the method by which SWIG makes modules. When we made the "a" module, we had no idea what derived classes might be used at a later time. However, it's impossible to produce the proper type information until after we know all of the derived classes. A nice problem to be sure, but one that can be fixed by making all modules share a single copy of the SWIG run-time library.<p>
<a name="n5"></a><H3>13.1.3 The SWIG runtime library</H3>
<a name="n5"></a><H3>15.1.3 The SWIG runtime library</H3>
To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules. This requires the use of the SWIG runtime library which is optionally built during SWIG installation. To use the runtime libraries, follow these steps:<p>
@ -155,7 +155,7 @@ When completed you should now end up with a collection of modules like this:<p>
<p>
<p>
In this configuration, the runtime library manages all datatypes and other information between modules. This management process is dynamic in nature--when new modules are loaded, they contribute information to the run-time system. In the C++ world, one could incrementally load classes as needed. As this process occurs, type information is updated and base-classes learn about derived classes as needed.<p>
<a name="n6"></a><H3>13.1.4 A few dynamic loading gotchas</H3>
<a name="n6"></a><H3>15.1.4 A few dynamic loading gotchas</H3>
When working with dynamic loading, it is critical to check that only one copy of the run-time library is being loaded into the system. When working with <tt>.a</tt> library files, problems can sometimes occur so there are a few approaches to the problem.<p>
@ -223,7 +223,7 @@ A somewhat better approach is to link your module with the proper path encoded.
The <tt>-rpath</tt> option encodes the location of shared libraries into your modules and gets around having to set the <tt>LD_LIBRARY_PATH</tt> variable.<p>
<p>
If all else fails, pull up the man pages for your linker and start playing around.<p>
<a name="n7"></a><H2>13.2 Dynamic Loading of C++ modules</H2>
<a name="n7"></a><H2>15.2 Dynamic Loading of C++ modules</H2>
Dynamic loading of C++ modules presents a special problem for many systems. This is because C++ modules often need additional supporting code for proper initialization and operation. Static constructors are also a bit of a problem.<p>
@ -239,12 +239,12 @@ While the process of building C++ modules is, by no means, and exact science, he
</ul>
<p>
The SWIG distribution contains some additional documentation about C++ modules in the Doc directory as well.<p>
<a name="n8"></a><H2>13.3 Inside the SWIG type-checker</H2>
<a name="n8"></a><H2>15.3 Inside the SWIG type-checker</H2>
The SWIG runtime type-checker plays a critical role in the correct operation of SWIG modules. It not only checks the validity of pointer types, but also manages C++ inheritance, and performs proper type-casting of pointers when necessary. This section provides some insight into what it does, how it works, and why it is the way it is.<p>
<a name="n9"></a><H3>13.3.1 Type equivalence</H3>
<a name="n9"></a><H3>15.3.1 Type equivalence</H3>
SWIG uses a name-based approach to managing pointer datatypes. For example, if you are using a pointer like "<tt>double *</tt>", the type-checker will look for a particular string representation of that datatype such as "<tt>_double_p</tt>". If no match is found, a type-error is reported.<p>
@ -313,7 +313,7 @@ E =&gt; { }
</pre></blockquote>
The encoding reflects the class hierarchy. For example, any object of type "A" will also accept objects of type B,C, and E because these are all derived from A. However, it is not legal to go the other way. For example, a function operating on a object from class E will not accept an object from class A.<p>
<a name="n10"></a><H3>13.3.2 Type casting</H3>
<a name="n10"></a><H3>15.3.2 Type casting</H3>
When working with C++ classes, SWIG needs to perform proper typecasting between derived and base classes. This is particularly important when working with multiple inheritance. To do this, conversion functions are created such as the following :<p>
@ -327,7 +327,7 @@ When working with C++ classes, SWIG needs to perform proper typecasting between
</pre></blockquote>
All pointers are internally represented as void *, but conversion functions are always invoked when pointer values are converted between base and derived classes in a C++ class hierarchy.<p>
<a name="n11"></a><H3>13.3.3 Why a name based approach?</H3>
<a name="n11"></a><H3>15.3.3 Why a name based approach?</H3>
SWIG uses a name-based approach to type-checking for a number of reasons :<p>
@ -339,7 +339,7 @@ SWIG uses a name-based approach to type-checking for a number of reasons :<p>
</ul>
<p>
An alternative to a name based scheme would be to generate type-signatures based on the structure of a datatype. Such a scheme would result in perfect type-checking, but I think it would also result in a very confusing scripting language module. For this reason, I see SWIG sticking with the name-based approach--at least for the foreseeable future. <p>
<a name="n12"></a><H3>13.3.4 Performance of the type-checker</H3>
<a name="n12"></a><H3>15.3.4 Performance of the type-checker</H3>
The type-checker performs the following steps when matching a datatype :<p>

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

@ -7,7 +7,7 @@
<body bgcolor="#ffffff">
<a name="n1"></a><H1>22 SWIG and Chicken</H1>
<a name="n1"></a><H1>24 SWIG and Chicken</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -58,7 +58,7 @@
</p>
<a name="n2"></a><H2>22.1 Preliminaries</H2>
<a name="n2"></a><H2>24.1 Preliminaries</H2>
<p>
@ -79,7 +79,7 @@
</p>
<a name="n3"></a><H3>22.1.1 Running SWIG in C mode</H3>
<a name="n3"></a><H3>24.1.1 Running SWIG in C mode</H3>
<p>
@ -101,7 +101,7 @@
object files and linked into your project.
</p>
<a name="n4"></a><H3>22.1.2 Running SWIG in C++ mode</H3>
<a name="n4"></a><H3>24.1.2 Running SWIG in C++ mode</H3>
<p>
@ -123,10 +123,10 @@
</p>
<a name="n5"></a><H2>22.2 Code Generation</H2>
<a name="n5"></a><H2>24.2 Code Generation</H2>
<a name="n6"></a><H3>22.2.1 Naming Conventions</H3>
<a name="n6"></a><H3>24.2.1 Naming Conventions</H3>
<p>
@ -153,7 +153,7 @@
<tt>%rename</tt> SWIG directive in the SWIG interface file.
</p>
<a name="n7"></a><H3>22.2.2 Modules and Prefixes</H3>
<a name="n7"></a><H3>24.2.2 Modules and Prefixes</H3>
<p>
@ -187,7 +187,7 @@
</p>
<a name="n8"></a><H3>22.2.3 Constants and Variables</H3>
<a name="n8"></a><H3>24.2.3 Constants and Variables</H3>
<p>
@ -212,7 +212,7 @@
use <tt>(my-variable)</tt>.
</p>
<a name="n9"></a><H3>22.2.4 Functions</H3>
<a name="n9"></a><H3>24.2.4 Functions</H3>
<p>
@ -231,7 +231,7 @@
parameters).
</p>
<a name="n10"></a><H2>22.3 TinyCLOS</H2>
<a name="n10"></a><H2>24.3 TinyCLOS</H2>
<p>
@ -269,7 +269,7 @@
</p>
<a name="n11"></a><H2>22.4 Compilation</H2>
<a name="n11"></a><H2>24.4 Compilation</H2>
<p>
@ -283,7 +283,7 @@
much simpler <tt>csc</tt> or <tt>csc.bat</tt>.
</p>
<a name="n12"></a><H2>22.5 Linkage</H2>
<a name="n12"></a><H2>24.5 Linkage</H2>
<p>
@ -307,7 +307,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
your platform.
</p>
<a name="n13"></a><H3>22.5.1 Customized Interpreter</H3>
<a name="n13"></a><H3>24.5.1 Customized Interpreter</H3>
<p>
@ -348,7 +348,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
</p>
<a name="n14"></a><H2>22.6 Typemaps</H2>
<a name="n14"></a><H2>24.6 Typemaps</H2>
<p>
@ -488,7 +488,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
</p>
<a name="n15"></a><H2>22.7 Pointers</H2>
<a name="n15"></a><H2>24.7 Pointers</H2>
<p>
@ -523,7 +523,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
to be broken (Bug #782468), so that type errors may not be
reported.
<a name="n16"></a><H2>22.8 Unsupported features</H2>
<a name="n16"></a><H2>24.8 Unsupported features</H2>
<ul>

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

@ -344,7 +344,18 @@
</ul>
<!-- INDEX -->
<h3><a href="Varargs.html">10 Variable Length Arguments</a></h3>
<h3><a href="Contract.html">10 Contracts</a></h3>
<!-- INDEX -->
<ul>
<li><a href="Contract.html#n2">The %contract directive</a>
<li><a href="Contract.html#n3">%contract and classes</a>
<li><a href="Contract.html#n4">Constant aggregation and %aggregate_check</a>
<li><a href="Contract.html#n5">Notes</a>
</ul>
<!-- INDEX -->
<h3><a href="Varargs.html">11 Variable Length Arguments</a></h3>
<!-- INDEX -->
<ul>
@ -360,7 +371,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Warnings.html">11 Warning Messages</a></h3>
<h3><a href="Warnings.html">12 Warning Messages</a></h3>
<!-- INDEX -->
<ul>
@ -383,7 +394,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Library.html">12 SWIG library</a></h3>
<h3><a href="Library.html">13 SWIG library</a></h3>
<!-- INDEX -->
<ul>
@ -414,7 +425,18 @@
</ul>
<!-- INDEX -->
<h3><a href="Advanced.html">13 Advanced Topics</a></h3>
<h3><a href="Modules.html">14 Working with Modules</a></h3>
<!-- INDEX -->
<ul>
<li><a href="Modules.html#n2">The SWIG runtime code</a>
<li><a href="Modules.html#n3">Compiling Multiple SWIG modules</a>
<li><a href="Modules.html#n4">A word of caution about static libraries</a>
<li><a href="Modules.html#n5">References</a>
</ul>
<!-- INDEX -->
<h3><a href="Advanced.html">15 Advanced Topics</a></h3>
<!-- INDEX -->
<ul>
@ -436,7 +458,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Guile.html">14 SWIG and Guile</a></h3>
<h3><a href="Guile.html">16 SWIG and Guile</a></h3>
<!-- INDEX -->
<ul>
@ -470,7 +492,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Java.html">15 SWIG and Java</a></h3>
<h3><a href="Java.html">17 SWIG and Java</a></h3>
<!-- INDEX -->
<ul>
@ -581,7 +603,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Ocaml.html">16 SWIG and Ocaml</a></h3>
<h3><a href="Ocaml.html">18 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<ul>
@ -627,7 +649,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Perl5.html">17 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html">19 SWIG and Perl5</a></h3>
<!-- INDEX -->
<ul>
@ -689,7 +711,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Php.html">18 SWIG and PHP4</a></h3>
<h3><a href="Php.html">20 SWIG and PHP4</a></h3>
<!-- INDEX -->
<ul>
@ -713,7 +735,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Python.html">19 SWIG and Python</a></h3>
<h3><a href="Python.html">21 SWIG and Python</a></h3>
<!-- INDEX -->
<ul>
@ -799,7 +821,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Ruby.html">20 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html">22 SWIG and Ruby</a></h3>
<!-- INDEX -->
<ul>
@ -874,7 +896,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Tcl.html">21 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html">23 SWIG and Tcl</a></h3>
<!-- INDEX -->
<ul>
@ -937,7 +959,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Chicken.html">22 SWIG and Chicken</a></h3>
<h3><a href="Chicken.html">24 SWIG and Chicken</a></h3>
<!-- INDEX -->
<ul>
@ -965,7 +987,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Extending.html">23 Extending SWIG</a></h3>
<h3><a href="Extending.html">25 Extending SWIG</a></h3>
<!-- INDEX -->
<ul>

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

@ -5,10 +5,18 @@
</head>
<body bgcolor="#ffffff">
<H1>Contracts</H1>
<a name="n1"></a><H1>10 Contracts</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">The %contract directive</a>
<li><a href="#n3">%contract and classes</a>
<li><a href="#n4">Constant aggregation and %aggregate_check</a>
<li><a href="#n5">Notes</a>
</ul>
<!-- INDEX -->
A common problem that arises when wrapping C libraries is that of maintaining
reliability and checking for errors. The fact of the matter is that many
C programs are notorious for not providing error checks. Not only that,
@ -24,7 +32,8 @@ check the output values of a function and more.
When one of the rules is violated by a script, a runtime exception is
generated rather than having the program continue to execute.
<H2>The %contract directive</H2>
<a name="n2"></a><H2>10.1 The %contract directive</H2>
Contracts are added to a declaration using the %contract directive. Here
is a simple example:
@ -73,7 +82,8 @@ RuntimeError: Contract violation: require: (arg1>=0)
</pre>
</blockquote>
<h2>%contract and classes</h2>
<a name="n3"></a><H2>10.2 %contract and classes</H2>
The <tt>%contract</tt> directive can also be applied to class methods and constructors. For example:
@ -143,10 +153,83 @@ In other words conditions specified for the base class and conditions
specified for the derived class all must hold. In the above example,
this means that both the arguments to <tt>Spam::bar</tt> must be positive.
<h2>Constant aggregation and %aggregate_check</h2>
<a name="n4"></a><H2>10.3 Constant aggregation and %aggregate_check</H2>
Consider an interface file that contains the following code:
<blockquote>
<pre>
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
One thing you might want to do is impose a constraint on the direction parameter to
make sure it's one of a few accepted values. To do that, SWIG provides an easy to
use macro %aggregate_check() that works like this:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, LEFT, RIGHT);
</pre>
</blockquote>
This merely defines a utility function of the form
<blockquote>
<pre>
int check_direction(int x);
</pre>
</blockquote>
That checks the argument x to see if it is one of the values listed. This utility
function can be used in contracts. For example:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
%contract move(SomeObject *, int direction, in) {
require:
check_direction(direction);
}
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
Alternatively, it can be used in typemaps and other directives. For example:
<blockquote>
<pre>
%aggregate_check(int, check_direction, UP, DOWN, RIGHT, LEFT);
%typemap(check) int direction {
if (!check_direction($1)) SWIG_exception(SWIG_ValueError, "Bad direction");
}
#define UP 1
#define DOWN 2
#define RIGHT 3
#define LEFT 4
void move(SomeObject *, int direction, int distance);
</pre>
</blockquote>
Regrettably, there is no automatic way to perform similar checks with enums values. Maybe in a future
release.
<a name="n5"></a><H2>10.4 Notes</H2>
<h2>Notes</h2>
Contract support was implemented by Songyan (Tiger) Feng and first appeared
in SWIG-1.3.20.

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>23 Extending SWIG</H1>
<a name="n1"></a><H1>25 Extending SWIG</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Introduction</a>
@ -70,7 +70,7 @@
<b>Caution: This chapter is being rewritten! (11/25/01)</b>
<a name="n2"></a><H2>23.1 Introduction</H2>
<a name="n2"></a><H2>25.1 Introduction</H2>
This chapter describes SWIG's internal organization and the process by which
@ -83,7 +83,7 @@ date, but changes are ongoing. Expect a few inconsistencies.
Also, this chapter is not meant to be a hand-holding tutorial. As a starting point,
you should probably look at one of SWIG's existing modules.
<a name="n3"></a><H2>23.2 Prerequisites</H2>
<a name="n3"></a><H2>25.2 Prerequisites</H2>
In order to extend SWIG, it is useful to have the following background:
@ -109,7 +109,7 @@ extension of the C++ <em>type</em> system. At first glance, this might not be
obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
<a name="n4"></a><H2>23.3 The Big Picture</H2>
<a name="n4"></a><H2>25.3 The Big Picture</H2>
SWIG is a special purpose compiler that parses C++ declarations to
@ -142,7 +142,7 @@ fundamental concepts. The type system and pattern matching rules also play a cr
role in making the system work. For example, both typemaps and declaration annotation are
based on pattern matching and interact heavily with the underlying type system.
<a name="n5"></a><H2>23.4 Execution Model</H2>
<a name="n5"></a><H2>25.4 Execution Model</H2>
When you run SWIG on an interface, processing is handled in stages by a series of system components:
@ -182,7 +182,7 @@ stage of compilation.
The next few sections briefly describe some of these stages.
<a name="n6"></a><H3>23.4.1 Preprocessing</H3>
<a name="n6"></a><H3>25.4.1 Preprocessing</H3>
The preprocessor plays a critical role in the SWIG implementation. This is because a lot
@ -254,7 +254,7 @@ probably isn't too useful in general, but it will show how macros have
been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
<a name="n7"></a><H3>23.4.2 Parsing</H3>
<a name="n7"></a><H3>25.4.2 Parsing</H3>
The current C++ parser handles a subset of C++. Most incompatibilities with C are due to
@ -339,7 +339,7 @@ interprets the above code as an abstract declarator for a function
returning a <tt>foo</tt> and taking types <tt>a</tt> and <tt>b</tt> as
arguments).
<a name="n8"></a><H3>23.4.3 Parse Trees</H3>
<a name="n8"></a><H3>25.4.3 Parse Trees</H3>
The SWIG parser produces a complete parse tree of the input file before any wrapper code
@ -588,7 +588,7 @@ $ swig -c++ -python -dump_tree example.i
</pre>
</blockquote>
<a name="n9"></a><H3>23.4.4 Attribute namespaces</H3>
<a name="n9"></a><H3>25.4.4 Attribute namespaces</H3>
Attributes of parse tree nodes are often prepended with a namespace qualifier.
@ -604,7 +604,7 @@ of wrapper code. The convention for doing this is to place these attributes in
that matches the name of the target language. For example, <tt>python:foo</tt> or
<tt>perl:foo</tt>.
<a name="n10"></a><H3>23.4.5 Symbol Tables</H3>
<a name="n10"></a><H3>25.4.5 Symbol Tables</H3>
During parsing, all symbols are managed in the space of the target
@ -684,7 +684,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</blockquote>
<a name="n11"></a><H3>23.4.6 The %feature directive</H3>
<a name="n11"></a><H3>25.4.6 The %feature directive</H3>
A number of SWIG directives such as <tt>%exception</tt> are implemented using the
@ -734,7 +734,7 @@ data stored in a feature attribute is usually just a raw unparsed string.
For example, the exception code above is simply
stored without any modifications.
<a name="n12"></a><H3>23.4.7 Code Generation</H3>
<a name="n12"></a><H3>25.4.7 Code Generation</H3>
Language modules work by defining handler functions that know how to respond to
@ -842,7 +842,7 @@ public :
The role of these functions is described shortly.
<a name="n13"></a><H3>23.4.8 SWIG and XML</H3>
<a name="n13"></a><H3>25.4.8 SWIG and XML</H3>
Much of SWIG's current parser design was originally motivated by
@ -853,7 +853,7 @@ by aspects of XML parsing. Therefore, in trying to understand SWIG's
internal data structures, it may be useful keep XML in the back of
your mind as a model.
<a name="n14"></a><H2>23.5 Primitive Data Structures</H2>
<a name="n14"></a><H2>25.5 Primitive Data Structures</H2>
Most of SWIG is constructed using three basic data structures:
@ -893,7 +893,7 @@ typedef Hash Typetab;
</pre>
</blockquote>
<a name="n15"></a><H3>23.5.1 Strings</H3>
<a name="n15"></a><H3>25.5.1 Strings</H3>
<p>
@ -1001,7 +1001,7 @@ DOH_REPLACE_FIRST - Replace first occurrence only.
Returns the number of replacements made (if any).
</blockquote>
<a name="n16"></a><H3>23.5.2 Hashes</H3>
<a name="n16"></a><H3>25.5.2 Hashes</H3>
<p>
@ -1062,7 +1062,7 @@ Returns the list of hash table keys.
</blockquote>
<a name="n17"></a><H3>23.5.3 Lists</H3>
<a name="n17"></a><H3>25.5.3 Lists</H3>
<p>
@ -1133,7 +1133,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.
</blockquote>
<a name="n18"></a><H3>23.5.4 Common operations</H3>
<a name="n18"></a><H3>25.5.4 Common operations</H3>
The following operations are applicable to all datatypes.
@ -1176,7 +1176,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</blockquote>
<a name="n19"></a><H3>23.5.5 Iterating over Lists and Hashes</H3>
<a name="n19"></a><H3>25.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:
@ -1216,7 +1216,7 @@ for (j = First(j); j.item; j= Next(j)) {
</pre>
</blockquote>
<a name="n20"></a><H3>23.5.6 I/O</H3>
<a name="n20"></a><H3>25.5.6 I/O</H3>
Special I/O functions are used for all internal I/O. These operations
@ -1323,7 +1323,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
<a name="n21"></a><H2>23.6 Navigating and manipulating parse trees</H2>
<a name="n21"></a><H2>25.6 Navigating and manipulating parse trees</H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1425,7 +1425,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</blockquote>
<a name="n22"></a><H2>23.7 Working with attributes</H2>
<a name="n22"></a><H2>25.7 Working with attributes</H2>
Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
@ -1524,14 +1524,14 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</blockquote>
<a name="n23"></a><H2>23.8 Type system</H2>
<a name="n23"></a><H2>25.8 Type system</H2>
SWIG implements the complete C++ type system including typedef, inheritance,
pointers, references, and pointers to members. A detailed discussion of
type theory is impossible here. However, let's cover the highlights.
<a name="n24"></a><H3>23.8.1 String encoding of types</H3>
<a name="n24"></a><H3>25.8.1 String encoding of types</H3>
<p>
@ -1619,7 +1619,7 @@ is processed in a few pieces. In this case, you have the base type
make the final type, the two parts are just joined together using
string concatenation.
<a name="n25"></a><H3>23.8.2 Type construction</H3>
<a name="n25"></a><H3>25.8.2 Type construction</H3>
The following functions are used to construct types. You should use
@ -1726,7 +1726,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</blockquote>
<a name="n26"></a><H3>23.8.3 Type tests</H3>
<a name="n26"></a><H3>25.8.3 Type tests</H3>
The following functions can be used to test properties of a datatype.
@ -1791,7 +1791,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</blockquote>
<a name="n27"></a><H3>23.8.4 Typedef and inheritance</H3>
<a name="n27"></a><H3>25.8.4 Typedef and inheritance</H3>
The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
@ -1876,7 +1876,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</blockquote>
<a name="n28"></a><H3>23.8.5 Lvalues</H3>
<a name="n28"></a><H3>25.8.5 Lvalues</H3>
When generating wrapper code, it is necessary to emit datatypes that can
@ -1907,7 +1907,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</blockquote>
<a name="n29"></a><H3>23.8.6 Output functions</H3>
<a name="n29"></a><H3>25.8.6 Output functions</H3>
The following functions produce strings that are suitable for output.
@ -1957,7 +1957,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</blockquote>
<a name="n30"></a><H2>23.9 Parameters</H2>
<a name="n30"></a><H2>25.9 Parameters</H2>
Several type-related functions involve parameter lists. These include
@ -2036,7 +2036,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</blockquote>
<a name="n31"></a><H2>23.10 Writing a Language Module</H2>
<a name="n31"></a><H2>25.10 Writing a Language Module</H2>
This section briefly outlines the steps needed to create a bare-bones
@ -2045,7 +2045,7 @@ of existing modules. Since the code is relatively easy to read, this section
describes the creation of a minimal Python module. You should be able to extrapolate
this to other languages.
<a name="n32"></a><H3>23.10.1 Execution model</H3>
<a name="n32"></a><H3>25.10.1 Execution model</H3>
Code generation modules are defined by inheriting from the <tt>Language</tt> class,
@ -2053,7 +2053,7 @@ currently defined in the <tt>Source/Modules1.1</tt> directory of SWIG. Starting
the parsing of command line options, all aspects of code generation are controlled by
different methods of the <tt>Language</tt> that must be defined by your module.
<a name="n33"></a><H3>23.10.2 Starting out</H3>
<a name="n33"></a><H3>25.10.2 Starting out</H3>
To define a new language module, first create a minimal implementation using
@ -2145,7 +2145,7 @@ Once it finishes compiling, try running SWIG with the command-line option
that activates your module. For example, <tt>swig -python foo.i</tt>. The
messages from your new module should appear.
<a name="n34"></a><H3>23.10.3 Command line options</H3>
<a name="n34"></a><H3>25.10.3 Command line options</H3>
When SWIG starts, the command line options are passed to your language module. This occurs
@ -2199,7 +2199,7 @@ If a module recognizes an option, it should always call <tt>Swig_mark_arg()</tt>
to mark the option as valid. If you forget to do this, SWIG will terminate with an
unrecognized command line option error.
<a name="n35"></a><H3>23.10.4 Configuration and preprocessing</H3>
<a name="n35"></a><H3>25.10.4 Configuration and preprocessing</H3>
In addition to looking at command line options, the <tt>main()</tt> method is responsible
@ -2242,7 +2242,7 @@ Just to review, your language module should now consist of two files--
an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
<a name="n36"></a><H3>23.10.5 Entry point to code generation</H3>
<a name="n36"></a><H3>25.10.5 Entry point to code generation</H3>
SWIG is a multi-pass compiler. Once the <tt>main()</tt> method has
@ -2296,13 +2296,13 @@ int Python::top(Node *n) {
</blockquote>
</pre>
<a name="n37"></a><H3>23.10.6 Module I/O and wrapper skeleton</H3>
<a name="n37"></a><H3>25.10.6 Module I/O and wrapper skeleton</H3>
<a name="n38"></a><H3>23.10.7 Low-level code generators</H3>
<a name="n38"></a><H3>25.10.7 Low-level code generators</H3>
<a name="n39"></a><H3>23.10.8 Configuration files</H3>
<a name="n39"></a><H3>25.10.8 Configuration files</H3>
<!-- please report bugs in this section to ttn -->
@ -2428,14 +2428,14 @@ to handle some of these configuration tasks, but that point is now
long past. If you are interested in working on that, feel free to
raise the issue in the context of a next-generation clean-slate SWIG.<p>
<a name="n40"></a><H3>23.10.9 Runtime support</H3>
<a name="n40"></a><H3>25.10.9 Runtime support</H3>
Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
<tt>SWIG_ConvertPtr()</tt> and <tt>SWIG_NewPointerObj()</tt>) and the names of
the SWIG files that implement those functions.
<a name="n41"></a><H3>23.10.10 Standard library files</H3>
<a name="n41"></a><H3>25.10.10 Standard library files</H3>
Discuss the standard library files that most language modules provide, e.g.
@ -2446,7 +2446,7 @@ Discuss the standard library files that most language modules provide, e.g.
<li> stl.i </li>
</ul>
<a name="n42"></a><H3>23.10.11 Examples and test cases</H3>
<a name="n42"></a><H3>25.10.11 Examples and test cases</H3>
Each of the language modules provides one or more examples. These examples
@ -2467,7 +2467,7 @@ By default, all of the examples are built and run when the user types
during this process, see the section on <a href="#n37a">configuration
files</a>.
<a name="n43"></a><H3>23.10.12 Documentation</H3>
<a name="n43"></a><H3>25.10.12 Documentation</H3>
Don't forget to write end-user documentation for your language module. Currently,
@ -2494,13 +2494,13 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<a name="n44"></a><H2>23.11 Typemaps</H2>
<a name="n44"></a><H2>25.11 Typemaps</H2>
<a name="n45"></a><H3>23.11.1 Proxy classes</H3>
<a name="n45"></a><H3>25.11.1 Proxy classes</H3>
<a name="n46"></a><H2>23.12 Guide to parse tree nodes</H2>
<a name="n46"></a><H2>25.12 Guide to parse tree nodes</H2>
This section describes the different parse tree nodes and their attributes.

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

@ -7,7 +7,7 @@
<body bgcolor="#ffffff">
<a name="n1"></a><H1>14 SWIG and Guile</H1>
<a name="n1"></a><H1>16 SWIG and Guile</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Meaning of "Module"</a>
@ -45,7 +45,7 @@
<p>
This section details guile-specific support in SWIG.
<a name="n2"></a><H2>14.1 Meaning of "Module"</H2>
<a name="n2"></a><H2>16.1 Meaning of "Module"</H2>
</a>
@ -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".
<a name="n3"></a><H2>14.2 Using the SCM or GH Guile API</H2>
<a name="n3"></a><H2>16.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
@ -105,7 +105,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>
<a name="n4"></a><H2>14.3 Linkage</H2>
<a name="n4"></a><H2>16.3 Linkage</H2>
</a>
@ -115,7 +115,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>.
<a name="n5"></a><H3>14.3.1 Simple Linkage</H3>
<a name="n5"></a><H3>16.3.1 Simple Linkage</H3>
The default linkage is the simplest; nothing special is done. In this
@ -191,7 +191,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.
<a name="n6"></a><H3>14.3.2 Passive Linkage</H3>
<a name="n6"></a><H3>16.3.2 Passive Linkage</H3>
<p>Passive linkage is just like simple linkage, but it generates an
@ -201,7 +201,7 @@ package name (see below).
<p>You should use passive linkage rather than simple linkage when you
are using multiple modules.
<a name="n7"></a><H3>14.3.3 Native Guile Module Linkage</H3>
<a name="n7"></a><H3>16.3.3 Native Guile Module Linkage</H3>
<p>SWIG can also generate wrapper code that does all the Guile module
@ -242,7 +242,7 @@ Newer Guile versions have a shorthand procedure for this:
</blockquote>
</ul>
<a name="n8"></a><H3>14.3.4 Old Auto-Loading Guile Module Linkage</H3>
<a name="n8"></a><H3>16.3.4 Old Auto-Loading Guile Module Linkage</H3>
<p>Guile used to support an autoloading facility for object-code
@ -268,7 +268,7 @@ option, SWIG generates an exported module initialization function with
an appropriate name.
<a name="n9"></a><H3>14.3.5 Hobbit4D Linkage</H3>
<a name="n9"></a><H3>16.3.5 Hobbit4D Linkage</H3>
<p>
@ -291,7 +291,7 @@ my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
experimental; the (hobbit4d link) conventions are not well understood.
<a name="n10"></a><H3>14.3.6 General Remarks on Multiple SWIG Modules</H3>
<a name="n10"></a><H3>16.3.6 General Remarks on Multiple SWIG Modules</H3>
If you want to use multiple SWIG modules, they have to share some
@ -311,7 +311,7 @@ SWIG if you invoke it with the <code>-guile -ldflags</code>
command-line arguments.
</ul>
<a name="n11"></a><H2>14.4 Underscore Folding</H2>
<a name="n11"></a><H2>16.4 Underscore Folding</H2>
</a>
@ -325,7 +325,7 @@ complained so far.
<code>%rename</code> to specify the Guile name of the wrapped
functions and variables (see CHANGES).
<a name="n12"></a><H2>14.5 Typemaps</H2>
<a name="n12"></a><H2>16.5 Typemaps</H2>
</a>
@ -390,7 +390,7 @@ In <code><var>body</var></code>, the first result of
</ul>
See also the "multivalue" example.
<a name="n13"></a><H2>14.6 Representation of pointers as smobs</H2>
<a name="n13"></a><H2>16.6 Representation of pointers as smobs</H2>
<p>
@ -411,7 +411,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.
<a name="n14"></a><H3>14.6.1 GH Smobs</H3>
<a name="n14"></a><H3>16.6.1 GH Smobs</H3>
<p>
@ -430,7 +430,7 @@ available. <code>SWIG_Guile_Init()</code> registers a smob type named
a table of all C pointer types seen so far, to which new types seen
are appended. The CDR stores the pointer value.
<a name="n15"></a><H3>14.6.2 SCM Smobs</H3>
<a name="n15"></a><H3>16.6.2 SCM Smobs</H3>
<p>The SCM interface (using the "-scm" argument to swig) uses common.swg.
@ -445,7 +445,7 @@ in the smob tag. If a generated GOOPS module has been loaded, smobs will be wra
GOOPS class.</p>
<a name="n16"></a><H3>14.6.3 Garbage Collection</H3>
<a name="n16"></a><H3>16.6.3 Garbage Collection</H3>
<p>Garbage collection is a feature of the new SCM interface, and it is automatically included
@ -459,7 +459,7 @@ is exactly like described in <a href="Customization.html#n9">
Section 9.2 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>
<a name="n17"></a><H2>14.7 Exception Handling</H2>
<a name="n17"></a><H2>16.7 Exception Handling</H2>
</a>
@ -485,7 +485,7 @@ mapping:
The default when not specified here is to use "swig-error".
See Lib/exception.i for details.
<a name="n18"></a><H2>14.8 Procedure documentation</H2>
<a name="n18"></a><H2>16.8 Procedure documentation</H2>
</a>
@ -520,7 +520,7 @@ like this:
typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
details.
<a name="n19"></a><H2>14.9 Procedures with setters</H2>
<a name="n19"></a><H2>16.9 Procedures with setters</H2>
</a>
@ -550,7 +550,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.
<a name="n20"></a><H2>14.10 GOOPS Shadow Classes</H2>
<a name="n20"></a><H2>16.10 GOOPS Shadow Classes</H2>
<p>SWIG can also generate classes and generic functions for use with
@ -673,7 +673,7 @@ before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put the
<code>%import "foo.h"</code> before the <code>%inline</code> block.
<a name="n21"></a><H3>14.10.1 Naming Issues</H3>
<a name="n21"></a><H3>16.10.1 Naming Issues</H3>
<p>As you can see in the example above, there are potential naming conflicts. The default exported
@ -711,7 +711,7 @@ guile-modules. For example,</p>
<p>TODO: Renaming class name prefixes?</p>
<a name="n22"></a><H3>14.10.2 Linking</H3>
<a name="n22"></a><H3>16.10.2 Linking</H3>
<p>The guile-modules generated above all need to be linked together. GOOPS support requires

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

@ -4,7 +4,7 @@
<title>SWIG and Java</title>
</head>
<body bgcolor="#FFFFFF">
<a name="n1"></a><H1>15 SWIG and Java</H1>
<a name="n1"></a><H1>17 SWIG and Java</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Overview</a>
@ -121,7 +121,7 @@ It covers most SWIG features, but certain low-level details are covered in less
<a name="overview"></a>
<a name="n2"></a><H2>15.1 Overview</H2>
<a name="n2"></a><H2>17.1 Overview</H2>
The 100% Pure Java effort is a commendable concept, however in the real world programmers often either need to re-use their existing code or in some situations
@ -154,7 +154,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.
<a name="preliminaries"></a>
<a name="n3"></a><H2>15.2 Preliminaries</H2>
<a name="n3"></a><H2>17.2 Preliminaries</H2>
SWIG 1.1 works with JDKs from JDK 1.1 to JDK1.4 (Java 2 SDK1.4) and should also work with any later versions.
@ -169,7 +169,7 @@ The Java module requires your system to support shared libraries and dynamic loa
This is the commonly used method to load JNI code so your system will more than likely support this.<p>
<a name="running_swig"></a>
<a name="n4"></a><H3>15.2.1 Running SWIG</H3>
<a name="n4"></a><H3>17.2.1 Running SWIG</H3>
Suppose that you defined a SWIG module such as the following:
@ -209,7 +209,7 @@ To change this, you can use the <tt>-o</tt> option.
It is also possible to change the <a href="SWIG.html#output">output directory </a> that the Java files are generated into using <tt>-outdir</tt>.
<a name="commandline"></a>
<a name="n5"></a><H3>15.2.2 Additional Commandline Options</H3>
<a name="n5"></a><H3>17.2.2 Additional Commandline Options</H3>
The following table list the additional commandline options available for the Java module. They can also be seen by using:
@ -236,7 +236,7 @@ The following table list the additional commandline options available for the Ja
Their use will become clearer by the time you have finished reading this section on SWIG and Java.
<a name="getting_right_headers"></a>
<a name="n6"></a><H3>15.2.3 Getting the right header files</H3>
<a name="n6"></a><H3>17.2.3 Getting the right header files</H3>
In order to compile the C/C++ wrappers, the compiler needs the <tt>jni.h</tt> and <tt>jni_md.h</tt> header files which are part of the JDK.
@ -251,7 +251,7 @@ They are usually in directories like this:<p>
The exact location may vary on your machine, but the above locations are typical. <p>
<a name="compiling_dynamic"></a>
<a name="n7"></a><H3>15.2.4 Compiling a dynamic module</H3>
<a name="n7"></a><H3>17.2.4 Compiling a dynamic module</H3>
The JNI code exists in a dynamic module or shared library (DLL on Windows) and gets loaded by the JVM.
@ -278,7 +278,7 @@ The name of the module is specified using the <tt>%module</tt> directive or<tt>
<p>
<a name="using_module"></a>
<a name="n8"></a><H3>15.2.5 Using your module</H3>
<a name="n8"></a><H3>17.2.5 Using your module</H3>
To load your shared native library module in Java, simply use Java's <tt>System.loadLibrary</tt> method in a Java class:<p>
@ -308,7 +308,7 @@ $
If it doesn't work have a look at the following section which discusses problems loading the shared library.
<a name="dynamic_linking_problems"></a>
<a name="n9"></a><H3>15.2.6 Dynamic linking problems</H3>
<a name="n9"></a><H3>17.2.6 Dynamic linking problems</H3>
As shown in the previous section the code to load a native library (shared library) is <tt>System.loadLibrary("name")</tt>.
@ -372,7 +372,7 @@ The following section also contains some C++ specific linking problems and solut
<a name="compilation_problems_cpp"></a>
<a name="n10"></a><H3>15.2.7 Compilation problems and compiling with C++</H3>
<a name="n10"></a><H3>17.2.7 Compilation problems and compiling with C++</H3>
On most machines, shared library files should be linked using the C++
@ -417,7 +417,7 @@ Finally make sure the version of JDK header files matches the version of Java th
<a name="building_windows"></a>
<a name="n11"></a><H3>15.2.8 Building on Windows</H3>
<a name="n11"></a><H3>17.2.8 Building on Windows</H3>
Building on Windows is roughly similar to the process used with Unix.
@ -426,7 +426,7 @@ This section covers the process of using SWIG with Microsoft Visual C++ 6 althou
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>
<a name="visual_studio"></a>
<a name="n12"></a><H4>15.2.8.1 Running SWIG from Visual Studio</H4>
<a name="n12"></a><H4>17.2.8.1 Running SWIG from Visual Studio</H4>
If you are developing your application within Microsoft Visual studio, SWIG can be invoked as a custom build option.
@ -458,7 +458,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="#dynamic_linking_problems">Dynamic linking problems</a>.
<a name="nmake"></a>
<a name="n13"></a><H4>15.2.8.2 Using NMAKE</H4>
<a name="n13"></a><H4>17.2.8.2 Using NMAKE</H4>
Alternatively, a Makefile for use by NMAKE can be written.
@ -516,7 +516,7 @@ Of course you may want to make changes for it to work for C++ by adding in the -
<a name="java_basic_tour"></a>
<a name="n14"></a><H2>15.3 A tour of basic C/C++ wrapping</H2>
<a name="n14"></a><H2>17.3 A tour of basic C/C++ wrapping</H2>
By default, SWIG attempts to build a natural Java interface
@ -525,7 +525,7 @@ variables are wrapped with JavaBean type getters and setters and so forth.
This section briefly covers the essential aspects of this wrapping.
<a name="module_packages_classes"></a>
<a name="n15"></a><H3>15.3.1 Modules, packages and generated Java classes</H3>
<a name="n15"></a><H3>17.3.1 Modules, packages and generated Java classes</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Java
@ -555,7 +555,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.
<a name="functions"></a>
<a name="n16"></a><H3>15.3.2 Functions</H3>
<a name="n16"></a><H3>17.3.2 Functions</H3>
There is no such thing as a global Java function so global C functions are wrapped as static methods in
@ -587,7 +587,7 @@ System.out.println(example.fact(4));
<a name="global_variables"></a>
<a name="n17"></a><H3>15.3.3 Global variables</H3>
<a name="n17"></a><H3>17.3.3 Global variables</H3>
C/C++ global variables are fully supported by SWIG.
@ -659,7 +659,7 @@ extern char *path; // Read-only (due to %immutable)
<a name="constants"></a>
<a name="n18"></a><H3>15.3.4 Constants</H3>
<a name="n18"></a><H3>17.3.4 Constants</H3>
C/C++ constants are wrapped as Java static final variables.
@ -734,7 +734,7 @@ You thus have the choice of accessing these constants from either the module cla
<a name="enumerations"></a>
<a name="n19"></a><H3>15.3.5 Enumerations</H3>
<a name="n19"></a><H3>17.3.5 Enumerations</H3>
Enumerations are wrapped as final static integers in Java and are also initialised using a JNI call. For example:
@ -794,7 +794,7 @@ also telling the C compiler about it, the wrapper code won't compile.
<p>
<a name="pointers"></a>
<a name="n20"></a><H3>15.3.6 Pointers</H3>
<a name="n20"></a><H3>17.3.6 Pointers</H3>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with
@ -874,7 +874,7 @@ a NULL pointer if the conversion can't be performed.
<p>
<a name="structures"></a>
<a name="n21"></a><H3>15.3.7 Structures</H3>
<a name="n21"></a><H3>17.3.7 Structures</H3>
If you wrap a C structure, it is wrapped by a Java class with getters and setters for access to the
@ -1017,7 +1017,7 @@ x.setA(3); // Modify x.a - this is the same as b.f.a
<a name="classes"></a>
<a name="n22"></a><H3>15.3.8 C++ classes</H3>
<a name="n22"></a><H3>17.3.8 C++ classes</H3>
C++ classes are wrapped by Java classes as well. For example, if you have this class,
@ -1072,7 +1072,7 @@ int bar = Spam.getBar();
<a name="inheritance"></a>
<a name="n23"></a><H3>15.3.9 C++ inheritance</H3>
<a name="n23"></a><H3>17.3.9 C++ inheritance</H3>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have
@ -1123,7 +1123,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.
<a name="pointers_refs_arrays"></a>
<a name="n24"></a><H3>15.3.10 Pointers, references, arrays and pass by value</H3>
<a name="n24"></a><H3>17.3.10 Pointers, references, arrays and pass by value</H3>
In C++, there are many different ways a function might receive
@ -1171,7 +1171,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).
<a name="null_pointers"></a>
<a name="n25"></a><H4>15.3.10.1 Null pointers</H4>
<a name="n25"></a><H4>17.3.10.1 Null pointers</H4>
Working with null pointers is easy.
@ -1192,7 +1192,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.
<a name="overloaded_functions"></a>
<a name="n26"></a><H3>15.3.11 C++ overloaded functions</H3>
<a name="n26"></a><H3>17.3.11 C++ overloaded functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -1290,7 +1290,7 @@ void spam(short); // Ignored
<P>
<a name="namespaces"></a>
<a name="n27"></a><H3>15.3.12 C++ namespaces</H3>
<a name="n27"></a><H3>17.3.12 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1343,7 +1343,7 @@ symbols separate, consider wrapping them as separate SWIG modules.
Each SWIG module can be placed into a separate package.
<a name="templates"></a>
<a name="n28"></a><H3>15.3.13 C++ templates</H3>
<a name="n28"></a><H3>17.3.13 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1387,7 +1387,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter.
<a name="smart_pointers"></a>
<a name="n29"></a><H3>15.3.14 C++ Smart Pointers</H3>
<a name="n29"></a><H3>17.3.14 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1460,7 +1460,7 @@ Foo f = p.__deref__(); // Returns underlying Foo *
</blockquote>
<a name="further_details"></a>
<a name="n30"></a><H2>15.4 Further details on the generated Java classes</H2>
<a name="n30"></a><H2>17.4 Further details on the generated Java classes</H2>
In the previous section, a high-level view of Java wrapping was
@ -1473,7 +1473,7 @@ of how the proxy classes work and then covers the type wrapper classes.
First, the crucial intermediary JNI class is considered.
<a name="imclass"></a>
<a name="n31"></a><H3>15.4.1 The intermediary JNI class</H3>
<a name="n31"></a><H3>17.4.1 The intermediary JNI class</H3>
In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters,
@ -1568,7 +1568,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>.
<a name="imclass_pragmas"></a>
<a name="n32"></a><H4>15.4.1.1 The intermediary JNI class pragmas</H4>
<a name="n32"></a><H4>17.4.1.1 The intermediary JNI class pragmas</H4>
The intermediary JNI class can be tailored through the use of pragmas, but is not commonly done. The pragmas for this class are:
@ -1639,7 +1639,7 @@ For example, let's change the intermediary JNI class access attribute to public.
All the methods in the intermediary JNI class will then be callable outside of the package as the method modifiers are public by default.
<a name="java_module_class"></a>
<a name="n33"></a><H3>15.4.2 The Java module class</H3>
<a name="n33"></a><H3>17.4.2 The Java module class</H3>
All global functions and variable getters/setters appear in the module class. For our example, there is just one function:
@ -1665,7 +1665,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.
<a name="module_class_pragmas"></a>
<a name="n34"></a><H4>15.4.2.1 The Java module class pragmas</H4>
<a name="n34"></a><H4>17.4.2.1 The Java module class pragmas</H4>
The module class can be tailored through the use of pragmas, in the same manner as the intermediary JNI class. The pragmas are similarly named and are used in the same way. The complete list follows:
@ -1712,7 +1712,7 @@ See <a href="#imclass_pragmas">The intermediary JNI class pragmas</a> section fo
<a name="java_proxy_classes"></a>
<a name="n35"></a><H3>15.4.3 Java proxy classes</H3>
<a name="n35"></a><H3>17.4.3 Java proxy classes</H3>
A Java proxy class is generated for each structure, union or C++ class that is wrapped.
@ -1783,7 +1783,7 @@ int y = f.spam(5, new Foo());
</blockquote>
<a name="memory_management"></a>
<a name="n36"></a><H4>15.4.3.1 Memory management</H4>
<a name="n36"></a><H4>17.4.3.1 Memory management</H4>
Each proxy class has an ownership flag <tt>swigCMemOwn</tt>. The value of this
@ -1916,7 +1916,7 @@ Obj obj = Factory.createObj(); // obj.swigCMemOwn = true;
<a name="inheritance_mirroring"></a>
<a name="n37"></a><H4>15.4.3.2 Inheritance</H4>
<a name="n37"></a><H4>17.4.3.2 Inheritance</H4>
Java proxy classes will mirror C++ inheritance chains. For example, given the base class <tt>Base</tt> and its derived class </tt>Derived</tt>:
@ -2024,7 +2024,7 @@ However, true cross language polymorphism can be achieved using the <a href="#ja
<a name="proxy_classes_gc"></a>
<a name="n38"></a><H4>15.4.3.3 Proxy classes and garbage collection</H4>
<a name="n38"></a><H4>17.4.3.3 Proxy classes and garbage collection</H4>
By default each proxy class has a <tt>delete()</tt> and a <tt>finalize()</tt> method.
@ -2095,7 +2095,7 @@ The section on <a href="#java_typemaps">Java typemaps</a> details how to specify
</ol>
<a name="type_wrapper_classes"></a>
<a name="n39"></a><H3>15.4.4 Type wrapper classes</H3>
<a name="n39"></a><H3>17.4.4 Type wrapper classes</H3>
The generated type wrapper class, for say an <tt>int *</tt>, looks like this:
@ -2170,7 +2170,7 @@ public static void spam(SWIGTYPE_p_int x, SWIGTYPE_p_int y, int z) { ... }
<p>
<a name="java_directors"></a>
<a name="n40"></a><H2>15.5 Cross language polymorphism using directors (experimental)</H2>
<a name="n40"></a><H2>17.5 Cross language polymorphism using directors (experimental)</H2>
Proxy classes provide a natural, object-oriented way to wrap C++ classes.
@ -2189,7 +2189,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.
<a name="java_enabling_directors"></a>
<a name="n41"></a><H3>15.5.1 Enabling directors</H3>
<a name="n41"></a><H3>17.5.1 Enabling directors</H3>
The director feature is disabled by default.
@ -2252,7 +2252,7 @@ public:
</blockquote>
<a name="java_directors_classes"></a>
<a name="n42"></a><H3>15.5.2 Director classes</H3>
<a name="n42"></a><H3>17.5.2 Director classes</H3>
For each class that has directors enabled, SWIG generates a new class that derives from both the class in question and a special <tt>Swig::Director</tt> class.
@ -2277,7 +2277,7 @@ If the correct implementation is in Java, the Java API is used to call the metho
<a name="java_directors_overhead"></a>
<a name="n43"></a><H3>15.5.3 Overhead and code bloat</H3>
<a name="n43"></a><H3>17.5.3 Overhead and code bloat</H3>
Enabling directors for a class will generate a new director method for every virtual method in the class' inheritance chain.
@ -2293,7 +2293,7 @@ This situation can be optimized by selectively enabling director methods (using
<a name="java_directors_example"></a>
<a name="n44"></a><H3>15.5.4 Simple directors example</H3>
<a name="n44"></a><H3>17.5.4 Simple directors example</H3>
<p>
@ -2354,7 +2354,7 @@ directorDerived::upcall_method() invoked.
</blockquote>
<a name="common_customization"></a>
<a name="n45"></a><H2>15.6 Common customization features</H2>
<a name="n45"></a><H2>17.6 Common customization features</H2>
An earlier section presented the absolute basics of C/C++ wrapping. If you do nothing
@ -2365,7 +2365,7 @@ be awkward. This section describes some common SWIG features that are used
to improve the interface to existing C/C++ code.
<a name="helper_functions"></a>
<a name="n46"></a><H3>15.6.1 C/C++ helper functions</H3>
<a name="n46"></a><H3>17.6.1 C/C++ helper functions</H3>
Sometimes when you create a module, it is missing certain bits of functionality. For
@ -2424,7 +2424,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.
<a name="class_extension"></a>
<a name="n47"></a><H3>15.6.2 Class extension with %extend</H3>
<a name="n47"></a><H3>17.6.2 Class extension with %extend</H3>
One of the more interesting features of SWIG is that it can extend
@ -2479,7 +2479,7 @@ Vector(2,3,4)
in any way---the extensions only show up in the Java interface.
<a name="exception_handling"></a>
<a name="n48"></a><H3>15.6.3 Exception handling with %exception</H3>
<a name="n48"></a><H3>17.6.3 Exception handling with %exception</H3>
If a C or C++ function throws an error, you may want to convert that error into a Java
@ -2579,7 +2579,7 @@ The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html">SWIG Library</a> chapter.
<a name="method_access"></a>
<a name="n49"></a><H3>15.6.4 Method access with %javamethodmodifiers</H3>
<a name="n49"></a><H3>17.6.4 Method access with %javamethodmodifiers</H3>
A Java feature called <tt>%javamethodmodifiers</tt> can be used to change the method modifiers from the default <tt>public</tt>. It applies to both module class methods and proxy class methods. For example:
@ -2602,7 +2602,7 @@ protected static void protect_me() {
</blockquote>
<a name="tips_techniques"></a>
<a name="n50"></a><H2>15.7 Tips and techniques</H2>
<a name="n50"></a><H2>17.7 Tips and techniques</H2>
Although SWIG is largely automatic, there are certain types of wrapping problems that
@ -2611,7 +2611,7 @@ strings and arrays. This chapter discusses the common techniques for
solving these problems.
<a name="input_output_parameters"></a>
<a name="n51"></a><H3>15.7.1 Input and output parameters using primitive pointers and references</H3>
<a name="n51"></a><H3>17.7.1 Input and output parameters using primitive pointers and references</H3>
A common problem in some C programs is handling parameters passed as simple pointers or references. For
@ -2754,7 +2754,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>.
<a name="simple_pointers"></a>
<a name="n52"></a><H3>15.7.2 Simple pointers</H3>
<a name="n52"></a><H3>17.7.2 Simple pointers</H3>
If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> another approach to using
@ -2808,7 +2808,7 @@ System.out.println("3 + 4 = " + result);
See the <a href="Library.html">SWIG Library</a> chapter for further details.
<a name="c_arrays"></a>
<a name="n53"></a><H3>15.7.3 Wrapping C arrays with Java arrays</H3>
<a name="n53"></a><H3>17.7.3 Wrapping C arrays with Java arrays</H3>
SWIG can wrap arrays in a more natural Java manner than the default by using the <tt>arrays_java.i</tt> library file.
@ -2866,7 +2866,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.
<a name="unbounded_c_arrays"></a>
<a name="n54"></a><H3>15.7.4 Unbounded C Arrays</H3>
<a name="n54"></a><H3>17.7.4 Unbounded C Arrays</H3>
Sometimes a C function expects an array to be passed as a pointer. For example,
@ -2992,7 +2992,7 @@ well suited for applications in which you need to create buffers,
package binary data, etc.
<a name="java_typemaps"></a>
<a name="n55"></a><H2>15.8 Java typemaps</H2>
<a name="n55"></a><H2>17.8 Java typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -3012,7 +3012,7 @@ 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.
<a name="default_primitive_type_mappings"></a>
<a name="n56"></a><H3>15.8.1 Default primitive type mappings</H3>
<a name="n56"></a><H3>17.8.1 Default primitive type mappings</H3>
The following table lists the default type mapping from Java to C/C++.<p>
@ -3144,7 +3144,7 @@ However, the mappings allow the full range of values for each C type from Java.
<p>
<a name="jvm64"></a>
<a name="n57"></a><H3>15.8.2 Sixty four bit JVMs</H3>
<a name="n57"></a><H3>17.8.2 Sixty four bit JVMs</H3>
If you are using a 64 bit JVM you may have to override the C long, but probably not C int default mappings.
@ -3156,7 +3156,7 @@ Unfortunately it won't of course hold true for JNI code.
<a name="what_is_typemap"></a>
<a name="n58"></a><H3>15.8.3 What is a typemap?</H3>
<a name="n58"></a><H3>17.8.3 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached to
@ -3257,7 +3257,7 @@ int c = example.count('e',"Hello World");
</blockquote>
<a name="typemaps_c_to_java_types"></a>
<a name="n59"></a><H3>15.8.4 Typemaps for mapping C/C++ types to Java types</H3>
<a name="n59"></a><H3>17.8.4 Typemaps for mapping C/C++ types to Java types</H3>
The typemaps available to the Java module include the common typemaps listed in the main typemaps section.
@ -3441,7 +3441,7 @@ These are listed below:
</table>
<a name="special_variables"></a>
<a name="n60"></a><H3>15.8.5 Java special variables</H3>
<a name="n60"></a><H3>17.8.5 Java special variables</H3>
The standard SWIG special variables are available for use within typemaps as described in the <a href=Typemaps.html>Typemaps documentation</a>, for example <tt>$1</tt>, <tt>$input</tt>,<tt>$result</tt> etc.
@ -3544,7 +3544,7 @@ public static Class bar(Class cls, int ush) {
These special variables used in the directors typemaps. See <a href="#java_directors_typemaps">Director specific typemaps</a> for details.
<a name="typemaps_for_c_and_c++"></a>
<a name="n61"></a><H3>15.8.6 Typemaps for both C and C++ compilation</H3>
<a name="n61"></a><H3>17.8.6 Typemaps for both C and C++ compilation</H3>
JNI calls must be written differently depending on whether the code is being compiled as C or C++.
@ -3575,7 +3575,7 @@ If you do not intend your code to be targeting both C and C++ then your typemaps
<a name="java_code_typemaps"></a>
<a name="n62"></a><H3>15.8.7 Java code typemaps</H3>
<a name="n62"></a><H3>17.8.7 Java code typemaps</H3>
Most of SWIG's typemaps are used for the generation of C/C++ code.
@ -3705,7 +3705,7 @@ Note that <tt>SWIGTYPE</tt> will target all proxy classes, but not all type wrap
<p>
<a name="java_directors_typemaps"></a>
<a name="n63"></a><H3>15.8.8 Director specific typemaps</H3>
<a name="n63"></a><H3>17.8.8 Director specific typemaps</H3>
The Java directors feature requires the "javadirectorin", "javadirectorout" and the "directorin" typemaps in order to work properly.
@ -3858,7 +3858,7 @@ The basic strategy here is to provide a default package typemap for the majority
</blockquote>
<a name="typemap_examples"></a>
<a name="n64"></a><H2>15.9 Typemap Examples</H2>
<a name="n64"></a><H2>17.9 Typemap Examples</H2>
This section includes a few examples of typemaps. For more examples, you
@ -3867,7 +3867,7 @@ the SWIG library.
<a name="converting_java_string_arrays"></a>
<a name="n65"></a><H3>15.9.1 Converting Java String arrays to char ** </H3>
<a name="n65"></a><H3>17.9.1 Converting Java String arrays to char ** </H3>
A common problem in many C programs is the processing of command line arguments, which are usually passed in an array of NULL terminated strings.
@ -4000,7 +4000,7 @@ Lastly the "jni", "jtype" and "jstype" typemaps are also required to specify
what Java types to use.
<a name="expanding_java_object"></a>
<a name="n66"></a><H3>15.9.2 Expanding a Java object to multiple arguments</H3>
<a name="n66"></a><H3>17.9.2 Expanding a Java object to multiple arguments</H3>
Suppose that you had a collection of C functions with arguments
@ -4074,7 +4074,7 @@ example.foo(new String[]{"red", "green", "blue", "white"});
<a name="using_typemaps_return_arguments"></a>
<a name="n67"></a><H3>15.9.3 Using typemaps to return arguments</H3>
<a name="n67"></a><H3>17.9.3 Using typemaps to return arguments</H3>
A common problem in some C programs is that values may be returned in function parameters rather than in the return value of a function.
@ -4175,7 +4175,7 @@ $ java main
</pre></blockquote>
<a name="adding_downcasts"></a>
<a name="n68"></a><H3>15.9.4 Adding Java downcasts to polymorphic return types</H3>
<a name="n68"></a><H3>17.9.4 Adding Java downcasts to polymorphic return types</H3>
SWIG support for polymorphism works in that the appropriate virtual function is called. However, the default generated code does not allow for downcasting.
@ -4359,7 +4359,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.
<a name="adding_equals_method"></a>
<a name="n69"></a><H3>15.9.5 Adding an equals method to the Java classes</H3>
<a name="n69"></a><H3>17.9.5 Adding an equals method to the Java classes</H3>
When a pointer is returned from a JNI function, it is wrapped using a new Java proxy class or type wrapper class.
@ -4395,7 +4395,7 @@ System.out.println("foo1? " + foo1.equals(foo2));
<a name="void_pointers"></a>
<a name="n70"></a><H3>15.9.6 Void pointers and a common Java base class</H3>
<a name="n70"></a><H3>17.9.6 Void pointers and a common Java base class</H3>
One might wonder why the common code that SWIG emits for the proxy and type wrapper classes is not pushed into a base class.
@ -4447,7 +4447,7 @@ This example contains some useful functionality which you may want in your code.
</ul>
<a name="java_directors_faq"></a>
<a name="n71"></a><H2>15.10 Living with Java Directors</H2>
<a name="n71"></a><H2>17.10 Living with Java Directors</H2>
<p>
@ -4613,11 +4613,11 @@ public abstract class UserVisibleFoo extends Foo {
</ol>
<a name="odds_ends"></a>
<a name="n72"></a><H2>15.11 Odds and ends</H2>
<a name="n72"></a><H2>17.11 Odds and ends</H2>
<a name="javadoc_comments"></a>
<a name="n73"></a><H3>15.11.1 JavaDoc comments</H3>
<a name="n73"></a><H3>17.11.1 JavaDoc comments</H3>
The SWIG documentation system is currently deprecated.
@ -4669,7 +4669,7 @@ public class Barmy {
<a name="functional_interface"></a>
<a name="n74"></a><H3>15.11.2 Functional interface without proxy classes</H3>
<a name="n74"></a><H3>17.11.2 Functional interface without proxy classes</H3>
It is possible to run SWIG in a mode that does not produce proxy classes by using the -noproxy commandline option.
@ -4721,7 +4721,7 @@ All destructors have to be called manually for example the <tt>delete_Foo(foo)</
<a name="using_own_jni_functions"></a>
<a name="n75"></a><H3>15.11.3 Using your own JNI functions</H3>
<a name="n75"></a><H3>17.11.3 Using your own JNI functions</H3>
You may have some hand written JNI functions that you want to use in addition to the SWIG generated JNI functions.
@ -4762,7 +4762,7 @@ This directive is only really useful if you want to mix your own hand crafted JN
<a name="performance"></a>
<a name="n76"></a><H3>15.11.4 Performance concerns and hints</H3>
<a name="n76"></a><H3>17.11.4 Performance concerns and hints</H3>
If you're directly manipulating huge arrays of complex objects from Java, performance may suffer greatly when using the array functions in <tt>arrays_java.i</tt>.
@ -4780,7 +4780,7 @@ This method calls the C++ destructor or <tt>free()</tt> for C code.
<a name="java_examples"></a>
<a name="n77"></a><H2>15.12 Examples</H2>
<a name="n77"></a><H2>17.12 Examples</H2>
The directory Examples/java has a number of further examples.

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>12 SWIG library</H1>
<a name="n1"></a><H1>13 SWIG library</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">The %include directive and library search path</a>
@ -50,7 +50,7 @@ these files are now deprecated and have been removed from the distribution.
Alternative libraries provide similar functionality. Please read this chapter
carefully if you used the old libraries.
<a name="n2"></a><H2>12.1 The %include directive and library search path</H2>
<a name="n2"></a><H2>13.1 The %include directive and library search path</H2>
Library files are included using the <tt>%include</tt> directive.
@ -73,7 +73,7 @@ for language-specific implementations of library files.
You can override the location of the SWIG library by setting the
<tt>SWIG_LIB</tt> environment variable.<p>
<a name="n3"></a><H2>12.2 C Arrays and Pointers</H2>
<a name="n3"></a><H2>13.2 C Arrays and Pointers</H2>
This section describes library modules for manipulating low-level C arrays and pointers.
@ -83,7 +83,7 @@ used to allocate memory, manufacture pointers, dereference memory, and wrap
pointers as class-like objects. Since these functions provide direct access to
memory, their use is potentially unsafe and you should exercise caution.
<a name="n4"></a><H3>12.2.1 cpointer.i</H3>
<a name="n4"></a><H3>13.2.1 cpointer.i</H3>
The <tt>cpointer.i</tt> module defines macros that can be used to used
@ -250,7 +250,7 @@ In this example, the function <tt>int_to_uint()</tt> would be used to cast type
<P>
<b>Note:</b> When working with simple pointers, typemaps can often be used to provide more seamless operation.
<a name="n5"></a><H3>12.2.2 carrays.i</H3>
<a name="n5"></a><H3>13.2.2 carrays.i</H3>
This module defines macros that assist in wrapping ordinary C pointers as arrays.
@ -395,7 +395,7 @@ you should consider using a special array object rather than a bare pointer.
<b>Note:</b> <tt>%array_functions()</tt> and <tt>%array_class()</tt> should not be
used with types of <tt>char</tt> or <tt>char *</tt>.
<a name="n6"></a><H3>12.2.3 cmalloc.i</H3>
<a name="n6"></a><H3>13.2.3 cmalloc.i</H3>
This module defines macros for wrapping the low-level C memory allocation functions
@ -507,7 +507,7 @@ Now, in a script:
</pre>
</blockquote>
<a name="n7"></a><H3>12.2.4 cdata.i</H3>
<a name="n7"></a><H3>13.2.4 cdata.i</H3>
The <tt>cdata.i</tt> module defines functions for converting raw C data to and from strings
@ -580,7 +580,7 @@ char *cdata_<em>name</em>(int nitems)
<b>Note:</b> These functions provide direct access to memory and can be used to overwrite data.
Clearly they are unsafe.
<a name="n8"></a><H2>12.3 C String Handling</H2>
<a name="n8"></a><H2>13.3 C String Handling</H2>
A common problem when working with C programs is dealing with
@ -597,7 +597,7 @@ well-known. However, SWIG is not in the business of enforcing
morality. The modules in this section provide basic functionality
for manipulating raw C strings.
<a name="n9"></a><H3>12.3.1 Default string handling</H3>
<a name="n9"></a><H3>13.3.1 Default string handling</H3>
Suppose you have a C function with this prototype:
@ -631,7 +631,7 @@ a <tt>char *</tt> argument points to data inside the target language, it is
interpreter and lead to a crash). Furthermore, the default behavior does
not work well with binary data. Instead, strings are assumed to be NULL-terminated.
<a name="n10"></a><H3>12.3.2 Passing binary data</H3>
<a name="n10"></a><H3>13.3.2 Passing binary data</H3>
If you have a function that expects binary data,
@ -664,7 +664,7 @@ Now, in the target language, you can use binary string data like this:
In the wrapper function, the passed string will be expanded to a pointer and length parameter.
<a name="n11"></a><H3>12.3.3 Using %newobject to release memory</H3>
<a name="n11"></a><H3>13.3.3 Using %newobject to release memory</H3>
If you have a function that allocates memory like this,
@ -695,7 +695,7 @@ char *foo();
This will release the result.
<a name="n12"></a><H3>12.3.4 cstring.i</H3>
<a name="n12"></a><H3>13.3.4 cstring.i</H3>
The <tt>cstring.i</tt> library file provides a collection of macros
@ -1066,14 +1066,14 @@ allocation. If using ANSI C, the library uses <tt>malloc()</tt> and <tt>free()<
structure or class instead.
</ul>
<a name="n13"></a><H2>12.4 C++ Library</H2>
<a name="n13"></a><H2>13.4 C++ Library</H2>
The library modules in this section provide access to parts of the standard C++ library.
All of these modules are new in SWIG-1.3.12 and are only the beginning phase of more complete
C++ library support including support for the STL.
<a name="n14"></a><H3>12.4.1 std_string.i</H3>
<a name="n14"></a><H3>13.4.1 std_string.i</H3>
The <tt>std_string.i</tt> library provides typemaps for converting C++ <tt>std::string</tt>
@ -1121,7 +1121,7 @@ void foo(string s, const String &t); // std_string typemaps still applied
<b>Note:</b> The <tt>std_string</tt> library is incompatible with Perl on some platforms.
We're looking into it.
<a name="n15"></a><H3>12.4.2 std_vector.i</H3>
<a name="n15"></a><H3>13.4.2 std_vector.i</H3>
The <tt>std_vector.i</tt> library provides support for the C++ <tt>vector</tt> class in the STL.
@ -1290,10 +1290,10 @@ details and the public API exposed to the interpreter vary.
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
<a name="n16"></a><H2>12.5 Utility Libraries</H2>
<a name="n16"></a><H2>13.5 Utility Libraries</H2>
<a name="n17"></a><H3>12.5.1 exception.i</H3>
<a name="n17"></a><H3>13.5.1 exception.i</H3>
The <tt>exception.i</tt> library provides a language-independent function for raising a run-time

165
SWIG/Doc/Manual/Modules.html Normal file
View file

@ -0,0 +1,165 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Working with Modules</title>
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>14 Working with Modules</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">The SWIG runtime code</a>
<li><a href="#n3">Compiling Multiple SWIG modules</a>
<li><a href="#n4">A word of caution about static libraries</a>
<li><a href="#n5">References</a>
</ul>
<!-- INDEX -->
When first working with SWIG, users commonly start by creating a
single module. That is, you might define a single SWIG interface that
wraps some set of C code. You then compile all of the generated
wrapper code into a module and use it. For large applications, however,
this approach is problematic---the size of the generated wrapper code
can be rather large. Moreover, it is probably easier to manage the
scripting interface when it is broken up into smaller pieces.
<p>
This chapter describes the problem of using SWIG in programs
where you want to create a collection of modules.
<a name="n2"></a><H2>14.1 The SWIG runtime code</H2>
All SWIG-generated wrapper modules include a set of functions
commonly known as the "SWIG runtime." These functions are
primarily related to the runtime type system which checks pointer
types and performs other tasks such as proper casting of pointer
values in C++.
<p>
By default, the runtime functions are private to each SWIG-generated
module. That is, the runtime functions are declared with "static"
linkage and are visible only to the wrapper functions defined in that
module. If two completely different SWIG modules are loaded, this
presents no problem---each module uses its own private runtime code.
The only problem with this approach is that when more than one SWIG
module is used in the same application, those modules often need to
share type information. This is especially true for C++ programs
where SWIG must collect and share information about inheritance
relationships that cross module boundaries.
<p>
To solve the problem of sharing information across modules, the
SWIG runtime functions need to be exposed in a way that allows data to
be shared between modules. The next section describes how to do that.
<a name="n3"></a><H2>14.2 Compiling Multiple SWIG modules</H2>
Suppose that you have three SWIG interface files A.i, B.i, and C.i
and suppose that these modules interact with each other. To make this work,
there are two approaches you can take:
<p>
<b>Option 1:</b> Designate one module to provide the runtime code
<p>
With this option, one of the modules is designated as providing the runtime
environment. This is done with the <tt>-runtime</tt> option like this:
<blockquote>
<pre>
% swig -runtime -c++ -python A.i
</pre>
</blockquote>
The other modules are then compiled without runtime support. This is done by
supplying the <tt>-noruntime</tt> option like this:
<blockquote>
<pre>
% swig -noruntime -c++ -python B.i
% swig -noruntime -c++ -python C.i
</pre>
</blockquote>
To use the modules, you compile and link everything as before, but you
need to make sure that module A is loaded before all of the other
modules are used---otherwise you will unresolved symbols.
<p>
Now, the bad news: This approach may or may not work depending on the platform you
are using, what target language you are using, and the way that shared libraries work
on the system. On many systems, the symbols contained in dynamically loaded modules
are private. Therefore, even though module A provides the runtime code, the other modules
won't be able to find it. You'll know if this is the case if you try to load the other modules
and you get errors about unresolved SWIG_* functions.
<p>
<b>Option 2: Build a runtime library</b>
<p>
The second way to work with multiple modules is to create a special runtime library module.
To do this, you first build a runtime library like this:
<blockquote>
<pre>
% swig -runtime -python swigrun.i
% # Build a shared library --- this is different on every machine! (shown for Linux)
% gcc -fpic swigrun_wrap.c -o swigrun_wrap.o
% gcc -shared swigrun_wrap.o -o libswigrunpy.so
</pre>
</blockquote>
Now, you compile all of the normal SWIG modules using the <tt>-noruntime</tt> option:
<blockquote>
<pre>
% swig -noruntime -c++ -python A.i
% swig -noruntime -c++ -python B.i
% swig -noruntime -c++ -python C.i
</pre>
</blockquote>
Finally, when linking the dynamically loadable modules, you need to link again the special
runtime library above. For example (Linux) :
<blockquote>
<pre>
% g++ -shared A_wrap.o -L. -lswigrunpy -o _A.so
% g++ -shared B_wrap.o -L. -lswigrunpy -o _B.so
% g++ -shared C_wrap.o -L. -lswigrunpy -o _C.so
</pre>
</blockquote>
Again, all of the details will vary depending on what compiler you use, the platform, target language,
and so forth. The key point is that the runtime needs to be contained in a shared/dynamic library and
you need to link all of the modules against that library.
<p>
When you use the modules created using this technique, the runtime code will be automatically loaded
when the modules are imported. Moreover, since all of the modules are linked against the same runtime
library, they will share that code.
<a name="n4"></a><H2>14.3 A word of caution about static libraries</H2>
When working with multiple SWIG modules, you should take care not to use static
libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
of SWIG modules with that library, each module will get its own private copy of the library code inserted
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
<a name="n5"></a><H2>14.4 References</H2>
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
<p><hr>
<address>SWIG 1.3 - Last Modified : November 22, 2003</address>
</body>
</html>

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

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<a name="n1"></a><H1>16 SWIG and Ocaml</H1>
<a name="n1"></a><H1>18 SWIG and Ocaml</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -73,7 +73,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>
<a name="n2"></a><H2>16.1 Preliminaries</H2>
<a name="n2"></a><H2>18.1 Preliminaries</H2>
SWIG 1.3 works with Ocaml 3.04 and above. Given the choice,
@ -90,7 +90,7 @@ usual -lxxx against libxxx.so, as well as with Gerd Stolpmann's
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.
<a name="n3"></a><H3>16.1.1 Running SWIG</H3>
<a name="n3"></a><H3>18.1.1 Running SWIG</H3>
The basics of getting a SWIG Ocaml module up and running
@ -109,7 +109,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>
<a name="n4"></a><H3>16.1.2 Compiling the code</H3>
<a name="n4"></a><H3>18.1.2 Compiling the code</H3>
The O'Caml SWIG module now requires you to compile a module (<tt>Swig</tt>)
@ -141,7 +141,7 @@ the user more freedom with respect to custom typing.
<pre>% cp example_wrap.cxx example_wrap.cxx.c<br>% ocamlc -c ... -ccopt -xc++ example_wrap.cxx.c<br>% ...<br></pre>
</blockquote>
<a name="n5"></a><H3>16.1.3 The camlp4 module</H3>
<a name="n5"></a><H3>18.1.3 The camlp4 module</H3>
The camlp4 module (swigp4.ml -&gt; swigp4.cmo) contains a simple rewriter which
@ -211,7 +211,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<a name="n6"></a><H3>16.1.4 Using your module</H3>
<a name="n6"></a><H3>18.1.4 Using your module</H3>
You can test-drive your module by building a
@ -221,7 +221,7 @@ toplevel ocaml interpreter. Consult the ocaml manual for details.
option to build your functions into the primitive list. This
option is not needed when you build native code.
<a name="n7"></a><H3>16.1.5 Compilation problems and compiling with C++</H3>
<a name="n7"></a><H3>18.1.5 Compilation problems and compiling with C++</H3>
As mentioned above, .cxx files need special
@ -230,7 +230,7 @@ that uses <tt>class</tt> as a non-keyword, and C code that is too
liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
<a name="n8"></a><H2>16.2 The low-level Ocaml/C interface</H2>
<a name="n8"></a><H2>18.2 The low-level Ocaml/C interface</H2>
In order to provide access to overloaded functions, and
@ -317,7 +317,7 @@ is that you must append them to the return list with swig_result = caml_list_a
value items pass through directly, but you must make your own type
signature for a function that uses value in this way.
<a name="n9"></a><H3>16.2.1 The generated module</H3>
<a name="n9"></a><H3>18.2.1 The generated module</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Ocaml
@ -347,7 +347,7 @@ which should run when the module is loaded may be inserted here.
it describes the output SWIG will generate for class definitions.
</table>
<a name="n10"></a><H3>16.2.2 Enums</H3>
<a name="n10"></a><H3>18.2.2 Enums</H3>
SWIG will wrap enumerations as polymorphic variants in the output
@ -403,10 +403,10 @@ val x : Enum_test.c_obj = C_enum `a
<p> </p>
<a name="n11"></a><H3>16.2.3 Arrays</H3>
<a name="n11"></a><H3>18.2.3 Arrays</H3>
<a name="n12"></a><H4>16.2.3.1 Simple types of bounded arrays</H4>
<a name="n12"></a><H4>18.2.3.1 Simple types of bounded arrays</H4>
<p>
@ -426,7 +426,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<a name="n13"></a><H4>16.2.3.2 Complex and unbounded arrays</H4>
<a name="n13"></a><H4>18.2.3.2 Complex and unbounded arrays</H4>
<p>
@ -439,7 +439,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>
<a name="n14"></a><H4>16.2.3.3 Using an object</H4>
<a name="n14"></a><H4>18.2.3.3 Using an object</H4>
<p>
@ -453,7 +453,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required centinel, etc.
</p>
<a name="n15"></a><H4>16.2.3.4 Example typemap for a function taking float * and int</H4>
<a name="n15"></a><H4>18.2.3.4 Example typemap for a function taking float * and int</H4>
<p>
@ -503,7 +503,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<a name="n16"></a><H3>16.2.4 C++ Classes</H3>
<a name="n16"></a><H3>18.2.4 C++ Classes</H3>
C++ classes, along with structs and unions are represented by C_obj
@ -541,7 +541,7 @@ the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
<p>
<a name="n17"></a><H4>16.2.4.1 STL vector and string Example</H4>
<a name="n17"></a><H4>18.2.4.1 STL vector and string Example</H4>
Standard typemaps are now provided for STL vector and string. More are in
@ -613,7 +613,7 @@ baz
#
</pre></blockquote>
<a name="n18"></a><H4>16.2.4.2 C++ Class Example</H4>
<a name="n18"></a><H4>18.2.4.2 C++ Class Example</H4>
Here's a simple example using Trolltech's Qt Library:
@ -640,7 +640,7 @@ public:
};
</pre></td></tr></table><p>
<a name="n19"></a><H4>16.2.4.3 Compiling the example</H4>
<a name="n19"></a><H4>18.2.4.3 Compiling the example</H4>
<blockquote><pre>
@ -658,7 +658,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></blockquote>
<a name="n20"></a><H4>16.2.4.4 Sample Session</H4>
<a name="n20"></a><H4>18.2.4.4 Sample Session</H4>
<blockquote><pre>
@ -683,10 +683,10 @@ val hello : Qt.c_obj = C_obj <fun>
Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
<a name="n21"></a><H3>16.2.5 Director Classes</H3>
<a name="n21"></a><H3>18.2.5 Director Classes</H3>
<a name="n22"></a><H4>16.2.5.1 Director Introduction</H4>
<a name="n22"></a><H4>18.2.5.1 Director Introduction</H4>
Director classes are classes which allow Ocaml code to override the public
@ -708,7 +708,7 @@ class foo {
};
</p></blockquote></pre>
<a name="n23"></a><H4>16.2.5.2 Overriding Methods in Ocaml</H4>
<a name="n23"></a><H4>18.2.5.2 Overriding Methods in Ocaml</H4>
<p>
@ -732,7 +732,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>
<a name="n24"></a><H4>16.2.5.3 Director Usage Example</H4>
<a name="n24"></a><H4>18.2.5.3 Director Usage Example</H4>
<table border="1" bgcolor="#dddddd"><tr><th><center>example_prog.ml</center>
@ -786,7 +786,7 @@ a tricky shape implementation, such as a boolean combination, to be expressed
in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
<p>
<a name="n25"></a><H4>16.2.5.4 Creating director objects</H4>
<a name="n25"></a><H4>18.2.5.4 Creating director objects</H4>
The definition of the actual object triangle can be described this way:
@ -820,7 +820,7 @@ new_derived_object, and throws NotObject). This prevents a deleted C++
object from causing a core dump, as long as the object is destroyed
properly.
<a name="n26"></a><H4>16.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<a name="n26"></a><H4>18.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<p>
@ -830,7 +830,7 @@ direction is reversed. They provide for you to provide argout values, as
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>
<a name="n27"></a><H4>16.2.5.6 <tt>directorin</tt> typemap</H4>
<a name="n27"></a><H4>18.2.5.6 <tt>directorin</tt> typemap</H4>
<p>
@ -841,7 +841,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>
<a name="n28"></a><H4>16.2.5.7 <tt>directorout</tt> typemap</H4>
<a name="n28"></a><H4>18.2.5.7 <tt>directorout</tt> typemap</H4>
<p>
@ -852,7 +852,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<a name="n29"></a><H4>16.2.5.8 <tt>directorargout</tt> typemap</H4>
<a name="n29"></a><H4>18.2.5.8 <tt>directorargout</tt> typemap</H4>
<p>
@ -869,7 +869,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>
<a name="n30"></a><H3>16.2.6 Exceptions</H3>
<a name="n30"></a><H3>18.2.6 Exceptions</H3>
Catching exceptions is now supported using SWIG's %exception feature. A simple

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>17 SWIG and Perl5</H1>
<a name="n1"></a><H1>19 SWIG and Perl5</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Overview</a>
@ -78,7 +78,7 @@ best results, it is recommended that SWIG be used with Perl5.003 or
later. Earlier versions are problematic and SWIG generated extensions
may not compile or run correctly.<p>
<a name="n2"></a><H2>17.1 Overview</H2>
<a name="n2"></a><H2>19.1 Overview</H2>
To build Perl extension modules, SWIG uses a layered approach. At
@ -96,7 +96,7 @@ procedural interface is presented. Finally, proxy classes are
described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
<a name="n3"></a><H2>17.2 Preliminaries</H2>
<a name="n3"></a><H2>19.2 Preliminaries</H2>
To build a Perl5 module, run Swig using the <tt>-perl</tt> option as
@ -116,7 +116,7 @@ properly load the module.
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.
<a name="n4"></a><H3>17.2.1 Getting the right header files</H3>
<a name="n4"></a><H3>19.2.1 Getting the right header files</H3>
In order to compile, SWIG extensions need the following Perl5 header files :<p>
@ -145,7 +145,7 @@ loaded, an easy way to find out is to run Perl itself.
</pre>
</blockquote>
<a name="n5"></a><H3>17.2.2 Compiling a dynamic module</H3>
<a name="n5"></a><H3>19.2.2 Compiling a dynamic module</H3>
The preferred approach to building an extension module is to compile it into
@ -172,7 +172,7 @@ the SWIG interface file. If you used `<tt>%module example</tt>', then
the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
<a name="n6"></a><H3>17.2.3 Building a dynamic module with MakeMaker</H3>
<a name="n6"></a><H3>19.2.3 Building a dynamic module with MakeMaker</H3>
It is also possible to use Perl to build dynamically loadable modules
@ -204,7 +204,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>
<a name="n7"></a><H3>17.2.4 Building a static version of Perl</H3>
<a name="n7"></a><H3>19.2.4 Building a static version of Perl</H3>
If you machine does not support dynamic loading or if you've tried to
@ -267,7 +267,7 @@ should be functionality identical to Perl with your C/C++ extension
added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
<a name="n8"></a><H3>17.2.5 Using the module</H3>
<a name="n8"></a><H3>19.2.5 Using the module</H3>
To use the module, simply use the Perl <tt>use</tt> statement. If
@ -398,7 +398,7 @@ Finally, you can use a command such as <tt>ldconfig</tt> (Linux) or
system configuration (this requires root access and you will need to
read the man pages).
<a name="n9"></a><H3>17.2.6 Compilation problems and compiling with C++</H3>
<a name="n9"></a><H3>19.2.6 Compilation problems and compiling with C++</H3>
Compilation of C++ extensions has traditionally been a tricky problem.
@ -520,7 +520,7 @@ in Lib/perl5/noembed.h while compiling the wrapper, you will
have to find the macro that conflicts and add an #undef into the .i file. Please report
any conflicting macros you find to <a href="mailto:swig@cs.uchicago.edu">swig@cs.uchicago.edu</a>.
<a name="n10"></a><H3>17.2.7 Compiling for 64-bit platforms</H3>
<a name="n10"></a><H3>19.2.7 Compiling for 64-bit platforms</H3>
On platforms that support 64-bit applications (Solaris, Irix, etc.),
@ -543,7 +543,7 @@ that software. This may prevent the use of 64-bit extensions. It may
also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
<a name="n11"></a><H2>17.3 Building Perl Extensions under Windows</H2>
<a name="n11"></a><H2>19.3 Building Perl Extensions under Windows</H2>
Building a SWIG extension to Perl under Windows is roughly
@ -552,7 +552,7 @@ produce a DLL that can be loaded into the Perl interpreter. This
section assumes you are using SWIG with Microsoft Visual C++
although the procedure may be similar with other compilers.
<a name="n12"></a><H3>17.3.1 Running SWIG from Developer Studio</H3>
<a name="n12"></a><H3>19.3.1 Running SWIG from Developer Studio</H3>
If you are developing your application within Microsoft developer
@ -613,13 +613,13 @@ print "$a\n";
</pre></blockquote>
<a name="n13"></a><H3>17.3.2 Using other compilers</H3>
<a name="n13"></a><H3>19.3.2 Using other compilers</H3>
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</a> chapter.
<a name="n14"></a><H2>17.4 The low-level interface</H2>
<a name="n14"></a><H2>19.4 The low-level interface</H2>
At its core, the Perl module uses a simple low-level interface
@ -627,7 +627,7 @@ to C function, variables, constants, and classes. This low-level interface
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.
<a name="n15"></a><H3>17.4.1 Functions</H3>
<a name="n15"></a><H3>19.4.1 Functions</H3>
C functions are converted into new Perl built-in commands (or
@ -645,7 +645,7 @@ Now, in Perl:
$a = &amp;example::fact(2);
</pre></blockquote>
<a name="n16"></a><H3>17.4.2 Global variables</H3>
<a name="n16"></a><H3>19.4.2 Global variables</H3>
Global variables are handled using Perl's magic
@ -698,7 +698,7 @@ extern char *path; // Declared later in the input
</pre>
</blockquote>
<a name="n17"></a><H3>17.4.3 Constants</H3>
<a name="n17"></a><H3>19.4.3 Constants</H3>
Constants are wrapped as read-only Perl variables. For example:
@ -721,7 +721,7 @@ $example::FOO = 2; # Error
</pre>
</blockquote>
<a name="n18"></a><H3>17.4.4 Pointers</H3>
<a name="n18"></a><H3>19.4.4 Pointers</H3>
SWIG represents pointers as blessed references. A blessed reference
@ -820,7 +820,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the growing differences between
SWIG and XS, this is no longer supported.
<a name="n19"></a><H3>17.4.5 Structures</H3>
<a name="n19"></a><H3>19.4.5 Structures</H3>
Access to the contents of a structure are provided through a set of low-level
@ -941,7 +941,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</blockquote>
<a name="n20"></a><H3>17.4.6 C++ classes</H3>
<a name="n20"></a><H3>19.4.6 C++ classes</H3>
C++ classes are wrapped by building a set of low level accessor functions.
@ -999,7 +999,7 @@ as the first argument. Although this interface is fairly primitive, it
provides direct access to C++ objects. A higher level interface using Perl proxy classes
can be built using these low-level accessors. This is described shortly.
<a name="n21"></a><H3>17.4.7 C++ classes and type-checking</H3>
<a name="n21"></a><H3>19.4.7 C++ classes and type-checking</H3>
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if you have
@ -1029,7 +1029,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
If necesssary, the type-checker also adjusts the value of the pointer (as is necessary when
multiple inheritance is used).
<a name="n22"></a><H3>17.4.8 C++ overloaded functions</H3>
<a name="n22"></a><H3>19.4.8 C++ overloaded functions</H3>
If you have a C++ program with overloaded functions or methods, you will need to disambiguate
@ -1067,7 +1067,7 @@ example::Spam_foo_d($s,3.14);
Please refer to the "SWIG Basics" chapter for more information.
<a name="n23"></a><H3>17.4.9 Operators</H3>
<a name="n23"></a><H3>19.4.9 Operators</H3>
C++ operators can also be wrapped using the <tt>%rename</tt> directive. All you need to do is
@ -1094,7 +1094,7 @@ $c = example::add_complex($a,$b);
Some preliminary work on mapping C++ operators into Perl operators has been completed. This is covered later.
<a name="n24"></a><H3>17.4.10 Modules and packages</H3>
<a name="n24"></a><H3>19.4.10 Modules and packages</H3>
When you create a SWIG extension, everything gets placed into
@ -1149,7 +1149,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></blockquote>
-->
<a name="n25"></a><H2>17.5 Input and output parameters</H2>
<a name="n25"></a><H2>19.5 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -1335,7 +1335,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
<a name="n26"></a><H2>17.6 Exception handling </H2>
<a name="n26"></a><H2>19.6 Exception handling </H2>
The SWIG <tt>%exception</tt> directive can be used to create a
@ -1484,7 +1484,7 @@ See the chapter on "<a href="Customization.html">Customization features</a>" for
This is still supported, but it is deprecated. The newer <tt>%exception</tt> directive provides the same
functionality, but it has additional capabilities that make it more powerful.
<a name="n27"></a><H2>17.7 Remapping datatypes with typemaps</H2>
<a name="n27"></a><H2>19.7 Remapping datatypes with typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -1498,7 +1498,7 @@ 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 primitive
C-Perl interface.
<a name="n28"></a><H3>17.7.1 A simple typemap example</H3>
<a name="n28"></a><H3>19.7.1 A simple typemap example</H3>
A typemap is nothing more than a code generation rule that is attached to
@ -1588,7 +1588,7 @@ example::count("e","Hello World");
</blockquote>
<a name="n29"></a><H3>17.7.2 Perl5 typemaps</H3>
<a name="n29"></a><H3>19.7.2 Perl5 typemaps</H3>
The previous section illustrated an "in" typemap for converting Perl objects to C.
@ -1668,7 +1668,7 @@ Return of C++ member data (all languages).<p>
Check value of input parameter.<p>
</blockquote>
<a name="n30"></a><H3>17.7.3 Typemap variables</H3>
<a name="n30"></a><H3>19.7.3 Typemap variables</H3>
Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear.
@ -1722,7 +1722,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</blockquote>
<a name="n31"></a><H3>17.7.4 Useful functions</H3>
<a name="n31"></a><H3>19.7.4 Useful functions</H3>
When writing typemaps, it is necessary to work directly with Perl5
@ -1782,14 +1782,14 @@ int sv_isa(SV *, char *0;
</blockquote>
<a name="n32"></a><H2>17.8 Typemap Examples</H2>
<a name="n32"></a><H2>19.8 Typemap Examples</H2>
This section includes a few examples of typemaps. For more examples, you
might look at the files "<tt>perl5.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<a name="n33"></a><H3>17.8.1 Converting a Perl5 array to a char ** </H3>
<a name="n33"></a><H3>19.8.1 Converting a Perl5 array to a char ** </H3>
A common problem in many C programs is the processing of command line
@ -1877,7 +1877,7 @@ print @$b,"\n"; # Print it out
</pre></blockquote>
<a name="n34"></a><H3>17.8.2 Return values </H3>
<a name="n34"></a><H3>19.8.2 Return values </H3>
Return values are placed on the argument stack of each wrapper
@ -1903,7 +1903,7 @@ can be done using the <tt>EXTEND()</tt> macro as in :<p>
}
</pre></blockquote>
<a name="n35"></a><H3>17.8.3 Returning values from arguments</H3>
<a name="n35"></a><H3>19.8.3 Returning values from arguments</H3>
Sometimes it is desirable for a function to return a value in one of
@ -1954,7 +1954,7 @@ print "multout(7,13) = @r\n";
($x,$y) = multout(7,13);
</pre></blockquote>
<a name="n36"></a><H3>17.8.4 Accessing array structure members</H3>
<a name="n36"></a><H3>19.8.4 Accessing array structure members</H3>
Consider the following data structure :<p>
@ -2006,7 +2006,7 @@ the "in" typemap in the previous section would be used to convert an
<tt>int[]</tt> array to C whereas the "memberin" typemap would be used
to copy the converted array into a C data structure.
<a name="n37"></a><H3>17.8.5 Turning Perl references into C pointers</H3>
<a name="n37"></a><H3>19.8.5 Turning Perl references into C pointers</H3>
A frequent confusion on the SWIG mailing list is errors caused by the
@ -2064,7 +2064,7 @@ print "$c\n";
</pre></blockquote>
<a name="n38"></a><H3>17.8.6 Pointer handling</H3>
<a name="n38"></a><H3>19.8.6 Pointer handling</H3>
Occasionally, it might be necessary to convert pointer values that have
@ -2136,7 +2136,7 @@ For example:
</pre>
</blockquote>
<a name="n39"></a><H2>17.9 Proxy classes</H2>
<a name="n39"></a><H2>19.9 Proxy classes</H2>
<b>Out of date. Needs update.</b>
@ -2149,7 +2149,7 @@ This is done by constructing a Perl proxy class that provides an OO wrapper
to the underlying code. This section describes the implementation
details of the proxy interface.
<a name="n40"></a><H3>17.9.1 Preliminaries</H3>
<a name="n40"></a><H3>19.9.1 Preliminaries</H3>
To generate proxy classes, you need to use the <tt>-proxy</tt> command line option.
@ -2283,7 +2283,7 @@ $v-&gt;DESTROY();
</pre></blockquote>
<a name="n41"></a><H3>17.9.2 Object Ownership</H3>
<a name="n41"></a><H3>19.9.2 Object Ownership</H3>
In order for shadow classes to work properly, it is necessary for Perl
@ -2356,7 +2356,7 @@ As always, a little care is in order. SWIG does not provide reference
counting, garbage collection, or advanced features one might find in
sophisticated languages.<p>
<a name="n42"></a><H3>17.9.3 Nested Objects</H3>
<a name="n42"></a><H3>19.9.3 Nested Objects</H3>
Suppose that we have a new object that looks like this :<p>
@ -2399,7 +2399,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></blockquote>
<p>
<a name="n43"></a><H3>17.9.4 Shadow Functions</H3>
<a name="n43"></a><H3>19.9.4 Shadow Functions</H3>
When functions take arguments involving a complex object, it is
@ -2429,7 +2429,7 @@ this :<p>
This function replaces the original function, but operates in an
identical manner.<p>
<a name="n44"></a><H3>17.9.5 Inheritance</H3>
<a name="n44"></a><H3>19.9.5 Inheritance</H3>
Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array

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

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>18 SWIG and PHP4</H1>
<a name="n1"></a><H1>20 SWIG and PHP4</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -43,7 +43,7 @@ if you thought you were familiar with what it said. The major change is
that shadow classes are implemented inside the php module in C++ instead
of in the generated .php file in php.
<a name="n2"></a><H2>18.1 Preliminaries</H2>
<a name="n2"></a><H2>20.1 Preliminaries</H2>
In order to use this module, you will need to have a copy of the PHP 4.0 (or
@ -53,7 +53,7 @@ need either the php binary or the Apache php module. If you want to build your
extension into php directly (without having the overhead of loading it into
each script), you will need the complete PHP source tree available.
<a name="n3"></a><H2>18.2 Building PHP4 Extensions</H2>
<a name="n3"></a><H2>20.2 Building PHP4 Extensions</H2>
To build a PHP4 extension, run swig using the <tt>-php4</tt> option as follows :
@ -86,7 +86,7 @@ the extension into the php executable/library so it will be available in every
script. The first choice is the default, however it can be changed by passing
the '-phpfull' command line switch to select the second build method.
<a name="n4"></a><H3>18.2.1 Building a loadable extension</H3>
<a name="n4"></a><H3>20.2.1 Building a loadable extension</H3>
To build a dynamic module for PHP, you have two options. You can use the
@ -146,10 +146,10 @@ attempts to do the <tt>dl()</tt> call for you:
A more complicated method which builds the module directly into the <tt>php</tt>
executable is described <a href="n12">below</a>.
<a name="n5"></a><H3>18.2.2 Basic PHP4 interface</H3>
<a name="n5"></a><H3>20.2.2 Basic PHP4 interface</H3>
<a name="n6"></a><H3>18.2.3 Functions</H3>
<a name="n6"></a><H3>20.2.3 Functions</H3>
C functions are converted into PHP functions. Default/optional arguments are
@ -170,7 +170,7 @@ $c = bar(3.5); # Use default argument for 2nd parameter
</pre></blockquote>
<a name="n7"></a><H3>18.2.4 Global Variables</H3>
<a name="n7"></a><H3>20.2.4 Global Variables</H3>
Global variables are difficult for PHP to handle, unlike Perl, their is no
@ -198,7 +198,7 @@ example_func(); # Syncs C variable to PHP Variable, now both 4
SWIG supports global variables of all C datatypes including pointers and complex
objects.<p>
<a name="n8"></a><H3>18.2.5 Pointers </H3>
<a name="n8"></a><H3>20.2.5 Pointers </H3>
Pointers to C/C++ objects <b>no longer</b> represented as character
@ -208,7 +208,7 @@ as PHP resources, rather like MySQL connection handles.
You can also explicitly create a NULL pointer as a string "NULL"
or by passing a null or empty value.
<a name="n9"></a><H3>18.2.6 Structures and C++ classes</H3>
<a name="n9"></a><H3>20.2.6 Structures and C++ classes</H3>
For structures and classes, SWIG produces accessor fuction for each member function and data. For example :<p>
@ -241,7 +241,7 @@ To use the class, simply use these functions. However, SWIG also has a mechanism
for creating shadow classes that hides these functions and uses an object
oriented interface instead - see <a href="n7">below</a>
<a name="n10"></a><H3>18.2.7 Constants</H3>
<a name="n10"></a><H3>20.2.7 Constants</H3>
These work in much the same way as in C/C++, constants can be defined by using
@ -337,7 +337,7 @@ both point to the same value, without the case test taking place.
</pre>
</blockquote>
<a name="n11"></a><H3>18.2.8 Shadow classes</H3>
<a name="n11"></a><H3>20.2.8 Shadow classes</H3>
To avoid having to call the various accessor function to get at structures or
@ -360,7 +360,7 @@ functions like before.
.... ( more examples on the way ) ....
<a name="n12"></a><H3>18.2.9 Constructors and Destructers</H3>
<a name="n12"></a><H3>20.2.9 Constructors and Destructers</H3>
Constructors are used in PHP as in C++, they are called when the object is
@ -384,7 +384,7 @@ object. 'RegisterShutdownFunction' is no longer needed for this.
I am not sure if PHP resources are all freed at the end of a script, or
when they each go out of scope.
<a name="n13"></a><H3>18.2.10 Static Member Variables</H3>
<a name="n13"></a><H3>20.2.10 Static Member Variables</H3>
Class variables are not supported in PHP, however class functions are, using
@ -418,7 +418,7 @@ echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
<a name="n14"></a><H3>18.2.11 PHP4 Pragmas</H3>
<a name="n14"></a><H3>20.2.11 PHP4 Pragmas</H3>
There are a few pragmas understood by the PHP4 module. The first,
@ -447,7 +447,7 @@ function is called.
%include "example.h"
</pre></blockquote>
<a name="n15"></a><H3>18.2.12 Building extensions into php</H3>
<a name="n15"></a><H3>20.2.12 Building extensions into php</H3>
This method, selected with the <tt>-phpfull</tt> command line switch, involves
@ -489,7 +489,7 @@ Once configure has completed, you can run make to build php. If this all
compiles correctly, you should end up with a php executable/library
which contains your new module. You can test it with a php script which
does not have the 'dl' command as used above.
<a name="n16"></a><H3>18.2.13 To be furthered...</H3>
<a name="n16"></a><H3>20.2.13 To be furthered...</H3>
</body>

128
SWIG/Doc/Manual/Python.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>19 SWIG and Python</H1>
<a name="n1"></a><H1>21 SWIG and Python</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Overview</a>
@ -107,7 +107,7 @@ are covered in less depth than in earlier chapters. At the
very least, make sure you read the "<a href="SWIG.html">SWIG
Basics</a>" chapter.
<a name="n2"></a><H2>19.1 Overview</H2>
<a name="n2"></a><H2>21.1 Overview</H2>
To build Python extension modules, SWIG uses a layered approach in which
@ -130,10 +130,10 @@ described. Advanced customization features such as typemaps are then
described followed by a discussion of low-level implementation
details.
<a name="n3"></a><H2>19.2 Preliminaries</H2>
<a name="n3"></a><H2>21.2 Preliminaries</H2>
<a name="n4"></a><H3>19.2.1 Running SWIG</H3>
<a name="n4"></a><H3>21.2.1 Running SWIG</H3>
Suppose that you defined a SWIG module such as the following:
@ -174,7 +174,7 @@ To change this, you can use the <tt>-o</tt> option. The name of the Python fil
from the module name specified with <tt>%module</tt>. If the module name is <tt>example</tt>, then
a file <tt>example.py</tt> is created.
<a name="n5"></a><H3>19.2.2 Getting the right header files</H3>
<a name="n5"></a><H3>21.2.2 Getting the right header files</H3>
In order to compile the C/C++ wrappers, the compiler needs the <tt>Python.h</tt> header file.
@ -201,7 +201,7 @@ Type "copyright", "credits" or "license" for more information.
</pre>
</blockquote>
<a name="n6"></a><H3>19.2.3 Compiling a dynamic module</H3>
<a name="n6"></a><H3>21.2.3 Compiling a dynamic module</H3>
The preferred approach to building an extension module is to compile it into
@ -239,10 +239,10 @@ other Python extension modules. For example, the <tt>socket</tt>
module actually consists of two files; <tt>socket.py</tt> and
<tt>_socket.so</tt>. Many other built-in Python modules follow a similar convention.
<a name="n7"></a><H3>19.2.4 Using distutils</H3>
<a name="n7"></a><H3>21.2.4 Using distutils</H3>
<a name="n8"></a><H3>19.2.5 Static linking</H3>
<a name="n8"></a><H3>21.2.5 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Python
@ -310,7 +310,7 @@ appears to "work" with Python 2.1, no future support is guaranteed.
If using static linking, you might want to rely on a different approach
(perhaps using distutils).
<a name="n9"></a><H3>19.2.6 Using your module</H3>
<a name="n9"></a><H3>21.2.6 Using your module</H3>
To use your module, simply use the Python <tt>import</tt> statement. If
@ -445,7 +445,7 @@ Finally, you can use a command such as <tt>ldconfig</tt> (Linux) or
system configuration (this requires root access and you will need to
read the man pages).
<a name="n10"></a><H3>19.2.7 Compilation of C++ extensions</H3>
<a name="n10"></a><H3>21.2.7 Compilation of C++ extensions</H3>
Compilation of C++ extensions has traditionally been a tricky problem.
@ -518,7 +518,7 @@ you will need to take steps to avoid segmentation faults and other
erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
<a name="n11"></a><H3>19.2.8 Compiling for 64-bit platforms</H3>
<a name="n11"></a><H3>21.2.8 Compiling for 64-bit platforms</H3>
On platforms that support 64-bit applications (Solaris, Irix, etc.),
@ -541,7 +541,7 @@ that software. This may prevent the use of 64-bit extensions. It may
also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
<a name="n12"></a><H3>19.2.9 Building Python Extensions under Windows</H3>
<a name="n12"></a><H3>21.2.9 Building Python Extensions under Windows</H3>
Building a SWIG extension to Python under Windows is roughly
@ -623,14 +623,14 @@ compilers tends to be rather problematic. For the latest information,
you may want to consult the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">
SWIG Wiki</a>.
<a name="n13"></a><H2>19.3 A tour of basic C/C++ wrapping</H2>
<a name="n13"></a><H2>21.3 A tour of basic C/C++ wrapping</H2>
By default, SWIG tries to build a very natural Python interface
to your C/C++ code. Functions are wrapped as functions, classes are wrapped as classes, and so forth.
This section briefly covers the essential aspects of this wrapping.
<a name="n14"></a><H3>19.3.1 Modules</H3>
<a name="n14"></a><H3>21.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Python
@ -641,7 +641,7 @@ extension module <tt>_example.so</tt>. When choosing a
module name, make sure you don't use the same name as a built-in
Python command or standard module name.
<a name="n15"></a><H3>19.3.2 Functions</H3>
<a name="n15"></a><H3>21.3.2 Functions</H3>
Global functions are wrapped as new Python built-in functions. For example,
@ -662,7 +662,7 @@ like you think it does:<p>
&gt;&gt;&gt;
</pre></blockquote>
<a name="n16"></a><H3>19.3.3 Global variables</H3>
<a name="n16"></a><H3>21.3.3 Global variables</H3>
C/C++ global variables are fully supported by SWIG. However, the underlying
@ -774,7 +774,7 @@ module loaded. To prevent this, you might consider renaming
that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.<p>
<a name="n17"></a><H3>19.3.4 Constants and enums</H3>
<a name="n17"></a><H3>21.3.4 Constants and enums</H3>
C/C++ constants are installed as Python objects containing the
@ -808,7 +808,7 @@ 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.
<a name="n18"></a><H3>19.3.5 Pointers</H3>
<a name="n18"></a><H3>21.3.5 Pointers</H3>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with
@ -940,7 +940,7 @@ to use the new C++ style casts. For example, in the above code, the
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.
<a name="n19"></a><H3>19.3.6 Structures</H3>
<a name="n19"></a><H3>21.3.6 Structures</H3>
If you wrap a C structure, it is wrapped by a Python class. This provides
@ -1103,7 +1103,7 @@ everything works just like you would expect. For example:
</pre>
</blockquote>
<a name="n20"></a><H3>19.3.7 C++ classes</H3>
<a name="n20"></a><H3>21.3.7 C++ classes</H3>
C++ classes are wrapped by Python classes as well. For example, if you have this class,
@ -1182,7 +1182,7 @@ they are accessed through <tt>cvar</tt> like this:
</pre></blockquote>
<a name="n21"></a><H3>19.3.8 C++ inheritance</H3>
<a name="n21"></a><H3>21.3.8 C++ inheritance</H3>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have
@ -1228,7 +1228,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
<p>
It is safe to use multiple inheritance with SWIG.
<a name="n22"></a><H3>19.3.9 Pointers, references, values, and arrays</H3>
<a name="n22"></a><H3>21.3.9 Pointers, references, values, and arrays</H3>
In C++, there are many different ways a function might receive
@ -1275,7 +1275,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used
to hold the result and a pointer is returned (Python will release this memory
when the return value is garbage collected).
<a name="n23"></a><H3>19.3.10 C++ overloaded functions</H3>
<a name="n23"></a><H3>21.3.10 C++ overloaded functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -1376,7 +1376,7 @@ first declaration takes precedence.
<P>
Please refer to the "SWIG and C++" chapter for more information about overloading.
<a name="n24"></a><H3>19.3.11 C++ operators</H3>
<a name="n24"></a><H3>21.3.11 C++ operators</H3>
Certain C++ overloaded operators can be handled automatically by SWIG. For example,
@ -1449,7 +1449,7 @@ Keep reading.
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.
<a name="n25"></a><H3>19.3.12 C++ namespaces</H3>
<a name="n25"></a><H3>21.3.12 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1508,7 +1508,7 @@ extension modules for each namespace separately. If your program
utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
<a name="n26"></a><H3>19.3.13 C++ templates</H3>
<a name="n26"></a><H3>21.3.13 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1555,7 +1555,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter. Some more complicated
examples will appear later.
<a name="n27"></a><H3>19.3.14 C++ Smart Pointers</H3>
<a name="n27"></a><H3>21.3.14 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1627,7 +1627,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</blockquote>
<a name="n28"></a><H2>19.4 Further details on the Python class interface</H2>
<a name="n28"></a><H2>21.4 Further details on the Python class interface</H2>
In the previous section, a high-level view of Python wrapping was
@ -1638,7 +1638,7 @@ advanced features such as operator overloading. However, a number
of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
<a name="n29"></a><H3>19.4.1 Proxy classes</H3>
<a name="n29"></a><H3>21.4.1 Proxy classes</H3>
In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters,
@ -1715,7 +1715,7 @@ The fact that the class has been wrapped by a real Python class offers certain a
you can attach new Python methods to the class and you can even inherit from it (something not supported
by Python built-in types until Python 2.2).
<a name="n30"></a><H3>19.4.2 Memory management</H3>
<a name="n30"></a><H3>21.4.2 Memory management</H3>
Associated with proxy object, is an ownership flag <tt>.thisown</tt> The value of this
@ -1877,7 +1877,7 @@ To work around this, it is always possible to flip the ownership flag. For examp
It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
<a name="n31"></a><H3>19.4.3 Python 2.2 and classic classes</H3>
<a name="n31"></a><H3>21.4.3 Python 2.2 and classic classes</H3>
SWIG makes every attempt to preserve backwards compatibility with
@ -1909,7 +1909,7 @@ of static member functions. In Python-2.2, they can be accessed via the
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).
<a name="n32"></a><H2>19.5 Cross language polymorphism (experimental)</H2>
<a name="n32"></a><H2>21.5 Cross language polymorphism (experimental)</H2>
Proxy classes provide a more natural, object-oriented way to access
@ -1937,7 +1937,7 @@ to know where a particular method is implemented: the combination of
proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
<a name="n33"></a><H3>19.5.1 Enabling directors</H3>
<a name="n33"></a><H3>21.5.1 Enabling directors</H3>
The director feature is disabled by default. To use directors you
@ -2002,7 +2002,7 @@ public:
</pre>
</blockquote>
<a name="n34"></a><H3>19.5.2 Director classes</H3>
<a name="n34"></a><H3>21.5.2 Director classes</H3>
For each class that has directors enabled, SWIG generates a new class
@ -2075,7 +2075,7 @@ unmodified proxy classes, all methods are ultimately implemented in C++
so there is no need for the extra overhead involved with routing the
calls through Python.
<a name="n35"></a><H3>19.5.3 Ownership and object destruction</H3>
<a name="n35"></a><H3>21.5.3 Ownership and object destruction</H3>
Memory management issues are slightly more complicated with directors
@ -2135,7 +2135,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard
references to the Foo objects remain in Python.
<p>
<a name="n36"></a><H3>19.5.4 Exception unrolling</H3>
<a name="n36"></a><H3>21.5.4 Exception unrolling</H3>
With directors routing method calls to Python, and proxies routing them
@ -2187,7 +2187,7 @@ exception. Because the Python error state is still set when
Swig::DirectorMethodException is thrown, Python will register the
exception as soon as the C wrapper function returns.
<a name="n37"></a><H3>19.5.5 Overhead and code bloat</H3>
<a name="n37"></a><H3>21.5.5 Overhead and code bloat</H3>
Enabling directors for a class will generate a new director method for
@ -2217,7 +2217,7 @@ optimized by selectively enabling director methods (using the %feature
directive) for only those methods that are likely to be extended in
Python.
<a name="n38"></a><H3>19.5.6 Typemaps</H3>
<a name="n38"></a><H3>21.5.6 Typemaps</H3>
Typemaps for input and output of most of the basic types from director
@ -2233,10 +2233,10 @@ for std::string, std::vector, and std::complex, although there's no
guarantee these are fully functional yet.
<p>
<a name="n39"></a><H3>19.5.7 Miscellaneous</H3>
<a name="n39"></a><H3>21.5.7 Miscellaneous</H3>
<a name="n40"></a><H2>19.6 Common customization features</H2>
<a name="n40"></a><H2>21.6 Common customization features</H2>
The last section presented the absolute basics of C/C++ wrapping. If you do nothing
@ -2246,7 +2246,7 @@ types of functionality might be missing or the interface to certain functions mi
be awkward. This section describes some common SWIG features that are used
to improve your the interface to an extension module.
<a name="n41"></a><H3>19.6.1 C/C++ helper functions</H3>
<a name="n41"></a><H3>21.6.1 C/C++ helper functions</H3>
Sometimes when you create a module, it is missing certain bits of functionality. For
@ -2317,7 +2317,7 @@ Admittedly, this is not the most elegant looking approach. However, it works an
hard to implement. It is possible to clean this up using Python code, typemaps, and other
customization features as covered in later sections.
<a name="n42"></a><H3>19.6.2 Adding additional Python code</H3>
<a name="n42"></a><H3>21.6.2 Adding additional Python code</H3>
If writing support code in C isn't enough, it is also possible to write code in
@ -2365,7 +2365,7 @@ soon enough. For now, think of this example as an illustration of
what can be done without having to rely on any of the more advanced
customization features.
<a name="n43"></a><H3>19.6.3 Class extension with %extend</H3>
<a name="n43"></a><H3>21.6.3 Class extension with %extend</H3>
One of the more interesting features of SWIG is that it can extend
@ -2444,7 +2444,7 @@ Vector(12,14,16)
<tt>%extend</tt> works with both C and C++ code. It does not modify the underlying object
in any way---the extensions only show up in the Python interface.
<a name="n44"></a><H3>19.6.4 Exception handling with %exception</H3>
<a name="n44"></a><H3>21.6.4 Exception handling with %exception</H3>
If a C or C++ function throws an error, you may want to convert that error into a Python
@ -2557,7 +2557,7 @@ PyExc_ZeroDivisionError
The language-independent <tt>exception.i</tt> library file can also be used
to raise exceptions. See the <a href="Library.html">SWIG Library</a> chapter.
<a name="n45"></a><H2>19.7 Tips and techniques</H2>
<a name="n45"></a><H2>21.7 Tips and techniques</H2>
Although SWIG is largely automatic, there are certain types of wrapping problems that
@ -2565,7 +2565,7 @@ require additional user input. Examples include dealing with output parameter
strings, binary data, and arrays. This chapter discusses the common techniques for
solving these problems.
<a name="n46"></a><H3>19.7.1 Input and output parameters</H3>
<a name="n46"></a><H3>21.7.1 Input and output parameters</H3>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -2745,7 +2745,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>.
<a name="n47"></a><H3>19.7.2 Simple pointers</H3>
<a name="n47"></a><H3>21.7.2 Simple pointers</H3>
If you must work with simple pointers such as <tt>int *</tt> or <tt>double *</tt> and you don't want to use
@ -2801,7 +2801,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t
See the <a href="Library.html">SWIG Library</a> chapter for further details.
<a name="n48"></a><H3>19.7.3 Unbounded C Arrays</H3>
<a name="n48"></a><H3>21.7.3 Unbounded C Arrays</H3>
Sometimes a C function expects an array to be passed as a pointer. For example,
@ -2855,7 +2855,7 @@ On the other hand, this low-level approach is extremely efficient and
well suited for applications in which you need to create buffers,
package binary data, etc.
<a name="n49"></a><H3>19.7.4 String handling</H3>
<a name="n49"></a><H3>21.7.4 String handling</H3>
If a C function has an argument of <tt>char *</tt>, then a Python string
@ -2909,16 +2909,16 @@ If you need to return binary data, you might use the
<tt>cstring.i</tt> library file. The <tt>cdata.i</tt> library can
also be used to extra binary data from arbitrary pointers.
<a name="n50"></a><H3>19.7.5 Arrays</H3>
<a name="n50"></a><H3>21.7.5 Arrays</H3>
<a name="n51"></a><H3>19.7.6 String arrays</H3>
<a name="n51"></a><H3>21.7.6 String arrays</H3>
<a name="n52"></a><H3>19.7.7 STL wrappers</H3>
<a name="n52"></a><H3>21.7.7 STL wrappers</H3>
<a name="n53"></a><H2>19.8 Typemaps</H2>
<a name="n53"></a><H2>21.8 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -2932,7 +2932,7 @@ 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 primitive
C-Python interface or if you want to elevate your guru status.
<a name="n54"></a><H3>19.8.1 What is a typemap?</H3>
<a name="n54"></a><H3>21.8.1 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached to
@ -3030,7 +3030,7 @@ parameter is omitted):
</pre>
</blockquote>
<a name="n55"></a><H3>19.8.2 Python typemaps</H3>
<a name="n55"></a><H3>21.8.2 Python typemaps</H3>
The previous section illustrated an "in" typemap for converting Python objects to C.
@ -3062,7 +3062,7 @@ $ cat python.swg
Additional typemap examples can also be found in the <tt>typemaps.i</tt> file.
<a name="n56"></a><H3>19.8.3 Typemap variables</H3>
<a name="n56"></a><H3>21.8.3 Typemap variables</H3>
Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear.
@ -3116,7 +3116,7 @@ properly assigned.
The Python name of the wrapper function being created.
</blockquote>
<a name="n57"></a><H3>19.8.4 Useful Python Functions</H3>
<a name="n57"></a><H3>21.8.4 Useful Python Functions</H3>
When you write a typemap, you usually have to work directly with Python objects.
@ -3213,14 +3213,14 @@ write me
</pre>
</blockquote>
<a name="n58"></a><H2>19.9 Typemap Examples</H2>
<a name="n58"></a><H2>21.9 Typemap Examples</H2>
This section includes a few examples of typemaps. For more examples, you
might look at the files "<tt>python.swg</tt>" and "<tt>typemaps.i</tt>" in
the SWIG library.
<a name="n59"></a><H3>19.9.1 Converting Python list to a char ** </H3>
<a name="n59"></a><H3>21.9.1 Converting Python list to a char ** </H3>
A common problem in many C programs is the processing of command line
@ -3293,7 +3293,7 @@ memory allocation is used to allocate memory for the array, the
"freearg" typemap is used to later release this memory after the execution of
the C function.
<a name="n60"></a><H3>19.9.2 Expanding a Python object into multiple arguments</H3>
<a name="n60"></a><H3>21.9.2 Expanding a Python object into multiple arguments</H3>
Suppose that you had a collection of C functions with arguments
@ -3363,7 +3363,7 @@ to supply the argument count. This is automatically set by the typemap code. F
</pre>
</blockquote>
<a name="n61"></a><H3>19.9.3 Using typemaps to return arguments</H3>
<a name="n61"></a><H3>21.9.3 Using typemaps to return arguments</H3>
A common problem in some C programs is that values may be returned in
@ -3441,7 +3441,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></blockquote>
<a name="n62"></a><H3>19.9.4 Mapping Python tuples into small arrays</H3>
<a name="n62"></a><H3>21.9.4 Mapping Python tuples into small arrays</H3>
In some applications, it is sometimes desirable to pass small arrays
@ -3482,7 +3482,7 @@ Since our mapping copies the contents of a Python tuple into a C
array, such an approach would not be recommended for huge arrays, but
for small structures, this approach works fine.<p>
<a name="n63"></a><H3>19.9.5 Mapping sequences to C arrays</H3>
<a name="n63"></a><H3>21.9.5 Mapping sequences to C arrays</H3>
Suppose that you wanted to generalize the previous example to handle C
@ -3561,7 +3561,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</blockquote>
<a name="n64"></a><H3>19.9.6 Pointer handling</H3>
<a name="n64"></a><H3>21.9.6 Pointer handling</H3>
Occasionally, it might be necessary to convert pointer values that have

102
SWIG/Doc/Manual/Ruby.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>20 SWIG and Ruby</H1>
<a name="n1"></a><H1>22 SWIG and Ruby</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -86,7 +86,7 @@
This chapter describes SWIG's support of Ruby.
<hr>
<a name="n2"></a><H2>20.1 Preliminaries</H2>
<a name="n2"></a><H2>22.1 Preliminaries</H2>
SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given the choice, you should
@ -100,7 +100,7 @@ href="SWIG.html">SWIG Basics</a>" chapter. It is also assumed that the reader
has a basic understanding of Ruby.
<a name="n3"></a><H3>20.1.1 Running SWIG</H3>
<a name="n3"></a><H3>22.1.1 Running SWIG</H3>
<p>
@ -120,7 +120,7 @@ compiling a C++ extension) that contains all of the code needed to build a
Ruby extension module. To finish building the module, you need to compile this
file and link it with the rest of your program.
<a name="n4"></a><H3>20.1.2 Getting the right header files</H3>
<a name="n4"></a><H3>22.1.2 Getting the right header files</H3>
In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
@ -147,7 +147,7 @@ $ <b>ruby -e 'puts $:.join("\n")'</b>
</pre>
</blockquote>
<a name="n5"></a><H3>20.1.3 Compiling a dynamic module</H3>
<a name="n5"></a><H3>22.1.3 Compiling a dynamic module</H3>
Ruby extension modules are typically compiled into shared libraries that the
@ -206,7 +206,7 @@ pages for your compiler and linker to determine the correct set of options.
You might also check the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl">
SWIG Wiki</a> for additional information.<p>
<a name="n6"></a><H3>20.1.4 Using your module</H3>
<a name="n6"></a><H3>22.1.4 Using your module</H3>
Ruby <i>module</i> names must be capitalized, but the convention for Ruby
@ -231,7 +231,7 @@ extension. So for example, a SWIG interface file that begins with:
will result in an extension module using the feature name "example" and
Ruby module name "Example".
<a name="n7"></a><H3>20.1.5 Static linking</H3>
<a name="n7"></a><H3>22.1.5 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Ruby
@ -247,7 +247,7 @@ the Ruby source, adding an entry to the <tt>ext/Setup</tt> file,
adding your directory to the list of extensions in the file, and finally rebuilding Ruby.
<p>
<a name="n8"></a><H3>20.1.6 Compilation of C++ extensions</H3>
<a name="n8"></a><H3>22.1.6 Compilation of C++ extensions</H3>
<p>
@ -279,7 +279,7 @@ create_makefile('example')
</blockquote>
<hr>
<a name="n9"></a><H2>20.2 Building Ruby Extensions under Windows 95/NT</H2>
<a name="n9"></a><H2>22.2 Building Ruby Extensions under Windows 95/NT</H2>
Building a SWIG extension to Ruby under Windows 95/NT is roughly similar to the
@ -300,7 +300,7 @@ IDE, instead of using the command line tools). In order to build extensions,
you may need to download the source distribution to the Ruby package, as you
will need the Ruby header files.<p>
<a name="n10"></a><H3>20.2.1 Running SWIG from Developer Studio</H3>
<a name="n10"></a><H3>22.2.1 Running SWIG from Developer Studio</H3>
If you are developing your application within Microsoft developer studio, SWIG
@ -364,13 +364,13 @@ Foo = 3.0
<hr>
<a name="n11"></a><H2>20.3 The Ruby-to-C/C++ Mapping</H2>
<a name="n11"></a><H2>22.3 The Ruby-to-C/C++ Mapping</H2>
This section describes the basics of how SWIG maps C or C++ declarations
in your SWIG interface files to Ruby constructs.
<a name="n12"></a><H3>20.3.1 Modules</H3>
<a name="n12"></a><H3>22.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Ruby module. If
@ -396,7 +396,7 @@ using the <tt>-globalmodule</tt> option to wrap everything into the global modul
take care that the names of your constants, classes and methods don't conflict
with any of Ruby's built-in names.
<a name="n13"></a><H3>20.3.2 Functions</H3>
<a name="n13"></a><H3>22.3.2 Functions</H3>
Global functions are wrapped as Ruby module methods. For example, given
@ -429,7 +429,7 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
24
</pre></blockquote>
<a name="n14"></a><H3>20.3.3 Variable Linking</H3>
<a name="n14"></a><H3>22.3.3 Variable Linking</H3>
C/C++ global variables are wrapped as a pair of singleton methods for the
@ -490,7 +490,7 @@ extern char *path;
The <tt>%immutable</tt> directive stays in effect until it is explicitly
disabled using <tt>%mutable</tt>.
<a name="n15"></a><H3>20.3.4 Constants</H3>
<a name="n15"></a><H3>22.3.4 Constants</H3>
C/C++ constants are wrapped as module constants initialized to the
@ -519,7 +519,7 @@ irb(main):002:0&gt; <b>Example::PI</b>
3.14159
</pre></blockquote>
<a name="n16"></a><H3>20.3.5 Pointers</H3>
<a name="n16"></a><H3>22.3.5 Pointers</H3>
"Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't explicitly
@ -540,7 +540,7 @@ irb(main):001:0&gt; <b>foo = Example::get_foo()</b>
A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt> object.
<a name="n17"></a><H3>20.3.6 Structures</H3>
<a name="n17"></a><H3>22.3.6 Structures</H3>
C/C++ structs are wrapped as Ruby classes, with accessor methods (i.e. "getters"
@ -655,7 +655,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</pre>
</blockquote>
<a name="n18"></a><H3>20.3.7 C++ classes</H3>
<a name="n18"></a><H3>22.3.7 C++ classes</H3>
Like structs, C++ classes are wrapped by creating a new Ruby class of the same
@ -707,7 +707,7 @@ Ale
3
</pre></blockquote>
<a name="n19"></a><H3>20.3.8 C++ Inheritance</H3>
<a name="n19"></a><H3>22.3.8 C++ Inheritance</H3>
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if you have
@ -856,7 +856,7 @@ In most cases, this is not a serious problem since objects of type <tt>Derived</
will otherwise behave as though they inherit from both <tt>Base1</tt> and <tt>Base2</tt>
(i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck Typing"</a>).
<a name="n20"></a><H3>20.3.9 C++ Overloaded Functions</H3>
<a name="n20"></a><H3>22.3.9 C++ Overloaded Functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -957,7 +957,7 @@ first declaration takes precedence.
<P>
Please refer to the <a href="SWIGPlus.html">"SWIG and C++"</a> chapter for more information about overloading.
<a name="n21"></a><H3>20.3.10 C++ Operators</H3>
<a name="n21"></a><H3>22.3.10 C++ Operators</H3>
For the most part, overloaded operators are handled automatically by SWIG
@ -1002,7 +1002,7 @@ c = Example.add_complex(a, b)
More details about wrapping C++ operators into Ruby operators is discussed in
the <a href="#n39">section on operator overloading</a>.
<a name="n22"></a><H3>20.3.11 C++ namespaces</H3>
<a name="n22"></a><H3>22.3.11 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1063,7 +1063,7 @@ extension modules for each namespace separately. If your program
utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
<a name="n23"></a><H3>20.3.12 C++ templates</H3>
<a name="n23"></a><H3>22.3.12 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1140,7 +1140,7 @@ float sum(const std::vector&lt;float&gt;& values);
Obviously, there is a lot more to template wrapping than shown in these examples.
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter.
<a name="n24"></a><H3>20.3.13 C++ Smart Pointers</H3>
<a name="n24"></a><H3>22.3.13 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1215,7 +1215,7 @@ irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *
</blockquote>
<a name="n25"></a><H3>20.3.14 Cross-Language Polymorphism</H3>
<a name="n25"></a><H3>22.3.14 Cross-Language Polymorphism</H3>
SWIG's Ruby module supports cross-language polymorphism (a.k.a. the "directors"
@ -1224,7 +1224,7 @@ information presented in the <a href="Python.html">Python</a> chapter, this
secton just notes the differences that you need to be aware of when using this
feature with Ruby.
<a name="n26"></a><H4>20.3.14.1 Exception Unrolling</H4>
<a name="n26"></a><H4>22.3.14.1 Exception Unrolling</H4>
Whenever a C++ director class routes one of its virtual member function calls to a
@ -1245,7 +1245,7 @@ using the <tt>rb_rescue2()</tt> function from Ruby's C API. If any Ruby exceptio
is raised, it will be caught here and a C++ exception is raised in its place.
<hr>
<a name="n27"></a><H2>20.4 Input and output parameters</H2>
<a name="n27"></a><H2>22.4 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as simple
@ -1403,7 +1403,7 @@ r, c = Example.get_dimensions(m)
</blockquote>
<hr>
<a name="n28"></a><H2>20.5 Simple exception handling </H2>
<a name="n28"></a><H2>22.5 Simple exception handling </H2>
The SWIG <tt>%exception</tt> directive can be used to define a user-definable
@ -1521,7 +1521,7 @@ shown above) or one of the built-in Ruby exception types. For a list of the stan
Ruby exception classes, consult a Ruby reference such as <a href="http://www.rubycentral.com/book"><em>Programming Ruby</em></a>.
<hr>
<a name="n29"></a><H2>20.6 Typemaps</H2>
<a name="n29"></a><H2>22.6 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -1535,7 +1535,7 @@ 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 primitive
C-Ruby interface.
<a name="n30"></a><H3>20.6.1 What is a typemap?</H3>
<a name="n30"></a><H3>22.6.1 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached to
@ -1643,7 +1643,7 @@ puts Example.count('o','Hello World')
</pre>
</blockquote>
<a name="n31"></a><H3>20.6.2 Ruby typemaps</H3>
<a name="n31"></a><H3>22.6.2 Ruby typemaps</H3>
The previous section illustrated an "in" typemap for converting Ruby objects to
@ -1725,7 +1725,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these typemaps appears in the <a href="#n34">section on typemap
examples</a>
<a name="n32"></a><H3>20.6.3 Typemap variables</H3>
<a name="n32"></a><H3>22.6.3 Typemap variables</H3>
Within a typemap, a number of special variables prefaced with a <tt>$</tt>
@ -1781,7 +1781,7 @@ so that their values can be properly assigned.
The Ruby name of the wrapper function being created.
</blockquote>
<a name="n33"></a><H3>20.6.4 Useful Functions</H3>
<a name="n33"></a><H3>22.6.4 Useful Functions</H3>
When you write a typemap, you usually have to work directly with Ruby objects.
@ -1790,7 +1790,7 @@ more can be found in <a href="http://www.rubycentral.com/book"><em>Programming R
and Andrew Hunt.)
<p>
<a name="n34"></a><H4>20.6.4.1 C Datatypes to Ruby Objects</H4>
<a name="n34"></a><H4>22.6.4.1 C Datatypes to Ruby Objects</H4>
<blockquote>
@ -1803,7 +1803,7 @@ rb_float_new(double) - double to Float
</pre>
</blockquote>
<a name="n35"></a><H4>20.6.4.2 Ruby Objects to C Datatypes</H4>
<a name="n35"></a><H4>22.6.4.2 Ruby Objects to C Datatypes</H4>
<blockquote>
@ -1823,7 +1823,7 @@ unsigned long FIX2ULONG(Numeric)
</pre>
</blockquote>
<a name="n36"></a><H4>20.6.4.3 Macros for VALUE</H4>
<a name="n36"></a><H4>22.6.4.3 Macros for VALUE</H4>
<p>
@ -1842,7 +1842,7 @@ unsigned long FIX2ULONG(Numeric)
<tt>RARRAY(arr)-&gt;ptr</tt>
<blockquote>pointer to array storage</blockquote>
<a name="n37"></a><H4>20.6.4.4 Exceptions</H4>
<a name="n37"></a><H4>22.6.4.4 Exceptions</H4>
<p>
@ -1917,7 +1917,7 @@ unsigned long FIX2ULONG(Numeric)
</pre>
</blockquote>
<a name="n38"></a><H4>20.6.4.5 Iterators</H4>
<a name="n38"></a><H4>22.6.4.5 Iterators</H4>
<p>
@ -1964,13 +1964,13 @@ unsigned long FIX2ULONG(Numeric)
<a name="n39"></a><H3>20.6.5 Typemap Examples</H3>
<a name="n39"></a><H3>22.6.5 Typemap Examples</H3>
This section includes a few examples of typemaps. For more examples, you
might look at the examples in the <tt>Example/ruby</tt> directory.
<a name="n40"></a><H3>20.6.6 Converting a Ruby array to a char **</H3>
<a name="n40"></a><H3>22.6.6 Converting a Ruby array to a char **</H3>
A common problem in many C programs is the processing of command line
@ -2034,7 +2034,7 @@ receive an input argument and convert it to a C array. Since dynamic memory
allocation is used to allocate memory for the array, the "freearg" typemap is
used to later release this memory after the execution of the C function.
<a name="n41"></a><H3>20.6.7 Collecting arguments in a hash</H3>
<a name="n41"></a><H3>22.6.7 Collecting arguments in a hash</H3>
Ruby's solution to the "keyword arguments" capability of some other languages is
@ -2242,7 +2242,7 @@ All of the code for this example, as well as a sample Ruby program that uses
the extension, can be found in the <tt>Examples/ruby/hashargs</tt> directory
of the SWIG distribution.
<a name="n42"></a><H3>20.6.8 Pointer handling</H3>
<a name="n42"></a><H3>22.6.8 Pointer handling</H3>
Occasionally, it might be necessary to convert pointer values that have been
@ -2301,7 +2301,7 @@ typemap variable <tt>$1_descriptor</tt>. For example:
</pre>
</blockquote>
<a name="n43"></a><H4>20.6.8.1 Ruby Datatype Wrapping</H4>
<a name="n43"></a><H4>22.6.8.1 Ruby Datatype Wrapping</H4>
<p>
@ -2322,7 +2322,7 @@ Retrieves the original C pointer of type <i>c-type</i> from the data object
</blockquote>
<hr>
<a name="n44"></a><H2>20.7 Operator overloading</H2>
<a name="n44"></a><H2>22.7 Operator overloading</H2>
SWIG allows operator overloading with, by using the <tt>%extend</tt> or
@ -2380,7 +2380,7 @@ __ge__ - &gt;=
Note that although SWIG supports the <tt>__eq__</tt> magic method name for defining an equivalence operator, there is no separate method for handling <i>inequality</i> since Ruby parses the expression <i>a != b</i> as <i>!(a == b)</i>.
<a name="n45"></a><H3>20.7.1 Example: STL Vector to Ruby Array</H3>
<a name="n45"></a><H3>22.7.1 Example: STL Vector to Ruby Array</H3>
<em><b>FIXME: This example is out of place here!</b></em><p>
@ -2469,10 +2469,10 @@ It is also possible to create a Ruby array from a vector of static data types:
</pre></blockquote>
<a name="n46"></a><H2>20.8 Advanced Topics</H2>
<a name="n46"></a><H2>22.8 Advanced Topics</H2>
<a name="n47"></a><H3>20.8.1 Creating Multi-Module Packages</H3>
<a name="n47"></a><H3>22.8.1 Creating Multi-Module Packages</H3>
The chapter on <a href="Advanced.html">Advanced Topics</a> discusses the basics
@ -2597,7 +2597,7 @@ irb(main):005:0> <b>c.getX()</b>
</pre>
</blockquote>
<a name="n48"></a><H3>20.8.2 Defining Aliases</H3>
<a name="n48"></a><H3>22.8.2 Defining Aliases</H3>
It's a fairly common practice in the Ruby built-ins and standard library to
@ -2665,7 +2665,7 @@ mechanism and so the same name matching rules used for other kinds of features
apply (see the chapter on <a href="Customization.html">"Customization Features"</a>)
for more details).
<a name="n49"></a><H3>20.8.3 Predicate Methods</H3>
<a name="n49"></a><H3>22.8.3 Predicate Methods</H3>
Predicate methods in Ruby are those which return either <tt>true</tt> or
@ -2716,7 +2716,7 @@ Note that the <tt>%predicate</tt> directive is implemented using SWIG's
of features apply (see the chapter on <a href="Customization.html">"Customization
Features"</a>) for more details).
<a name="n50"></a><H3>20.8.4 Specifying Mixin Modules</H3>
<a name="n50"></a><H3>22.8.4 Specifying Mixin Modules</H3>
The Ruby language doesn't support multiple inheritance, but it does allow you
@ -2788,7 +2788,7 @@ Note that the <tt>%mixin</tt> directive is implemented using SWIG's
of features apply (see the chapter on <a href="Customization.html">"Customization
Features"</a>) for more details).
<a name="n51"></a><H3>20.8.5 Interacting with Ruby's Garbage Collector</H3>
<a name="n51"></a><H3>22.8.5 Interacting with Ruby's Garbage Collector</H3>
<b>This section is still unfinished!</b><p>

2
SWIG/Doc/Manual/SWIG.html
View file

@ -2655,4 +2655,4 @@ The bottom line: don't do this.
<address>SWIG 1.3 - Last Modified : August 7, 2003</address>
</body>
</html>
</html>

90
SWIG/Doc/Manual/Tcl.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>21 SWIG and Tcl</H1>
<a name="n1"></a><H1>23 SWIG and Tcl</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -76,7 +76,7 @@ This chapter discusses SWIG's support of Tcl. SWIG currently requires
Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
<a name="n2"></a><H2>21.1 Preliminaries</H2>
<a name="n2"></a><H2>23.1 Preliminaries</H2>
To build a Tcl module, run SWIG using the <tt>-tcl</tt> option :<p>
@ -97,7 +97,7 @@ This creates a file <tt>example_wrap.c</tt> or
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.
<a name="n3"></a><H3>21.1.1 Getting the right header files</H3>
<a name="n3"></a><H3>23.1.1 Getting the right header files</H3>
In order to compile the wrapper code, the compiler needs the <tt>tcl.h</tt> header file.
@ -111,7 +111,7 @@ Be aware that some Tcl versions install this header file with a version number a
this is the case, you should probably make a symbolic link so that <tt>tcl.h</tt> points to the correct
header file.
<a name="n4"></a><H3>21.1.2 Compiling a dynamic module</H3>
<a name="n4"></a><H3>23.1.2 Compiling a dynamic module</H3>
The preferred approach to building an extension module is to compile it into
@ -140,7 +140,7 @@ name of the corresponding object file should be
The name of the module is specified using the <tt>%module</tt> directive or the
<tt> -module</tt> command line option.<p>
<a name="n5"></a><H3>21.1.3 Static linking</H3>
<a name="n5"></a><H3>23.1.3 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Tcl
@ -196,7 +196,7 @@ However, the performance gained by static linking tends to be rather
minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
<a name="n6"></a><H3>21.1.4 Using your module</H3>
<a name="n6"></a><H3>23.1.4 Using your module</H3>
To use your module, simply use the Tcl <tt>load</tt> command. If
@ -305,7 +305,7 @@ Finally, you can use a command such as <tt>ldconfig</tt> to add additional searc
to the default system configuration (this requires root access and you will need to read
the man pages).
<a name="n7"></a><H3>21.1.5 Compilation of C++ extensions</H3>
<a name="n7"></a><H3>23.1.5 Compilation of C++ extensions</H3>
Compilation of C++ extensions has traditionally been a tricky problem.
@ -378,7 +378,7 @@ you will need to take steps to avoid segmentation faults and other
erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
<a name="n8"></a><H3>21.1.6 Compiling for 64-bit platforms</H3>
<a name="n8"></a><H3>23.1.6 Compiling for 64-bit platforms</H3>
On platforms that support 64-bit applications (Solaris, Irix, etc.),
@ -401,7 +401,7 @@ that software. This may prevent the use of 64-bit extensions. It may
also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
<a name="n9"></a><H3>21.1.7 Setting a package prefix</H3>
<a name="n9"></a><H3>23.1.7 Setting a package prefix</H3>
To avoid namespace problems, you can instruct SWIG to append a package
@ -415,7 +415,7 @@ If you have a function "<tt>bar</tt>" in the SWIG file, the prefix
option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>". <p>
<a name="n10"></a><H3>21.1.8 Using namespaces</H3>
<a name="n10"></a><H3>23.1.8 Using namespaces</H3>
Alternatively, you can have SWIG install your module into a Tcl
@ -430,7 +430,7 @@ name, but you can override it using the <tt>-prefix</tt> option.<p>
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>.
<a name="n11"></a><H2>21.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<a name="n11"></a><H2>23.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
Building a SWIG extension to Tcl/Tk under Windows 95/NT is roughly
@ -439,7 +439,7 @@ produce a DLL that can be loaded into tclsh or wish. This section
covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.<p>
<a name="n12"></a><H3>21.2.1 Running SWIG from Developer Studio</H3>
<a name="n12"></a><H3>23.2.1 Running SWIG from Developer Studio</H3>
If you are developing your application within Microsoft developer
@ -496,7 +496,7 @@ MSDOS &gt; tclsh80
%
</pre></blockquote>
<a name="n13"></a><H3>21.2.2 Using NMAKE</H3>
<a name="n13"></a><H3>23.2.2 Using NMAKE</H3>
Alternatively, SWIG extensions can be built by writing a Makefile for
@ -553,7 +553,7 @@ first). This is a pretty minimal Makefile, but hopefully its enough
to get you started. With a little practice, you'll be making lots of
Tcl extensions.<p>
<a name="n14"></a><H2>21.3 A tour of basic C/C++ wrapping</H2>
<a name="n14"></a><H2>23.3 A tour of basic C/C++ wrapping</H2>
By default, SWIG tries to build a very natural Tcl interface to your
@ -562,7 +562,7 @@ in an interface that mimics the style of Tk widgets and [incr Tcl]
classes. This section briefly covers the essential aspects of this
wrapping.
<a name="n15"></a><H3>21.3.1 Modules</H3>
<a name="n15"></a><H3>23.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Tcl
@ -591,7 +591,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</blockquote>
<a name="n16"></a><H3>21.3.2 Functions</H3>
<a name="n16"></a><H3>23.3.2 Functions</H3>
Global functions are wrapped as new Tcl built-in commands. For example,
@ -614,7 +614,7 @@ like you think it does:<p>
%
</pre></blockquote>
<a name="n17"></a><H3>21.3.3 Global variables</H3>
<a name="n17"></a><H3>23.3.3 Global variables</H3>
C/C++ global variables are wrapped by Tcl global variables. For example:
@ -675,7 +675,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</blockquote>
<a name="n18"></a><H3>21.3.4 Constants and enums</H3>
<a name="n18"></a><H3>23.3.4 Constants and enums</H3>
C/C++ constants are installed as global Tcl variables containing the
@ -746,7 +746,7 @@ proc blah {} {
When an identifier name is given, it is used to perform an implicit hash-table lookup of the value during argument
conversion. This allows the <tt>global</tt> statement to be ommitted.
<a name="n19"></a><H3>21.3.5 Pointers</H3>
<a name="n19"></a><H3>23.3.5 Pointers</H3>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with
@ -831,7 +831,7 @@ to use the new C++ style casts. For example, in the above code, the
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.
<a name="n20"></a><H3>21.3.6 Structures</H3>
<a name="n20"></a><H3>23.3.6 Structures</H3>
If you wrap a C structure, it is wrapped by a Tcl interface that somewhat resembles a Tk widget.
@ -1071,7 +1071,7 @@ or
Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
<a name="n21"></a><H3>21.3.7 C++ classes</H3>
<a name="n21"></a><H3>23.3.7 C++ classes</H3>
C++ classes are wrapped as an extension of structure wrapping. For example, if you have this class,
@ -1129,7 +1129,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</blockquote>
<a name="n22"></a><H3>21.3.8 C++ inheritance</H3>
<a name="n22"></a><H3>23.3.8 C++ inheritance</H3>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have
@ -1171,7 +1171,7 @@ For instance:
<p>
It is safe to use multiple inheritance with SWIG.
<a name="n23"></a><H3>21.3.9 Pointers, references, values, and arrays</H3>
<a name="n23"></a><H3>23.3.9 Pointers, references, values, and arrays</H3>
In C++, there are many different ways a function might receive
@ -1217,7 +1217,7 @@ Since the third function (spam7) returns a value, newly allocated memory is used
to hold the result and a pointer is returned (Tcl will release this memory
when the return value is garbage collected).
<a name="n24"></a><H3>21.3.10 C++ overloaded functions</H3>
<a name="n24"></a><H3>23.3.10 C++ overloaded functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -1318,7 +1318,7 @@ first declaration takes precedence.
<P>
Please refer to the "SWIG and C++" chapter for more information about overloading.
<a name="n25"></a><H3>21.3.11 C++ operators</H3>
<a name="n25"></a><H3>23.3.11 C++ operators</H3>
Certain C++ overloaded operators can be handled automatically by SWIG. For example,
@ -1408,7 +1408,7 @@ Complex operator+(double, const Complex &c);
There are ways to make this operator appear as part of the class using the <tt>%extend</tt> directive.
Keep reading.
<a name="n26"></a><H3>21.3.12 C++ namespaces</H3>
<a name="n26"></a><H3>23.3.12 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1464,7 +1464,7 @@ extension modules for each namespace separately. If your program
utilizes thousands of small deeply nested namespaces each with
identical symbol names, well, then you get what you deserve.
<a name="n27"></a><H3>21.3.13 C++ templates</H3>
<a name="n27"></a><H3>23.3.13 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1510,7 +1510,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a> chapter. Some more complicated
examples will appear later.
<a name="n28"></a><H3>21.3.14 C++ Smart Pointers</H3>
<a name="n28"></a><H3>23.3.14 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1582,7 +1582,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</blockquote>
<a name="n29"></a><H2>21.4 Further details on the Tcl class interface</H2>
<a name="n29"></a><H2>23.4 Further details on the Tcl class interface</H2>
In the previous section, a high-level view of Tcl wrapping was
@ -1593,7 +1593,7 @@ advanced features such as operator overloading. However, a number
of low-level details were omitted. This section provides a brief overview
of how the proxy classes work.
<a name="n30"></a><H3>21.4.1 Proxy classes</H3>
<a name="n30"></a><H3>23.4.1 Proxy classes</H3>
In the <a href="SWIG.html">"SWIG basics"</a> and <a href="SWIGPlus.html">"SWIG and C++"</a> chapters,
@ -1650,7 +1650,7 @@ However, in addition to this, the classname <tt>Foo</tt> is used as an object co
function. This allows objects to be encapsulated objects that look a lot like Tk widgets
as shown in the last section.
<a name="n31"></a><H3>21.4.2 Memory management</H3>
<a name="n31"></a><H3>23.4.2 Memory management</H3>
Associated with each wrapped object, is an ownership flag <tt>thisown</tt> The value of this
@ -1814,7 +1814,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
<a name="n32"></a><H2>21.5 Input and output parameters</H2>
<a name="n32"></a><H2>23.5 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -1975,7 +1975,7 @@ set c [lindex $dim 1]
</pre>
</blockquote>
<a name="n33"></a><H2>21.6 Exception handling </H2>
<a name="n33"></a><H2>23.6 Exception handling </H2>
The <tt>%exception</tt> directive can be used to create a user-definable
@ -2101,7 +2101,7 @@ For example:
Since SWIG's exception handling is user-definable, you are not limited to C++ exception handling.
See the chapter on "<a href="Customization.html">Customization Features</a>" for more examples.
<a name="n34"></a><H2>21.7 Typemaps</H2>
<a name="n34"></a><H2>23.7 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -2115,7 +2115,7 @@ 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 primitive
C-Tcl interface.
<a name="n35"></a><H3>21.7.1 What is a typemap?</H3>
<a name="n35"></a><H3>23.7.1 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached to
@ -2212,7 +2212,7 @@ parameter is ommitted):
</pre>
</blockquote>
<a name="n36"></a><H3>21.7.2 Tcl typemaps</H3>
<a name="n36"></a><H3>23.7.2 Tcl typemaps</H3>
The previous section illustrated an "in" typemap for converting Tcl objects to C.
@ -2302,7 +2302,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
<a name="n37"></a><H3>21.7.3 Typemap variables</H3>
<a name="n37"></a><H3>23.7.3 Typemap variables</H3>
Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear.
@ -2356,7 +2356,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</blockquote>
<a name="n38"></a><H3>21.7.4 Converting a Tcl list to a char ** </H3>
<a name="n38"></a><H3>23.7.4 Converting a Tcl list to a char ** </H3>
A common problem in many C programs is the processing of command line
@ -2413,7 +2413,7 @@ argv[2] = Larry
3
</pre></blockquote>
<a name="n39"></a><H3>21.7.5 Returning values in arguments</H3>
<a name="n39"></a><H3>23.7.5 Returning values in arguments</H3>
The "argout" typemap can be used to return a value originating from a
@ -2451,7 +2451,7 @@ result, a Tcl function using these typemaps will work like this :<p>
%
</pre></blockquote>
<a name="n40"></a><H3>21.7.6 Useful functions</H3>
<a name="n40"></a><H3>23.7.6 Useful functions</H3>
The following tables provide some functions that may be useful in
@ -2514,7 +2514,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</blockquote>
<a name="n41"></a><H3>21.7.7 Standard typemaps</H3>
<a name="n41"></a><H3>23.7.7 Standard typemaps</H3>
The following typemaps show how to convert a few common kinds of
@ -2587,7 +2587,7 @@ work)<p>
</pre>
</blockquote>
<a name="n42"></a><H3>21.7.8 Pointer handling</H3>
<a name="n42"></a><H3>23.7.8 Pointer handling</H3>
SWIG pointers are mapped into Tcl strings containing the
@ -2656,7 +2656,7 @@ For example:
</pre>
</blockquote>
<a name="n43"></a><H2>21.8 Turning a SWIG module into a Tcl Package.</H2>
<a name="n43"></a><H2>23.8 Turning a SWIG module into a Tcl Package.</H2>
Tcl 7.4 introduced the idea of an extension package. By default, SWIG
@ -2717,7 +2717,7 @@ As a final note, most SWIG examples do not yet use the
<tt>package</tt> commands. For simple extensions it may be easier just
to use the <tt>load</tt> command instead.<p>
<a name="n44"></a><H2>21.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<a name="n44"></a><H2>23.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
One of the most interesting aspects of Tcl and SWIG is that you can
@ -2809,7 +2809,7 @@ the Tcl code would simply return with an error so there is very little
danger of blowing something up (although it is easily accomplished
with an out of bounds array access).<p>
<a name="n45"></a><H3>21.9.1 Shadow classes</H3>
<a name="n45"></a><H3>23.9.1 Shadow classes</H3>
A similar approach can be applied to shadow classes. The following

20
SWIG/Doc/Manual/Varargs.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>10 Variable Length Arguments</H1>
<a name="n1"></a><H1>11 Variable Length Arguments</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Introduction</a>
@ -36,7 +36,7 @@ fact, support for varargs is an often requested feature that was first
added in SWIG-1.3.12. Most other wrapper generation tools have
wisely chosen to avoid this issue.
<a name="n2"></a><H2>10.1 Introduction</H2>
<a name="n2"></a><H2>11.1 Introduction</H2>
Some C and C++ programs may include functions that accept a variable
@ -122,7 +122,7 @@ List make_list(const char *s, ...) {
</pre>
</blockquote>
<a name="n3"></a><H2>10.2 The Problem</H2>
<a name="n3"></a><H2>11.2 The Problem</H2>
Generating wrappers for a variable length argument function presents a
@ -203,7 +203,7 @@ varargs support without having to resort to assembly language. However, SWIG
can also support real varargs wrapping (with stack-frame manipulation) if you
are willing to get hands dirty. Keep reading.
<a name="n4"></a><H2>10.3 Default varargs support</H2>
<a name="n4"></a><H2>11.3 Default varargs support</H2>
When variable length arguments appear in an interface, the default
@ -246,7 +246,7 @@ instance, you could make function calls like this (in Python):
Notice how string formatting is being done in Python instead of C.
<a name="n5"></a><H2>10.4 Argument replacement using %varargs</H2>
<a name="n5"></a><H2>11.4 Argument replacement using %varargs</H2>
Instead of dropping the variable length arguments, an alternative approach is to replace
@ -298,7 +298,7 @@ Argument replacement is not as useful when working with functions that accept
mixed argument types such as <tt>printf()</tt>. Providing general purpose
wrappers to such functions presents special problems (covered shortly).
<a name="n6"></a><H2>10.5 Varargs and typemaps</H2>
<a name="n6"></a><H2>11.5 Varargs and typemaps</H2>
Variable length arguments may be used in typemap specifications. For example:
@ -435,7 +435,7 @@ you know for certain that they've had several cups of coffee. If you
really want to elevate your guru status and increase your job
security, continue to the next section.
<a name="n7"></a><H2>10.6 Varargs wrapping with libffi</H2>
<a name="n7"></a><H2>11.6 Varargs wrapping with libffi</H2>
All of the previous examples have relied on features of SWIG that are
@ -674,7 +674,7 @@ module, we used the special <tt>varargs</tt> variable to get these arguments. M
provide an argument number for the first extra argument. This can be used to index into an array of passed arguments to get
values. Please consult the chapter on each language module for more details.
<a name="n8"></a><H2>10.7 Wrapping of va_list</H2>
<a name="n8"></a><H2>11.7 Wrapping of va_list</H2>
Closely related to variable length argument wrapping, you may encounter functions that accept a parameter
@ -694,7 +694,7 @@ of a <tt>va_list</tt> structure are closely tied to the underlying
call-stack. It's not clear that exporting a <tt>va_list</tt> would
have any use or that it would work at all.
<a name="n9"></a><H2>10.8 C++ Issues</H2>
<a name="n9"></a><H2>11.8 C++ Issues</H2>
Wrapping of C++ member functions that accept a variable number of
@ -755,7 +755,7 @@ Given the potential to shoot yourself in the foot, it is probably easier to reco
design or to provide an alternative interface using a helper function than it is to create a
fully general wrapper to a varargs C++ member function.
<a name="n10"></a><H2>10.9 Discussion</H2>
<a name="n10"></a><H2>11.9 Discussion</H2>
This chapter has provided a number of techniques that can be used to address the problem of variable length

32
SWIG/Doc/Manual/Warnings.html
View file

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>11 Warning Messages</H1>
<a name="n1"></a><H1>12 Warning Messages</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Introduction</a>
@ -29,7 +29,7 @@
<a name="n2"></a><H2>11.1 Introduction</H2>
<a name="n2"></a><H2>12.1 Introduction</H2>
During compilation, SWIG may generate a variety of warning messages. For example:
@ -45,7 +45,7 @@ Typically, warning messages indicate non-fatal problems with the input
where the generated wrapper code will probably compile, but it may not
work like you expect.
<a name="n3"></a><H2>11.2 Warning message suppression</H2>
<a name="n3"></a><H2>12.2 Warning message suppression</H2>
All warning messages have a numeric code that is shown in the warning message itself.
@ -123,7 +123,7 @@ There is no option to suppress all SWIG warning messages. The warning messages
for a reason---to tell you that something may be <em>broken</em> in
your interface. Ignore the warning messages at your own peril.
<a name="n4"></a><H2>11.3 Enabling additional warnings</H2>
<a name="n4"></a><H2>12.3 Enabling additional warnings</H2>
Some warning messages are disabled by default and are generated only
@ -167,7 +167,7 @@ or
Note: selective enabling of warnings with <tt>%warnfilter</tt> overrides any global settings you might have
made using <tt>-w</tt> or <tt>#pragma</tt>.
<a name="n5"></a><H2>11.4 Issuing a warning message</H2>
<a name="n5"></a><H2>12.4 Issuing a warning message</H2>
Warning messages can be issued from an interface file using a number of directives. The
@ -205,7 +205,7 @@ Warning messages can be associated with typemaps using the
In this case, the warning message will be printed whenever the typemap is actually used.
<a name="n6"></a><H2>11.5 Commentary</H2>
<a name="n6"></a><H2>12.5 Commentary</H2>
The ability to suppress warning messages is really only provided for
@ -221,10 +221,10 @@ no obvious recovery. There is no mechanism for suppressing error
messages or handling errors as warnings---you must make changes to
the input file to fix the problem.
<a name="n7"></a><H2>11.6 Warning number reference</H2>
<a name="n7"></a><H2>12.6 Warning number reference</H2>
<a name="n8"></a><H3>11.6.1 Deprecated features (100-199)</H3>
<a name="n8"></a><H3>12.6.1 Deprecated features (100-199)</H3>
<ul>
@ -250,7 +250,7 @@ the input file to fix the problem.
<li>120. Deprecated command line option (-c).
</ul>
<a name="n9"></a><H3>11.6.2 Preprocessor (200-299)</H3>
<a name="n9"></a><H3>12.6.2 Preprocessor (200-299)</H3>
<ul>
@ -258,7 +258,7 @@ the input file to fix the problem.
<li>202. Could not evaluate 'expr'.
</ul>
<a name="n10"></a><H3>11.6.3 C/C++ Parser (300-399)</H3>
<a name="n10"></a><H3>12.6.3 C/C++ Parser (300-399)</H3>
<ul>
@ -330,7 +330,7 @@ the input file to fix the problem.
<li>395. operator delete[] ignored.
</ul>
<a name="n11"></a><H3>11.6.4 Types and typemaps (400-499) </H3>
<a name="n11"></a><H3>12.6.4 Types and typemaps (400-499) </H3>
<ul>
@ -352,7 +352,7 @@ the input file to fix the problem.
<li>468. No 'throw' typemap defined for exception type 'type'.
</ul>
<a name="n12"></a><H3>11.6.5 Code generation (500-599)</H3>
<a name="n12"></a><H3>12.6.5 Code generation (500-599)</H3>
<ul>
@ -371,7 +371,7 @@ the input file to fix the problem.
<li>513. Can't generate wrappers for unnamed struct/class.
</ul>
<a name="n13"></a><H3>11.6.6 Language module specific (800-899) </H3>
<a name="n13"></a><H3>12.6.6 Language module specific (800-899) </H3>
<ul>
@ -402,12 +402,12 @@ the input file to fix the problem.
<li>838. No csin typemap defined for <em>type</em> (C#).
</ul>
<a name="n14"></a><H3>11.6.7 User defined (900-999)</H3>
<a name="n14"></a><H3>12.6.7 User defined (900-999)</H3>
These numbers can be used by your own application.
<a name="n15"></a><H2>11.7 History</H2>
<a name="n15"></a><H2>12.7 History</H2>
The ability to control warning messages was first added to SWIG-1.3.12.
@ -415,4 +415,4 @@ The ability to control warning messages was first added to SWIG-1.3.12.
<p><hr>
<address>SWIG 1.3 - Last Modified : June 28, 2003</address>
</body>
</html>
</html>

1
SWIG/Doc/Manual/chapters
View file

@ -12,6 +12,7 @@ Contract.html
Varargs.html
Warnings.html
Library.html
Modules.html
Advanced.html
Guile.html
Java.html

5
SWIG/Doc/Manual/index.html
View file

@ -49,6 +49,7 @@ to help!).
<li><a href="Contract.html">Contracts</a>
<li><a href="Varargs.html">Variable length arguments</a>
<li><a href="Warnings.html">Warning messages</a>
<li><a href="Modules.html">Working with Modules</a>
</ul>
<H3>Language Module Documentation</h3>
@ -83,10 +84,10 @@ implementation of typemaps. Make sure you read the <a href="Typemaps.html">Typ
chapter above if you are using this feature.
<ul>
<li><a href="Advanced.html">Advanced topics</a>
<li><a href="Advanced.html">Advanced topics</a> (see <a href="Modules.html">Modules</a> for updated information).
</ul>
<h3>Documentation not yet written</h3>
<h3>Documentation not yet written (volunteers needed)</h3>
<ul>
<li>Mzscheme module