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

added basic Modula-3 support

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@5776 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Henning Thielemann 2004-03-19 11:45:29 +00:00
commit 483d8b4367
57 changed files with 6645 additions and 380 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -7,7 +7,7 @@
<body bgcolor="#ffffff">
<a name="n1"></a><H1>24 SWIG and Chicken</H1>
<a name="n1"></a><H1>25 SWIG and Chicken</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Preliminaries</a>
@ -58,7 +58,7 @@
</p>
<a name="n2"></a><H2>24.1 Preliminaries</H2>
<a name="n2"></a><H2>25.1 Preliminaries</H2>
<p>
@ -79,7 +79,7 @@
</p>
<a name="n3"></a><H3>24.1.1 Running SWIG in C mode</H3>
<a name="n3"></a><H3>25.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>24.1.2 Running SWIG in C++ mode</H3>
<a name="n4"></a><H3>25.1.2 Running SWIG in C++ mode</H3>
<p>
@ -123,10 +123,10 @@
</p>
<a name="n5"></a><H2>24.2 Code Generation</H2>
<a name="n5"></a><H2>25.2 Code Generation</H2>
<a name="n6"></a><H3>24.2.1 Naming Conventions</H3>
<a name="n6"></a><H3>25.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>24.2.2 Modules and Prefixes</H3>
<a name="n7"></a><H3>25.2.2 Modules and Prefixes</H3>
<p>
@ -187,7 +187,7 @@
</p>
<a name="n8"></a><H3>24.2.3 Constants and Variables</H3>
<a name="n8"></a><H3>25.2.3 Constants and Variables</H3>
<p>
@ -212,7 +212,7 @@
use <tt>(my-variable)</tt>.
</p>
<a name="n9"></a><H3>24.2.4 Functions</H3>
<a name="n9"></a><H3>25.2.4 Functions</H3>
<p>
@ -231,7 +231,7 @@
parameters).
</p>
<a name="n10"></a><H2>24.3 TinyCLOS</H2>
<a name="n10"></a><H2>25.3 TinyCLOS</H2>
<p>
@ -269,7 +269,7 @@
</p>
<a name="n11"></a><H2>24.4 Compilation</H2>
<a name="n11"></a><H2>25.4 Compilation</H2>
<p>
@ -283,7 +283,7 @@
much simpler <tt>csc</tt> or <tt>csc.bat</tt>.
</p>
<a name="n12"></a><H2>24.5 Linkage</H2>
<a name="n12"></a><H2>25.5 Linkage</H2>
<p>
@ -307,7 +307,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
your platform.
</p>
<a name="n13"></a><H3>24.5.1 Customized Interpreter</H3>
<a name="n13"></a><H3>25.5.1 Customized Interpreter</H3>
<p>
@ -348,7 +348,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
</p>
<a name="n14"></a><H2>24.6 Typemaps</H2>
<a name="n14"></a><H2>25.6 Typemaps</H2>
<p>
@ -488,7 +488,7 @@ CHICKEN_HOME=/usr/local/share/chicken</pre>
</p>
<a name="n15"></a><H2>24.7 Pointers</H2>
<a name="n15"></a><H2>25.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>24.8 Unsupported features</H2>
<a name="n16"></a><H2>25.8 Unsupported features</H2>
<ul>

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

@ -38,11 +38,11 @@
<li><a href="Introduction.html#n7">Building a Perl5 module</a>
<li><a href="Introduction.html#n8">Building a Python module</a>
<li><a href="Introduction.html#n9">Shortcuts</a>
<li><a href="Introduction.html#n10">Building libraries and modules</a>
</ul>
<li><a href="Introduction.html#n11">Supported C/C++ language features</a>
<li><a href="Introduction.html#n12">Non-intrusive interface building</a>
<li><a href="Introduction.html#n13">Hands off code generation</a>
<li><a href="Introduction.html#n10">Supported C/C++ language features</a>
<li><a href="Introduction.html#n11">Non-intrusive interface building</a>
<li><a href="Introduction.html#n12">Hands off code generation</a>
<li><a href="Introduction.html#n13">SWIG and freedom</a>
</ul>
<!-- INDEX -->
@ -57,25 +57,26 @@
</ul>
<li><a href="Windows.html#n5">SWIG Windows Examples</a>
<ul>
<li><a href="Windows.html#n6">Instructions for using the Examples with Visual C++</a>
<li><a href="Windows.html#n6">Instructions for using the Examples with Visual Studio</a>
<ul>
<li><a href="Windows.html#n7">Python</a>
<li><a href="Windows.html#n8">TCL</a>
<li><a href="Windows.html#n9">Perl</a>
<li><a href="Windows.html#n10">Java</a>
<li><a href="Windows.html#n11">Ruby</a>
<li><a href="Windows.html#n12">C#</a>
</ul>
<li><a href="Windows.html#n12">Instructions for using the Examples with other compilers</a>
<li><a href="Windows.html#n13">Instructions for using the Examples with other compilers</a>
</ul>
<li><a href="Windows.html#n13">SWIG on Cygwin and MinGW</a>
<li><a href="Windows.html#n14">SWIG on Cygwin and MinGW</a>
<ul>
<li><a href="Windows.html#n14">Building swig.exe on Windows</a>
<li><a href="Windows.html#n15">Building swig.exe on Windows</a>
<ul>
<li><a href="Windows.html#n15">Building swig.exe using MinGW and MSYS</a>
<li><a href="Windows.html#n16">Building swig.exe using Cygwin</a>
<li><a href="Windows.html#n17">Building swig.exe alternatives</a>
<li><a href="Windows.html#n16">Building swig.exe using MinGW and MSYS</a>
<li><a href="Windows.html#n17">Building swig.exe using Cygwin</a>
<li><a href="Windows.html#n18">Building swig.exe alternatives</a>
</ul>
<li><a href="Windows.html#n18">Running the examples on Windows using Cygwin</a>
<li><a href="Windows.html#n19">Running the examples on Windows using Cygwin</a>
</ul>
</ul>
<!-- INDEX -->
@ -380,17 +381,18 @@
<li><a href="Warnings.html#n4">Enabling additional warnings</a>
<li><a href="Warnings.html#n5">Issuing a warning message</a>
<li><a href="Warnings.html#n6">Commentary</a>
<li><a href="Warnings.html#n7">Warning number reference</a>
<li><a href="Warnings.html#n7">Message output format</a>
<li><a href="Warnings.html#n8">Warning number reference</a>
<ul>
<li><a href="Warnings.html#n8">Deprecated features (100-199)</a>
<li><a href="Warnings.html#n9">Preprocessor (200-299)</a>
<li><a href="Warnings.html#n10">C/C++ Parser (300-399)</a>
<li><a href="Warnings.html#n11">Types and typemaps (400-499) </a>
<li><a href="Warnings.html#n12">Code generation (500-599)</a>
<li><a href="Warnings.html#n13">Language module specific (800-899) </a>
<li><a href="Warnings.html#n14">User defined (900-999)</a>
<li><a href="Warnings.html#n9">Deprecated features (100-199)</a>
<li><a href="Warnings.html#n10">Preprocessor (200-299)</a>
<li><a href="Warnings.html#n11">C/C++ Parser (300-399)</a>
<li><a href="Warnings.html#n12">Types and typemaps (400-499) </a>
<li><a href="Warnings.html#n13">Code generation (500-599)</a>
<li><a href="Warnings.html#n14">Language module specific (800-899) </a>
<li><a href="Warnings.html#n15">User defined (900-999)</a>
</ul>
<li><a href="Warnings.html#n15">History</a>
<li><a href="Warnings.html#n16">History</a>
</ul>
<!-- INDEX -->
@ -603,7 +605,28 @@
</ul>
<!-- INDEX -->
<h3><a href="Ocaml.html">18 SWIG and Ocaml</a></h3>
<h3><a href="Modula3.html">18 SWIG and Modula-3</a></h3>
<!-- INDEX -->
<ul>
<li><a href="Modula3.html#n2">Overview</a>
<li><a href="Modula3.html#n3">Preliminaries</a>
<ul>
<li><a href="Modula3.html#n4">Compilers</a>
<li><a href="Modula3.html#n5">Additional Commandline Options</a>
</ul>
<li><a href="Modula3.html#n6">Modula-3 typemaps</a>
<ul>
<li><a href="Modula3.html#n7">Inputs and outputs</a>
<li><a href="Modula3.html#n8">Exceptions</a>
<li><a href="Modula3.html#n9">Subranges, Enumerations, Sets</a>
<li><a href="Modula3.html#n10">Objects</a>
<li><a href="Modula3.html#n11">Example</a>
</ul>
</ul>
<!-- INDEX -->
<h3><a href="Ocaml.html">19 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<ul>
@ -649,7 +672,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Perl5.html">19 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html">20 SWIG and Perl5</a></h3>
<!-- INDEX -->
<ul>
@ -711,7 +734,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Php.html">20 SWIG and PHP4</a></h3>
<h3><a href="Php.html">21 SWIG and PHP4</a></h3>
<!-- INDEX -->
<ul>
@ -735,7 +758,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Python.html">21 SWIG and Python</a></h3>
<h3><a href="Python.html">22 SWIG and Python</a></h3>
<!-- INDEX -->
<ul>
@ -821,7 +844,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Ruby.html">22 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html">23 SWIG and Ruby</a></h3>
<!-- INDEX -->
<ul>
@ -896,7 +919,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Tcl.html">23 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html">24 SWIG and Tcl</a></h3>
<!-- INDEX -->
<ul>
@ -959,7 +982,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Chicken.html">24 SWIG and Chicken</a></h3>
<h3><a href="Chicken.html">25 SWIG and Chicken</a></h3>
<!-- INDEX -->
<ul>
@ -987,7 +1010,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Extending.html">25 Extending SWIG</a></h3>
<h3><a href="Extending.html">26 Extending SWIG</a></h3>
<!-- INDEX -->
<ul>

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

@ -155,6 +155,7 @@ this means that both the arguments to <tt>Spam::bar</tt> must be positive.
<a name="n4"></a><H2>10.3 Constant aggregation and %aggregate_check</H2>
Consider an interface file that contains the following code:
<blockquote>
@ -238,4 +239,4 @@ in SWIG-1.3.20.
<address>SWIG 1.3 - Last Modified : November 12, 2003</address>
</body>
</html>
</html>

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>25 Extending SWIG</H1>
<a name="n1"></a><H1>26 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>25.1 Introduction</H2>
<a name="n2"></a><H2>26.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>25.2 Prerequisites</H2>
<a name="n3"></a><H2>26.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>25.3 The Big Picture</H2>
<a name="n4"></a><H2>26.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>25.4 Execution Model</H2>
<a name="n5"></a><H2>26.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>25.4.1 Preprocessing</H3>
<a name="n6"></a><H3>26.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>25.4.2 Parsing</H3>
<a name="n7"></a><H3>26.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>25.4.3 Parse Trees</H3>
<a name="n8"></a><H3>26.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>25.4.4 Attribute namespaces</H3>
<a name="n9"></a><H3>26.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>25.4.5 Symbol Tables</H3>
<a name="n10"></a><H3>26.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>25.4.6 The %feature directive</H3>
<a name="n11"></a><H3>26.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>25.4.7 Code Generation</H3>
<a name="n12"></a><H3>26.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>25.4.8 SWIG and XML</H3>
<a name="n13"></a><H3>26.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>25.5 Primitive Data Structures</H2>
<a name="n14"></a><H2>26.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>25.5.1 Strings</H3>
<a name="n15"></a><H3>26.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>25.5.2 Hashes</H3>
<a name="n16"></a><H3>26.5.2 Hashes</H3>
<p>
@ -1062,7 +1062,7 @@ Returns the list of hash table keys.
</blockquote>
<a name="n17"></a><H3>25.5.3 Lists</H3>
<a name="n17"></a><H3>26.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>25.5.4 Common operations</H3>
<a name="n18"></a><H3>26.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>25.5.5 Iterating over Lists and Hashes</H3>
<a name="n19"></a><H3>26.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>25.5.6 I/O</H3>
<a name="n20"></a><H3>26.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>25.6 Navigating and manipulating parse trees</H2>
<a name="n21"></a><H2>26.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>25.7 Working with attributes</H2>
<a name="n22"></a><H2>26.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>25.8 Type system</H2>
<a name="n23"></a><H2>26.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>25.8.1 String encoding of types</H3>
<a name="n24"></a><H3>26.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>25.8.2 Type construction</H3>
<a name="n25"></a><H3>26.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>25.8.3 Type tests</H3>
<a name="n26"></a><H3>26.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>25.8.4 Typedef and inheritance</H3>
<a name="n27"></a><H3>26.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>25.8.5 Lvalues</H3>
<a name="n28"></a><H3>26.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>25.8.6 Output functions</H3>
<a name="n29"></a><H3>26.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>25.9 Parameters</H2>
<a name="n30"></a><H2>26.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>25.10 Writing a Language Module</H2>
<a name="n31"></a><H2>26.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>25.10.1 Execution model</H3>
<a name="n32"></a><H3>26.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>25.10.2 Starting out</H3>
<a name="n33"></a><H3>26.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>25.10.3 Command line options</H3>
<a name="n34"></a><H3>26.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>25.10.4 Configuration and preprocessing</H3>
<a name="n35"></a><H3>26.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>25.10.5 Entry point to code generation</H3>
<a name="n36"></a><H3>26.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>25.10.6 Module I/O and wrapper skeleton</H3>
<a name="n37"></a><H3>26.10.6 Module I/O and wrapper skeleton</H3>
<a name="n38"></a><H3>25.10.7 Low-level code generators</H3>
<a name="n38"></a><H3>26.10.7 Low-level code generators</H3>
<a name="n39"></a><H3>25.10.8 Configuration files</H3>
<a name="n39"></a><H3>26.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>25.10.9 Runtime support</H3>
<a name="n40"></a><H3>26.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>25.10.10 Standard library files</H3>
<a name="n41"></a><H3>26.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>25.10.11 Examples and test cases</H3>
<a name="n42"></a><H3>26.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>25.10.12 Documentation</H3>
<a name="n43"></a><H3>26.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>25.11 Typemaps</H2>
<a name="n44"></a><H2>26.11 Typemaps</H2>
<a name="n45"></a><H3>25.11.1 Proxy classes</H3>
<a name="n45"></a><H3>26.11.1 Proxy classes</H3>
<a name="n46"></a><H2>25.12 Guide to parse tree nodes</H2>
<a name="n46"></a><H2>26.12 Guide to parse tree nodes</H2>
This section describes the different parse tree nodes and their attributes.
@ -2817,4 +2817,4 @@ extern "X" { ... } declaration.
<address>SWIG 1.3 - Last Modified : January 22, 2002</address>
</body>
</html>
</html>

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

@ -17,11 +17,11 @@
<li><a href="#n7">Building a Perl5 module</a>
<li><a href="#n8">Building a Python module</a>
<li><a href="#n9">Shortcuts</a>
<li><a href="#n10">Building libraries and modules</a>
</ul>
<li><a href="#n11">Supported C/C++ language features</a>
<li><a href="#n12">Non-intrusive interface building</a>
<li><a href="#n13">Hands off code generation</a>
<li><a href="#n10">Supported C/C++ language features</a>
<li><a href="#n11">Non-intrusive interface building</a>
<li><a href="#n12">Hands off code generation</a>
<li><a href="#n13">SWIG and freedom</a>
</ul>
<!-- INDEX -->
@ -67,6 +67,7 @@ in scientific and engineering projects.
<a name="n3"></a><H2>1.2 Why use SWIG?</H2>
As stated in the previous section, the primary purpose of SWIG is to simplify
the task of integrating C/C++ with other programming languages. However, why would
anyone want to do that? To answer that question, it is useful to list a few strengths
@ -286,7 +287,8 @@ print $example::My_variable + 4.5, "\n";
7.5
</pre></blockquote>
<a name="n11"></a><H2>1.4 Supported C/C++ language features</H2>
<a name="n10"></a><H2>1.4 Supported C/C++ language features</H2>
A primary goal of the SWIG project is to make the language binding
process extremely easy. Although a few simple examples have been shown,
@ -321,7 +323,8 @@ wrapping simple C++ code. In fact, SWIG is able handle C++ code that
stresses the very limits of many C++ compilers.
<a name="n12"></a><H2>1.5 Non-intrusive interface building</H2>
<a name="n11"></a><H2>1.5 Non-intrusive interface building</H2>
When used as intended, SWIG requires minimal (if any) modification to
existing C code. This makes SWIG extremely easy to use with existing
@ -330,7 +333,7 @@ the C code independent of the high level interface, you can change the
interface and reuse the code in other applications. It is also
possible to support different types of interfaces depending on the application.
<a name="n13"></a><H2>1.6 Hands off code generation</H2>
<a name="n12"></a><H2>1.6 Hands off code generation</H2>
SWIG is designed to produce working code that needs no
@ -343,7 +346,8 @@ file. While this approach may limit flexibility for hard-core hackers,
it allows others to forget about the low-level implementation
details.
<H2>SWIG and freedom</h2>
<a name="n13"></a><H2>1.7 SWIG and freedom</H2>
No, this isn't a special section on the sorry state of world politics.
However, it may be useful to know that SWIG was written with a
@ -371,4 +375,4 @@ non-portable or unreliable programming features.
<address>SWIG 1.3 - Last Modified : August 10, 2002</address>
</body>
</html>
</html>

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

@ -4789,4 +4789,4 @@ If your SWIG installation went well Unix users should be able to type <tt>make</
For the benefit of Windows users, there are also Visual C++ project files in a couple of the <a href="Windows.html#examples">Windows Examples</a>.
</body>
</html>
</html>

360
SWIG/Doc/Manual/Modula3.html Normal file
View file

@ -0,0 +1,360 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>SWIG and Modula-3</title>
</head>
<body bgcolor="#FFFFFF">
<a name="n1"></a><H1>18 SWIG and Modula-3</H1>
<!-- INDEX -->
<ul>
<li><a href="#n2">Overview</a>
<li><a href="#n3">Preliminaries</a>
<ul>
<li><a href="#n4">Compilers</a>
<li><a href="#n5">Additional Commandline Options</a>
</ul>
<li><a href="#n6">Modula-3 typemaps</a>
<ul>
<li><a href="#n7">Inputs and outputs</a>
<li><a href="#n8">Exceptions</a>
<li><a href="#n9">Subranges, Enumerations, Sets</a>
<li><a href="#n10">Objects</a>
<li><a href="#n11">Example</a>
</ul>
</ul>
<!-- INDEX -->
This chapter describes SWIG's support of
<a href="http://www.m3.org/">Modula-3</a>.
You should be familiar with the
<a href="SWIG.html">basics</a>
of SWIG,
especially typemaps.
<a name="overview"></a>
<a name="n2"></a><H2>18.1 Overview</H2>
<p>
The Modula-3 support is very basic and highly experimental!
Many features are still not designed satisfyingly
and I need more discussion about the odds and ends.
The Modula-3 generator was already useful for interfacing
to the
<a href="http://www.elegosoft.com/cgi-bin/cvsweb.cgi/cm3/m3-libs/plplot/">
PLPlot
</a>
library.
<!--
<p>
The following introduction may help you
when you are uncertain about using
the Modula-3 support or SWIG at all.
<a name="whycxx"></a>
<a name="n3"></a><DISABLED>18.1.1 Why not scripting ?</DISABLED>
<p>
SWIG started as wrapper from the fast compiled languages C and C++
to high level scripting languages like Python.
Although scripting languages are designed
to make programming life easier
by hiding machine internals from the programmer
there are several aspects of todays scripting languages
that are unfavourable in my opinion.
<p>
Besides C, C++, Cluster (a Modula derivate for Amiga computers)
I evaluated several scripting like languages in the past:
Different dialects of BASIC,
Perl, ARexx (a variant of Rexx for Amiga computers),
shell scripts.
I found them too inconsistent,
too weak in distinguishing types,
too weak in encapsulating pieces of code.
Eventually I have started several projects in Python
because of the fine syntax.
But when projects became larger
I lost the track.
I got convinced that one can not have
maintainable code in a language
that is not statically typed.
In fact the main advantages of scripting languages
e.g. matching regular expressions,
complex built-in datatypes like lists, dictionaries,
are not advantages of the language itself
but can be provided by function libraries.
<a name="whymodula3"></a>
<a name="n4"></a><DISABLED>18.1.2 Why Modula-3 ?</DISABLED>
<p>
Modula-3 is a compiler language
in the tradition of Niklas Wirth's Modula 2,
which is in turn a successor of the popular Pascal.
I have chosen Modula-3
because of its
logical syntax,
strong modularization,
the type system which is very detailed
for machine types compared to other languages.
Of course it supports all of the modern games
like exceptions, objects, garbage collection, threads.
While C++ programmers must
control three languages,
namely the preprocessor, C and ++,
Modula-3 is made in one go
and the language definition is really compact.
On the one hand Modula-3 can be safe
(but probably less efficient) in normal modules
while providing much static and dynamic safety.
On the other hand you can write efficient
but less safe code in the style of C
within UNSAFE modules.
<p>
Unfortunately Modula's safety and strength
requires more writing than scripting languages do.
Today if I want to safe characters
I prefer Haskell (similar to OCAML) -
it's statically typed, too.
<a name="whycxx"></a>
<a name="n5"></a><DISABLED>18.1.3 Why C / C++ ?</DISABLED>
<p>
Although it is no problem to write Modula-3 programs
that performs as fast as C
most libraries are not written in Modula-3 but in C.
Fortunately the binary interface of most function libraries
can be addressed by Modula-3.
Even more fortunately even non-C libraries may provide C header files.
This is where SWIG becomes helpful.
<a name="whycxx"></a>
<a name="n6"></a><DISABLED>18.1.4 Why SWIG ?</DISABLED>
<p>
The C headers and the possibility to interface to C libraries
still leaves the work for you
to write Modula-3 interfaces to them.
To make things comfortable you will also need
wrappers that convert between high-level features of Modula-3
(garbage collecting, exceptions)
and the low level of the C libraries.
<p>
SWIG converts C headers to Modula-3 interfaces for you.
You could call the C functions without loss
of efficiency but it won't be joy
because you could not pass TEXTs
or open arrays and
you would have to process error return codes
rather then exceptions.
But using some typemaps SWIG will also generate
wrappers that bring the whole Modula-3 comfort to you.
If the library API is ill designed
writing appropriate typemaps can be still time-consuming.
E.g. C programmers are very creative to work-around
missing data types like (real) enumerations and sets.
You should turn such work-arounds back to the Modula-3 way
otherwise you lose static safety and consistency.
<p>
But you have still a problem:
C library interfaces are often ill.
They lack for certain information
because C compilers wouldn't care about.
You should integrate detailed type information
by adding <tt>typedef</tt>s and <tt>const</tt>s
and you should persuade the C library programmer
to add this information to his interface.
Only this way other language users can benefit from your work
and only this way you can easily update your interfaces
when a new library version is released.
You will realise that writing <b>good</b> SWIG interfaces
is very costly and it will only amortise
when considering evolving libraries.
<p>
Without SWIG you would probably never consider
to call C++ libraries from Modula-3.
But with SWIG this is worth a consideration.
SWIG can write C wrappers to C++ functions and object methods
that may throw exceptions.
In fact it breaks down C++ libraries to C interfaces
which can be in turn called from Modula-3.
To make it complete you can hide the C interface
with Modula-3 classes and exceptions.
<p>
Although SWIG does the best it can do
it can only serve as a one-way strategy.
That means you can use C++ libraries
with Modula-3 (even with call back functions),
but it's certainly not possible to smoothly
integrate Modula-3 code into a C / C++ project.
-->
<a name="preliminaries"></a>
<a name="n3"></a><H2>18.2 Preliminaries</H2>
<a name="compilers"></a>
<a name="n4"></a><H3>18.2.1 Compilers</H3>
There are different Modula-3 compilers around:
cm3, pm3, ezm3, Klagenfurth Modula-3, Cambridge Modula-3.
SWIG itself does not contain compiler specific code
but the library file
<a href="../../Lib/modula3/modula3.swg"><tt>modula3.swg</tt></a>
may do so.
For testing examples I used Critical Mass' cm3.
<a name="commandline"></a>
<a name="n5"></a><H3>18.2.2 Additional Commandline Options</H3>
There some experimental command line options
that prevent SWIG from generating interface files.
Instead files are emitted that may assist
writing SWIG interface files.
<table>
<tr>
<th>Modula-3 specific options</th>
</tr>
<tr>
<td>-generateconst &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate code for computing numeric values of constants.
</td>
</tr>
<tr>
<td>-generaterename &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate suggestions for %rename.
</td>
</tr>
<tr>
<td>-generatetypemap &lt;file&gt;</td>
<td>
Disable generation of interfaces and wrappers.
Instead generate templates for some basic typemaps.
</td>
</tr>
</table>
<a name="typemaps"></a>
<a name="n6"></a><H2>18.3 Modula-3 typemaps</H2>
<a name="inoutparam"></a>
<a name="n7"></a><H3>18.3.1 Inputs and outputs</H3>
Each C procedure has a bunch of inputs and outputs.
Aside from global variables
inputs are passed as call arguments,
outputs are updated reference arguments and
the function value.
Each C type can have several typemaps
that apply only in case the types are used
as input argument, as output argument,
or as return value.
A further typemap may specify
the direction that is used for certain parameters.
<a name="exceptions"></a>
<a name="n8"></a><H3>18.3.2 Exceptions</H3>
Modula-3 provides another possibility
of an output of a function: exceptions.
Any piecec of Modula-3 code that SWIG inserts
due to a typemap can raise an exception.
This way you can also convert an error code
from a C function into an Modula-3 exception.
The <tt>RAISES</tt> clause is controlled
by typemaps with the <tt>except</tt> extension.
<a name="ordinals"></a>
<a name="n9"></a><H3>18.3.3 Subranges, Enumerations, Sets</H3>
<a name="class"></a>
<a name="n10"></a><H3>18.3.4 Objects</H3>
<a name="typemap_examlpe"></a>
<a name="n11"></a><H3>18.3.5 Example</H3>
The generation of wrappers in Modula-3 needs very fine control
to take advantage of the language features.
Here is an example of a generated wrapper
where almost everything is generated by a typemap:
<blockquote><pre>
<I> (* %relabel m3wrapinmode m3wrapinname m3wrapintype m3wrapindefault *)</I>
PROCEDURE Name (READONLY str : TEXT := "" )
<I> (* m3wrapoutcheck:throws *)</I>
: NameResult RAISES {E} =
VAR
arg0 : C.char_star; <I>(* m3wrapretvar *)</I>
arg1 : C.char_star; <I>(* m3wrapargvar *)</I>
arg2 : C.int;
result : RECORD
<I> (*m3wrapretname m3wraprettype*)</I>
unixPath : TEXT;
<I> (*m3wrapoutname m3wrapouttype*)</I>
checksum : CARDINAL;
END;
BEGIN
TRY
arg1 := M3toC.SharedTtoS(str); <I>(* m3wrapinconv *)</I>
IF Text.Length(arg1) > 10 THEN <I>(* m3wrapincheck *)</I>
RAISE E("str too long");
END;
<I> (* m3wrapretraw m3wrapargraw *)</I>
arg0 := MessyToUnix (arg1, arg2);
result.unixPath := M3toC.CopyStoT(arg0); <I>(* m3wrapretconv *)</I>
result.checksum := arg2; <I>(* m3wrapoutconv *)</I>
IF result.checksum = 0 THEN <I>(* m3wrapoutcheck *)</I>
RAISE E("invalid checksum");
END;
FINALLY
M3toC.FreeSharedS(str,arg1); <I>(* m3wrapfreearg *)</I>
END;
END Name;
</pre></blockquote>
</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>18 SWIG and Ocaml</H1>
<a name="n1"></a><H1>19 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>18.1 Preliminaries</H2>
<a name="n2"></a><H2>19.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>18.1.1 Running SWIG</H3>
<a name="n3"></a><H3>19.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>18.1.2 Compiling the code</H3>
<a name="n4"></a><H3>19.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>18.1.3 The camlp4 module</H3>
<a name="n5"></a><H3>19.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>18.1.4 Using your module</H3>
<a name="n6"></a><H3>19.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>18.1.5 Compilation problems and compiling with C++</H3>
<a name="n7"></a><H3>19.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>18.2 The low-level Ocaml/C interface</H2>
<a name="n8"></a><H2>19.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>18.2.1 The generated module</H3>
<a name="n9"></a><H3>19.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>18.2.2 Enums</H3>
<a name="n10"></a><H3>19.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>18.2.3 Arrays</H3>
<a name="n11"></a><H3>19.2.3 Arrays</H3>
<a name="n12"></a><H4>18.2.3.1 Simple types of bounded arrays</H4>
<a name="n12"></a><H4>19.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>18.2.3.2 Complex and unbounded arrays</H4>
<a name="n13"></a><H4>19.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>18.2.3.3 Using an object</H4>
<a name="n14"></a><H4>19.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>18.2.3.4 Example typemap for a function taking float * and int</H4>
<a name="n15"></a><H4>19.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>18.2.4 C++ Classes</H3>
<a name="n16"></a><H3>19.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>18.2.4.1 STL vector and string Example</H4>
<a name="n17"></a><H4>19.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>18.2.4.2 C++ Class Example</H4>
<a name="n18"></a><H4>19.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>18.2.4.3 Compiling the example</H4>
<a name="n19"></a><H4>19.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>18.2.4.4 Sample Session</H4>
<a name="n20"></a><H4>19.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>18.2.5 Director Classes</H3>
<a name="n21"></a><H3>19.2.5 Director Classes</H3>
<a name="n22"></a><H4>18.2.5.1 Director Introduction</H4>
<a name="n22"></a><H4>19.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>18.2.5.2 Overriding Methods in Ocaml</H4>
<a name="n23"></a><H4>19.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>18.2.5.3 Director Usage Example</H4>
<a name="n24"></a><H4>19.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>18.2.5.4 Creating director objects</H4>
<a name="n25"></a><H4>19.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>18.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<a name="n26"></a><H4>19.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>18.2.5.6 <tt>directorin</tt> typemap</H4>
<a name="n27"></a><H4>19.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>18.2.5.7 <tt>directorout</tt> typemap</H4>
<a name="n28"></a><H4>19.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>18.2.5.8 <tt>directorargout</tt> typemap</H4>
<a name="n29"></a><H4>19.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>18.2.6 Exceptions</H3>
<a name="n30"></a><H3>19.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>19 SWIG and Perl5</H1>
<a name="n1"></a><H1>20 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>19.1 Overview</H2>
<a name="n2"></a><H2>20.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>19.2 Preliminaries</H2>
<a name="n3"></a><H2>20.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>19.2.1 Getting the right header files</H3>
<a name="n4"></a><H3>20.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>19.2.2 Compiling a dynamic module</H3>
<a name="n5"></a><H3>20.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>19.2.3 Building a dynamic module with MakeMaker</H3>
<a name="n6"></a><H3>20.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>19.2.4 Building a static version of Perl</H3>
<a name="n7"></a><H3>20.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>19.2.5 Using the module</H3>
<a name="n8"></a><H3>20.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>19.2.6 Compilation problems and compiling with C++</H3>
<a name="n9"></a><H3>20.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>19.2.7 Compiling for 64-bit platforms</H3>
<a name="n10"></a><H3>20.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>19.3 Building Perl Extensions under Windows</H2>
<a name="n11"></a><H2>20.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>19.3.1 Running SWIG from Developer Studio</H3>
<a name="n12"></a><H3>20.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>19.3.2 Using other compilers</H3>
<a name="n13"></a><H3>20.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>19.4 The low-level interface</H2>
<a name="n14"></a><H2>20.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>19.4.1 Functions</H3>
<a name="n15"></a><H3>20.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>19.4.2 Global variables</H3>
<a name="n16"></a><H3>20.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>19.4.3 Constants</H3>
<a name="n17"></a><H3>20.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>19.4.4 Pointers</H3>
<a name="n18"></a><H3>20.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>19.4.5 Structures</H3>
<a name="n19"></a><H3>20.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>19.4.6 C++ classes</H3>
<a name="n20"></a><H3>20.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>19.4.7 C++ classes and type-checking</H3>
<a name="n21"></a><H3>20.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>19.4.8 C++ overloaded functions</H3>
<a name="n22"></a><H3>20.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>19.4.9 Operators</H3>
<a name="n23"></a><H3>20.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>19.4.10 Modules and packages</H3>
<a name="n24"></a><H3>20.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>19.5 Input and output parameters</H2>
<a name="n25"></a><H2>20.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>19.6 Exception handling </H2>
<a name="n26"></a><H2>20.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>19.7 Remapping datatypes with typemaps</H2>
<a name="n27"></a><H2>20.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>19.7.1 A simple typemap example</H3>
<a name="n28"></a><H3>20.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>19.7.2 Perl5 typemaps</H3>
<a name="n29"></a><H3>20.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>19.7.3 Typemap variables</H3>
<a name="n30"></a><H3>20.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>19.7.4 Useful functions</H3>
<a name="n31"></a><H3>20.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>19.8 Typemap Examples</H2>
<a name="n32"></a><H2>20.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>19.8.1 Converting a Perl5 array to a char ** </H3>
<a name="n33"></a><H3>20.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>19.8.2 Return values </H3>
<a name="n34"></a><H3>20.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>19.8.3 Returning values from arguments</H3>
<a name="n35"></a><H3>20.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>19.8.4 Accessing array structure members</H3>
<a name="n36"></a><H3>20.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>19.8.5 Turning Perl references into C pointers</H3>
<a name="n37"></a><H3>20.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>19.8.6 Pointer handling</H3>
<a name="n38"></a><H3>20.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>19.9 Proxy classes</H2>
<a name="n39"></a><H2>20.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>19.9.1 Preliminaries</H3>
<a name="n40"></a><H3>20.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>19.9.2 Object Ownership</H3>
<a name="n41"></a><H3>20.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>19.9.3 Nested Objects</H3>
<a name="n42"></a><H3>20.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>19.9.4 Shadow Functions</H3>
<a name="n43"></a><H3>20.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>19.9.5 Inheritance</H3>
<a name="n44"></a><H3>20.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>20 SWIG and PHP4</H1>
<a name="n1"></a><H1>21 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>20.1 Preliminaries</H2>
<a name="n2"></a><H2>21.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>20.2 Building PHP4 Extensions</H2>
<a name="n3"></a><H2>21.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>20.2.1 Building a loadable extension</H3>
<a name="n4"></a><H3>21.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>20.2.2 Basic PHP4 interface</H3>
<a name="n5"></a><H3>21.2.2 Basic PHP4 interface</H3>
<a name="n6"></a><H3>20.2.3 Functions</H3>
<a name="n6"></a><H3>21.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>20.2.4 Global Variables</H3>
<a name="n7"></a><H3>21.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>20.2.5 Pointers </H3>
<a name="n8"></a><H3>21.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>20.2.6 Structures and C++ classes</H3>
<a name="n9"></a><H3>21.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>20.2.7 Constants</H3>
<a name="n10"></a><H3>21.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>20.2.8 Shadow classes</H3>
<a name="n11"></a><H3>21.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>20.2.9 Constructors and Destructers</H3>
<a name="n12"></a><H3>21.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>20.2.10 Static Member Variables</H3>
<a name="n13"></a><H3>21.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>20.2.11 PHP4 Pragmas</H3>
<a name="n14"></a><H3>21.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>20.2.12 Building extensions into php</H3>
<a name="n15"></a><H3>21.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>20.2.13 To be furthered...</H3>
<a name="n16"></a><H3>21.2.13 To be furthered...</H3>
</body>

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

@ -105,6 +105,7 @@ about this can be obtained at:
<a name="n6"></a><H2>0.5 Prerequisites</H2>
This manual assumes that you know how to write C/C++ programs and that you
have at least heard of scripting languages such as
Tcl, Python, and Perl. A detailed knowledge of these scripting
@ -188,6 +189,7 @@ port.
<a name="n11"></a><H2>0.10 Bug reports</H2>
Although every attempt has been made to make SWIG bug-free, we are also trying
to make feature improvements that may introduce bugs.
To report a bug, either send mail to the SWIG developer
@ -201,4 +203,4 @@ can only fix bugs if we know about them.
<p><hr>
<address>SWIG 1.3 - Last Modified : March 9, 2003</address>
</body>
</html>
</html>

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a><H1>21 SWIG and Python</H1>
<a name="n1"></a><H1>22 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>21.1 Overview</H2>
<a name="n2"></a><H2>22.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>21.2 Preliminaries</H2>
<a name="n3"></a><H2>22.2 Preliminaries</H2>
<a name="n4"></a><H3>21.2.1 Running SWIG</H3>
<a name="n4"></a><H3>22.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>21.2.2 Getting the right header files</H3>
<a name="n5"></a><H3>22.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>21.2.3 Compiling a dynamic module</H3>
<a name="n6"></a><H3>22.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>21.2.4 Using distutils</H3>
<a name="n7"></a><H3>22.2.4 Using distutils</H3>
<a name="n8"></a><H3>21.2.5 Static linking</H3>
<a name="n8"></a><H3>22.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>21.2.6 Using your module</H3>
<a name="n9"></a><H3>22.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>21.2.7 Compilation of C++ extensions</H3>
<a name="n10"></a><H3>22.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>21.2.8 Compiling for 64-bit platforms</H3>
<a name="n11"></a><H3>22.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>21.2.9 Building Python Extensions under Windows</H3>
<a name="n12"></a><H3>22.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>21.3 A tour of basic C/C++ wrapping</H2>
<a name="n13"></a><H2>22.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>21.3.1 Modules</H3>
<a name="n14"></a><H3>22.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>21.3.2 Functions</H3>
<a name="n15"></a><H3>22.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>21.3.3 Global variables</H3>
<a name="n16"></a><H3>22.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>21.3.4 Constants and enums</H3>
<a name="n17"></a><H3>22.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>21.3.5 Pointers</H3>
<a name="n18"></a><H3>22.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>21.3.6 Structures</H3>
<a name="n19"></a><H3>22.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>21.3.7 C++ classes</H3>
<a name="n20"></a><H3>22.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>21.3.8 C++ inheritance</H3>
<a name="n21"></a><H3>22.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>21.3.9 Pointers, references, values, and arrays</H3>
<a name="n22"></a><H3>22.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>21.3.10 C++ overloaded functions</H3>
<a name="n23"></a><H3>22.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>21.3.11 C++ operators</H3>
<a name="n24"></a><H3>22.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>21.3.12 C++ namespaces</H3>
<a name="n25"></a><H3>22.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>21.3.13 C++ templates</H3>
<a name="n26"></a><H3>22.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>21.3.14 C++ Smart Pointers</H3>
<a name="n27"></a><H3>22.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>21.4 Further details on the Python class interface</H2>
<a name="n28"></a><H2>22.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>21.4.1 Proxy classes</H3>
<a name="n29"></a><H3>22.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>21.4.2 Memory management</H3>
<a name="n30"></a><H3>22.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>21.4.3 Python 2.2 and classic classes</H3>
<a name="n31"></a><H3>22.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>21.5 Cross language polymorphism (experimental)</H2>
<a name="n32"></a><H2>22.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>21.5.1 Enabling directors</H3>
<a name="n33"></a><H3>22.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>21.5.2 Director classes</H3>
<a name="n34"></a><H3>22.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>21.5.3 Ownership and object destruction</H3>
<a name="n35"></a><H3>22.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>21.5.4 Exception unrolling</H3>
<a name="n36"></a><H3>22.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>21.5.5 Overhead and code bloat</H3>
<a name="n37"></a><H3>22.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>21.5.6 Typemaps</H3>
<a name="n38"></a><H3>22.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>21.5.7 Miscellaneous</H3>
<a name="n39"></a><H3>22.5.7 Miscellaneous</H3>
<a name="n40"></a><H2>21.6 Common customization features</H2>
<a name="n40"></a><H2>22.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>21.6.1 C/C++ helper functions</H3>
<a name="n41"></a><H3>22.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>21.6.2 Adding additional Python code</H3>
<a name="n42"></a><H3>22.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>21.6.3 Class extension with %extend</H3>
<a name="n43"></a><H3>22.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>21.6.4 Exception handling with %exception</H3>
<a name="n44"></a><H3>22.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>21.7 Tips and techniques</H2>
<a name="n45"></a><H2>22.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>21.7.1 Input and output parameters</H3>
<a name="n46"></a><H3>22.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>21.7.2 Simple pointers</H3>
<a name="n47"></a><H3>22.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>21.7.3 Unbounded C Arrays</H3>
<a name="n48"></a><H3>22.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>21.7.4 String handling</H3>
<a name="n49"></a><H3>22.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>21.7.5 Arrays</H3>
<a name="n50"></a><H3>22.7.5 Arrays</H3>
<a name="n51"></a><H3>21.7.6 String arrays</H3>
<a name="n51"></a><H3>22.7.6 String arrays</H3>
<a name="n52"></a><H3>21.7.7 STL wrappers</H3>
<a name="n52"></a><H3>22.7.7 STL wrappers</H3>
<a name="n53"></a><H2>21.8 Typemaps</H2>
<a name="n53"></a><H2>22.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>21.8.1 What is a typemap?</H3>
<a name="n54"></a><H3>22.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>21.8.2 Python typemaps</H3>
<a name="n55"></a><H3>22.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>21.8.3 Typemap variables</H3>
<a name="n56"></a><H3>22.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>21.8.4 Useful Python Functions</H3>
<a name="n57"></a><H3>22.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>21.9 Typemap Examples</H2>
<a name="n58"></a><H2>22.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>21.9.1 Converting Python list to a char ** </H3>
<a name="n59"></a><H3>22.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>21.9.2 Expanding a Python object into multiple arguments</H3>
<a name="n60"></a><H3>22.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>21.9.3 Using typemaps to return arguments</H3>
<a name="n61"></a><H3>22.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>21.9.4 Mapping Python tuples into small arrays</H3>
<a name="n62"></a><H3>22.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>21.9.5 Mapping sequences to C arrays</H3>
<a name="n63"></a><H3>22.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>21.9.6 Pointer handling</H3>
<a name="n64"></a><H3>22.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>22 SWIG and Ruby</H1>
<a name="n1"></a><H1>23 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>22.1 Preliminaries</H2>
<a name="n2"></a><H2>23.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>22.1.1 Running SWIG</H3>
<a name="n3"></a><H3>23.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>22.1.2 Getting the right header files</H3>
<a name="n4"></a><H3>23.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>22.1.3 Compiling a dynamic module</H3>
<a name="n5"></a><H3>23.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>22.1.4 Using your module</H3>
<a name="n6"></a><H3>23.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>22.1.5 Static linking</H3>
<a name="n7"></a><H3>23.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>22.1.6 Compilation of C++ extensions</H3>
<a name="n8"></a><H3>23.1.6 Compilation of C++ extensions</H3>
<p>
@ -279,7 +279,7 @@ create_makefile('example')
</blockquote>
<hr>
<a name="n9"></a><H2>22.2 Building Ruby Extensions under Windows 95/NT</H2>
<a name="n9"></a><H2>23.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>22.2.1 Running SWIG from Developer Studio</H3>
<a name="n10"></a><H3>23.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>22.3 The Ruby-to-C/C++ Mapping</H2>
<a name="n11"></a><H2>23.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>22.3.1 Modules</H3>
<a name="n12"></a><H3>23.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>22.3.2 Functions</H3>
<a name="n13"></a><H3>23.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>22.3.3 Variable Linking</H3>
<a name="n14"></a><H3>23.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>22.3.4 Constants</H3>
<a name="n15"></a><H3>23.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>22.3.5 Pointers</H3>
<a name="n16"></a><H3>23.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>22.3.6 Structures</H3>
<a name="n17"></a><H3>23.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>22.3.7 C++ classes</H3>
<a name="n18"></a><H3>23.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>22.3.8 C++ Inheritance</H3>
<a name="n19"></a><H3>23.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>22.3.9 C++ Overloaded Functions</H3>
<a name="n20"></a><H3>23.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>22.3.10 C++ Operators</H3>
<a name="n21"></a><H3>23.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>22.3.11 C++ namespaces</H3>
<a name="n22"></a><H3>23.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>22.3.12 C++ templates</H3>
<a name="n23"></a><H3>23.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>22.3.13 C++ Smart Pointers</H3>
<a name="n24"></a><H3>23.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>22.3.14 Cross-Language Polymorphism</H3>
<a name="n25"></a><H3>23.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>22.3.14.1 Exception Unrolling</H4>
<a name="n26"></a><H4>23.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>22.4 Input and output parameters</H2>
<a name="n27"></a><H2>23.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>22.5 Simple exception handling </H2>
<a name="n28"></a><H2>23.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>22.6 Typemaps</H2>
<a name="n29"></a><H2>23.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>22.6.1 What is a typemap?</H3>
<a name="n30"></a><H3>23.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>22.6.2 Ruby typemaps</H3>
<a name="n31"></a><H3>23.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>22.6.3 Typemap variables</H3>
<a name="n32"></a><H3>23.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>22.6.4 Useful Functions</H3>
<a name="n33"></a><H3>23.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>22.6.4.1 C Datatypes to Ruby Objects</H4>
<a name="n34"></a><H4>23.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>22.6.4.2 Ruby Objects to C Datatypes</H4>
<a name="n35"></a><H4>23.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>22.6.4.3 Macros for VALUE</H4>
<a name="n36"></a><H4>23.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>22.6.4.4 Exceptions</H4>
<a name="n37"></a><H4>23.6.4.4 Exceptions</H4>
<p>
@ -1917,7 +1917,7 @@ unsigned long FIX2ULONG(Numeric)
</pre>
</blockquote>
<a name="n38"></a><H4>22.6.4.5 Iterators</H4>
<a name="n38"></a><H4>23.6.4.5 Iterators</H4>
<p>
@ -1964,13 +1964,13 @@ unsigned long FIX2ULONG(Numeric)
<a name="n39"></a><H3>22.6.5 Typemap Examples</H3>
<a name="n39"></a><H3>23.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>22.6.6 Converting a Ruby array to a char **</H3>
<a name="n40"></a><H3>23.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>22.6.7 Collecting arguments in a hash</H3>
<a name="n41"></a><H3>23.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>22.6.8 Pointer handling</H3>
<a name="n42"></a><H3>23.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>22.6.8.1 Ruby Datatype Wrapping</H4>
<a name="n43"></a><H4>23.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>22.7 Operator overloading</H2>
<a name="n44"></a><H2>23.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>22.7.1 Example: STL Vector to Ruby Array</H3>
<a name="n45"></a><H3>23.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>22.8 Advanced Topics</H2>
<a name="n46"></a><H2>23.8 Advanced Topics</H2>
<a name="n47"></a><H3>22.8.1 Creating Multi-Module Packages</H3>
<a name="n47"></a><H3>23.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>22.8.2 Defining Aliases</H3>
<a name="n48"></a><H3>23.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>22.8.3 Predicate Methods</H3>
<a name="n49"></a><H3>23.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>22.8.4 Specifying Mixin Modules</H3>
<a name="n50"></a><H3>23.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>22.8.5 Interacting with Ruby's Garbage Collector</H3>
<a name="n51"></a><H3>23.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

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

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

@ -3723,4 +3723,4 @@ is the reference document we use to guide a lot of SWIG's C++ support.
<address>SWIG 1.3 - Last Modified : April 3, 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>23 SWIG and Tcl</H1>
<a name="n1"></a><H1>24 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>23.1 Preliminaries</H2>
<a name="n2"></a><H2>24.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>23.1.1 Getting the right header files</H3>
<a name="n3"></a><H3>24.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>23.1.2 Compiling a dynamic module</H3>
<a name="n4"></a><H3>24.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>23.1.3 Static linking</H3>
<a name="n5"></a><H3>24.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>23.1.4 Using your module</H3>
<a name="n6"></a><H3>24.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>23.1.5 Compilation of C++ extensions</H3>
<a name="n7"></a><H3>24.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>23.1.6 Compiling for 64-bit platforms</H3>
<a name="n8"></a><H3>24.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>23.1.7 Setting a package prefix</H3>
<a name="n9"></a><H3>24.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>23.1.8 Using namespaces</H3>
<a name="n10"></a><H3>24.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>23.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<a name="n11"></a><H2>24.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>23.2.1 Running SWIG from Developer Studio</H3>
<a name="n12"></a><H3>24.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>23.2.2 Using NMAKE</H3>
<a name="n13"></a><H3>24.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>23.3 A tour of basic C/C++ wrapping</H2>
<a name="n14"></a><H2>24.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>23.3.1 Modules</H3>
<a name="n15"></a><H3>24.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>23.3.2 Functions</H3>
<a name="n16"></a><H3>24.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>23.3.3 Global variables</H3>
<a name="n17"></a><H3>24.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>23.3.4 Constants and enums</H3>
<a name="n18"></a><H3>24.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>23.3.5 Pointers</H3>
<a name="n19"></a><H3>24.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>23.3.6 Structures</H3>
<a name="n20"></a><H3>24.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>23.3.7 C++ classes</H3>
<a name="n21"></a><H3>24.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>23.3.8 C++ inheritance</H3>
<a name="n22"></a><H3>24.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>23.3.9 Pointers, references, values, and arrays</H3>
<a name="n23"></a><H3>24.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>23.3.10 C++ overloaded functions</H3>
<a name="n24"></a><H3>24.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>23.3.11 C++ operators</H3>
<a name="n25"></a><H3>24.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>23.3.12 C++ namespaces</H3>
<a name="n26"></a><H3>24.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>23.3.13 C++ templates</H3>
<a name="n27"></a><H3>24.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>23.3.14 C++ Smart Pointers</H3>
<a name="n28"></a><H3>24.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>23.4 Further details on the Tcl class interface</H2>
<a name="n29"></a><H2>24.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>23.4.1 Proxy classes</H3>
<a name="n30"></a><H3>24.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>23.4.2 Memory management</H3>
<a name="n31"></a><H3>24.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>23.5 Input and output parameters</H2>
<a name="n32"></a><H2>24.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>23.6 Exception handling </H2>
<a name="n33"></a><H2>24.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>23.7 Typemaps</H2>
<a name="n34"></a><H2>24.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>23.7.1 What is a typemap?</H3>
<a name="n35"></a><H3>24.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>23.7.2 Tcl typemaps</H3>
<a name="n36"></a><H3>24.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>23.7.3 Typemap variables</H3>
<a name="n37"></a><H3>24.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>23.7.4 Converting a Tcl list to a char ** </H3>
<a name="n38"></a><H3>24.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>23.7.5 Returning values in arguments</H3>
<a name="n39"></a><H3>24.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>23.7.6 Useful functions</H3>
<a name="n40"></a><H3>24.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>23.7.7 Standard typemaps</H3>
<a name="n41"></a><H3>24.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>23.7.8 Pointer handling</H3>
<a name="n42"></a><H3>24.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>23.8 Turning a SWIG module into a Tcl Package.</H2>
<a name="n43"></a><H2>24.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>23.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<a name="n44"></a><H2>24.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>23.9.1 Shadow classes</H3>
<a name="n45"></a><H3>24.9.1 Shadow classes</H3>
A similar approach can be applied to shadow classes. The following

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

@ -438,4 +438,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>

36
SWIG/Doc/Manual/Windows.html
View file

@ -22,19 +22,19 @@
<li><a href="#n9">Perl</a>
<li><a href="#n10">Java</a>
<li><a href="#n11">Ruby</a>
<li><a href="#n110">C#</a>
<li><a href="#n12">C#</a>
</ul>
<li><a href="#n12">Instructions for using the Examples with other compilers</a>
<li><a href="#n13">Instructions for using the Examples with other compilers</a>
</ul>
<li><a href="#n13">SWIG on Cygwin and MinGW</a>
<li><a href="#n14">SWIG on Cygwin and MinGW</a>
<ul>
<li><a href="#n14">Building swig.exe on Windows</a>
<li><a href="#n15">Building swig.exe on Windows</a>
<ul>
<li><a href="#n15">Building swig.exe using MinGW and MSYS</a>
<li><a href="#n16">Building swig.exe using Cygwin</a>
<li><a href="#n17">Building swig.exe alternatives</a>
<li><a href="#n16">Building swig.exe using MinGW and MSYS</a>
<li><a href="#n17">Building swig.exe using Cygwin</a>
<li><a href="#n18">Building swig.exe alternatives</a>
</ul>
<li><a href="#n18">Running the examples on Windows using Cygwin</a>
<li><a href="#n19">Running the examples on Windows using Cygwin</a>
</ul>
</ul>
<!-- INDEX -->
@ -169,23 +169,25 @@ RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32<br>
RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib<br>
</tt>
<a name="n110"></a><H4>2.2.1.6 C#</H4>
<a name="n12"></a><H4>2.2.1.6 C#</H4>
The C# examples do not require any environment variables to be set as a C# project file is included.
Just open up the .sln solution file in Visual Studio .NET 2003 and do a Rebuild All from the Build menu.
The accompanying C# and C++ project file are automatically used by the solution file.
<a name="n12"></a><H3>2.2.2 Instructions for using the Examples with other compilers</H3>
<a name="n13"></a><H3>2.2.2 Instructions for using the Examples with other compilers</H3>
If you do not have access to Visual C++ you will have to set up project files / Makefiles for your chosen compiler. There is a section in each of the language modules detailing what needs setting up using Visual C++ which may be of some guidance. Alternatively you may want to use Cygwin as described in the following section.
<a name="n13"></a><H2>2.3 SWIG on Cygwin and MinGW</H2>
<a name="n14"></a><H2>2.3 SWIG on Cygwin and MinGW</H2>
SWIG can also be compiled and run using <a href="http://www.cygwin.com">Cygwin</a> or <a href=http://www.mingw.org>MinGW</a> which provides a Unix like front end to Windows and comes free with gcc, an ANSI C/C++ compiler. However, this is not a recommended approach as the prebuilt executable is supplied.
<a name="swig_exe"></a>
<a name="n14"></a><H3>2.3.1 Building swig.exe on Windows</H3>
<a name="n15"></a><H3>2.3.1 Building swig.exe on Windows</H3>
If you want to replicate the build of swig.exe that comes with the download, follow the MinGW instructions below.
@ -193,7 +195,7 @@ This is not necessary to use the supplied swig.exe.
This information is provided for those that want to modify the SWIG source code in a Windows environment.
Normally this is not needed, so most people will want to ignore this section.
<a name="n15"></a><H4>2.3.1.1 Building swig.exe using MinGW and MSYS</H4>
<a name="n16"></a><H4>2.3.1.1 Building swig.exe using MinGW and MSYS</H4>
<ul>
@ -202,7 +204,7 @@ Normally this is not needed, so most people will want to ignore this section.
</ul>
<a name="n16"></a><H4>2.3.1.2 Building swig.exe using Cygwin</H4>
<a name="n17"></a><H4>2.3.1.2 Building swig.exe using Cygwin</H4>
Note that SWIG can also be built using Cygwin.
@ -213,7 +215,7 @@ Note that the Cygwin environment will also allow one to regenerate the autotool
These files are generated using the <tt>autogen.sh</tt> script and will only need regenerating in circumstances such as changing the build system.
<p>
<a name="n17"></a><H4>2.3.1.3 Building swig.exe alternatives</H4>
<a name="n18"></a><H4>2.3.1.3 Building swig.exe alternatives</H4>
If you don't want to install Cygwin or MinGW, use a different compiler to build
@ -222,7 +224,7 @@ file in order to build swig.exe from the Visual C++ IDE.
<a name="examples_cygwin"></a>
<a name="n18"></a><H3>2.3.2 Running the examples on Windows using Cygwin</H3>
<a name="n19"></a><H3>2.3.2 Running the examples on Windows using Cygwin</H3>
The examples and test-suite work as successfully on Cygwin as on any other Unix operating system.
@ -232,4 +234,4 @@ Follow the Unix instructions in the README file in the SWIG root directory to bu
<p>
</body>
</html>
</html>

1
SWIG/Doc/Manual/chapters
View file

@ -16,6 +16,7 @@ Modules.html
Advanced.html
Guile.html
Java.html
Modula3.html
Ocaml.html
Perl5.html
Php.html