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

Update after running html tools in makefile

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6139 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2004-08-24 22:21:18 +00:00
commit 229d40e0ee
11 changed files with 339 additions and 331 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -7,7 +7,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Advanced"></a>29 Advanced Topics</H1>
<H1><a name="Advanced"></a>30 Advanced Topics</H1>
<!-- INDEX -->
<ul>
<li><a href="#Advanced_nn2">Creating multi-module packages</a>
@ -32,7 +32,7 @@
<b>Caution: This chapter is under repair!</b>
<H2><a name="Advanced_nn2"></a>29.1 Creating multi-module packages</H2>
<H2><a name="Advanced_nn2"></a>30.1 Creating multi-module packages</H2>
<p>
@ -43,7 +43,7 @@ SWIG can be used to create packages consisting of many different modules. Howeve
This chapter doesn't apply to those languages that use static type checking, rather than runtime type checking, such as Java and C#.
</p>
<H3><a name="Advanced_nn3"></a>29.1.1 Runtime support (and potential problems)</H3>
<H3><a name="Advanced_nn3"></a>30.1.1 Runtime support (and potential problems)</H3>
<p>
@ -59,7 +59,7 @@ If you create a system consisting of many modules, each one will have an identic
This duplication of runtime libraries is usually harmless since there are no namespace conflicts and memory overhead is minimal. However, there is serious problem related to the fact that modules do not share type-information. This is particularly a problem when working with C++ (as described next).
</p>
<H3><a name="Advanced_nn4"></a>29.1.2 Why doesn't C++ inheritance work between modules?</H3>
<H3><a name="Advanced_nn4"></a>30.1.2 Why doesn't C++ inheritance work between modules?</H3>
<p>
@ -127,7 +127,7 @@ The type information listed shows the acceptable values for various C datatypes.
Unfortunately, this problem is inherent in the method by which SWIG makes modules. When we made the "a" module, we had no idea what derived classes might be used at a later time. However, it's impossible to produce the proper type information until after we know all of the derived classes. A nice problem to be sure, but one that can be fixed by making all modules share a single copy of the SWIG run-time library.
</p>
<H3><a name="Advanced_nn5"></a>29.1.3 The SWIG runtime library</H3>
<H3><a name="Advanced_nn5"></a>30.1.3 The SWIG runtime library</H3>
To reduce overhead and to fix type-handling problems, it is possible to share the SWIG run-time functions between multiple modules.
@ -153,7 +153,7 @@ In this configuration, the runtime library manages all datatypes and other infor
<b>Compatibility Note:</b> In SWIG-1.3.19 and earlier releases, SWIG built the runtime libraries by default and attempted to install them with the SWIG installation. This had numerous limitations, not least, the version of the target language was tied to what was detected at installation time and would not necessarily be the version the user required.
</p>
<H3><a name="Advanced_nn6"></a>29.1.4 A few dynamic loading gotchas</H3>
<H3><a name="Advanced_nn6"></a>30.1.4 A few dynamic loading gotchas</H3>
<p>
@ -261,7 +261,7 @@ The <tt>-rpath</tt> option encodes the location of shared libraries into your mo
If all else fails, pull up the man pages for your linker and start playing around.
</p>
<H2><a name="Advanced_nn7"></a>29.2 Dynamic Loading of C++ modules</H2>
<H2><a name="Advanced_nn7"></a>30.2 Dynamic Loading of C++ modules</H2>
<p>
@ -284,14 +284,14 @@ While the process of building C++ modules is, by no means, and exact science, he
The SWIG distribution contains some additional documentation about C++ modules in the Doc directory as well.
</p>
<H2><a name="Advanced_nn8"></a>29.3 Inside the SWIG type-checker</H2>
<H2><a name="Advanced_nn8"></a>30.3 Inside the SWIG type-checker</H2>
<p>
The SWIG runtime type-checker plays a critical role in the correct operation of SWIG modules. It not only checks the validity of pointer types, but also manages C++ inheritance, and performs proper type-casting of pointers when necessary. This section provides some insight into what it does, how it works, and why it is the way it is.
</p>
<H3><a name="Advanced_nn9"></a>29.3.1 Type equivalence</H3>
<H3><a name="Advanced_nn9"></a>30.3.1 Type equivalence</H3>
<p>
@ -394,7 +394,7 @@ E =&gt; { }
The encoding reflects the class hierarchy. For example, any object of type "A" will also accept objects of type B,C, and E because these are all derived from A. However, it is not legal to go the other way. For example, a function operating on a object from class E will not accept an object from class A.
</p>
<H3><a name="Advanced_nn10"></a>29.3.2 Type casting</H3>
<H3><a name="Advanced_nn10"></a>30.3.2 Type casting</H3>
<p>
@ -414,7 +414,7 @@ void *EtoA(void *ptr) {
All pointers are internally represented as void *, but conversion functions are always invoked when pointer values are converted between base and derived classes in a C++ class hierarchy.
</p>
<H3><a name="Advanced_nn11"></a>29.3.3 Why a name based approach?</H3>
<H3><a name="Advanced_nn11"></a>30.3.3 Why a name based approach?</H3>
<p>
@ -431,7 +431,7 @@ SWIG uses a name-based approach to type-checking for a number of reasons :
An alternative to a name based scheme would be to generate type-signatures based on the structure of a datatype. Such a scheme would result in perfect type-checking, but I think it would also result in a very confusing scripting language module. For this reason, I see SWIG sticking with the name-based approach--at least for the foreseeable future.
</p>
<H3><a name="Advanced_nn12"></a>29.3.4 Performance of the type-checker</H3>
<H3><a name="Advanced_nn12"></a>30.3.4 Performance of the type-checker</H3>
<p>

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

@ -667,7 +667,15 @@
</ul>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">21 SWIG and Ocaml</a></h3>
<h3><a href="Mzscheme.html#Mzscheme">21 SWIG and MzScheme</a></h3>
<!-- INDEX -->
<ul>
<li><a href="Mzscheme.html#MzScheme_nn2">Creating native MzScheme structures</a>
</ul>
<!-- INDEX -->
<h3><a href="Ocaml.html#Ocaml">22 SWIG and Ocaml</a></h3>
<!-- INDEX -->
<ul>
@ -713,7 +721,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Perl5.html#Perl5">22 SWIG and Perl5</a></h3>
<h3><a href="Perl5.html#Perl5">23 SWIG and Perl5</a></h3>
<!-- INDEX -->
<ul>
@ -776,7 +784,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Php.html#Php">23 SWIG and PHP4</a></h3>
<h3><a href="Php.html#Php">24 SWIG and PHP4</a></h3>
<!-- INDEX -->
<ul>
@ -800,7 +808,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Pike.html#Pike">24 SWIG and Pike</a></h3>
<h3><a href="Pike.html#Pike">25 SWIG and Pike</a></h3>
<!-- INDEX -->
<ul>
@ -822,7 +830,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Python.html#Python">25 SWIG and Python</a></h3>
<h3><a href="Python.html#Python">26 SWIG and Python</a></h3>
<!-- INDEX -->
<ul>
@ -908,7 +916,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Ruby.html#Ruby">26 SWIG and Ruby</a></h3>
<h3><a href="Ruby.html#Ruby">27 SWIG and Ruby</a></h3>
<!-- INDEX -->
<ul>
@ -983,7 +991,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Tcl.html#Tcl">27 SWIG and Tcl</a></h3>
<h3><a href="Tcl.html#Tcl">28 SWIG and Tcl</a></h3>
<!-- INDEX -->
<ul>
@ -1046,7 +1054,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Extending.html#Extending">28 Extending SWIG</a></h3>
<h3><a href="Extending.html#Extending">29 Extending SWIG</a></h3>
<!-- INDEX -->
<ul>
@ -1108,7 +1116,7 @@
</ul>
<!-- INDEX -->
<h3><a href="Advanced.html#Advanced">29 Advanced Topics</a></h3>
<h3><a href="Advanced.html#Advanced">30 Advanced Topics</a></h3>
<!-- INDEX -->
<ul>

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Extending"></a>28 Extending SWIG</H1>
<H1><a name="Extending"></a>29 Extending SWIG</H1>
<!-- INDEX -->
<ul>
<li><a href="#Extending_nn2">Introduction</a>
@ -70,7 +70,7 @@
<b>Caution: This chapter is being rewritten! (11/25/01)</b>
<H2><a name="Extending_nn2"></a>28.1 Introduction</H2>
<H2><a name="Extending_nn2"></a>29.1 Introduction</H2>
<p>
@ -86,7 +86,7 @@ Also, this chapter is not meant to be a hand-holding tutorial. As a starting po
you should probably look at one of SWIG's existing modules.
</p>
<H2><a name="Extending_nn3"></a>28.2 Prerequisites</H2>
<H2><a name="Extending_nn3"></a>29.2 Prerequisites</H2>
<p>
@ -116,7 +116,7 @@ obvious, but almost all SWIG directives as well as the low-level generation of
wrapper code are driven by C++ datatypes.
</p>
<H2><a name="Extending_nn4"></a>28.3 The Big Picture</H2>
<H2><a name="Extending_nn4"></a>29.3 The Big Picture</H2>
SWIG is a special purpose compiler that parses C++ declarations to
@ -151,7 +151,7 @@ role in making the system work. For example, both typemaps and declaration anno
based on pattern matching and interact heavily with the underlying type system.
</p>
<H2><a name="Extending_nn5"></a>28.4 Execution Model</H2>
<H2><a name="Extending_nn5"></a>29.4 Execution Model</H2>
When you run SWIG on an interface, processing is handled in stages by a series of system components:
@ -194,7 +194,7 @@ stage of compilation.
The next few sections briefly describe some of these stages.
</p>
<H3><a name="Extending_nn6"></a>28.4.1 Preprocessing</H3>
<H3><a name="Extending_nn6"></a>29.4.1 Preprocessing</H3>
The preprocessor plays a critical role in the SWIG implementation. This is because a lot
@ -270,7 +270,7 @@ been expanded as well as everything else that goes into the low-level
construction of the wrapper code.
</p>
<H3><a name="Extending_nn7"></a>28.4.2 Parsing</H3>
<H3><a name="Extending_nn7"></a>29.4.2 Parsing</H3>
<p>
@ -368,7 +368,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).
<H3><a name="Extending_nn8"></a>28.4.3 Parse Trees</H3>
<H3><a name="Extending_nn8"></a>29.4.3 Parse Trees</H3>
The SWIG parser produces a complete parse tree of the input file before any wrapper code
@ -618,7 +618,7 @@ $ swig -c++ -python -dump_tree example.i
</pre>
</blockquote>
<H3><a name="Extending_nn9"></a>28.4.4 Attribute namespaces</H3>
<H3><a name="Extending_nn9"></a>29.4.4 Attribute namespaces</H3>
<p>
@ -637,7 +637,7 @@ that matches the name of the target language. For example, <tt>python:foo</tt>
<tt>perl:foo</tt>.
</p>
<H3><a name="Extending_nn10"></a>28.4.5 Symbol Tables</H3>
<H3><a name="Extending_nn10"></a>29.4.5 Symbol Tables</H3>
During parsing, all symbols are managed in the space of the target
@ -717,7 +717,7 @@ example.i:5. Previous declaration is foo_i(int )
</pre>
</blockquote>
<H3><a name="Extending_nn11"></a>28.4.6 The %feature directive</H3>
<H3><a name="Extending_nn11"></a>29.4.6 The %feature directive</H3>
A number of SWIG directives such as <tt>%exception</tt> are implemented using the
@ -767,7 +767,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.
<H3><a name="Extending_nn12"></a>28.4.7 Code Generation</H3>
<H3><a name="Extending_nn12"></a>29.4.7 Code Generation</H3>
<p>
@ -883,7 +883,7 @@ public :
The role of these functions is described shortly.
<H3><a name="Extending_nn13"></a>28.4.8 SWIG and XML</H3>
<H3><a name="Extending_nn13"></a>29.4.8 SWIG and XML</H3>
Much of SWIG's current parser design was originally motivated by
@ -894,7 +894,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.
<H2><a name="Extending_nn14"></a>28.5 Primitive Data Structures</H2>
<H2><a name="Extending_nn14"></a>29.5 Primitive Data Structures</H2>
<p>
@ -938,7 +938,7 @@ typedef Hash Typetab;
</pre>
</blockquote>
<H3><a name="Extending_nn15"></a>28.5.1 Strings</H3>
<H3><a name="Extending_nn15"></a>29.5.1 Strings</H3>
<p>
@ -1077,7 +1077,7 @@ Returns the number of replacements made (if any).
</blockquote>
<H3><a name="Extending_nn16"></a>28.5.2 Hashes</H3>
<H3><a name="Extending_nn16"></a>29.5.2 Hashes</H3>
<p>
@ -1154,7 +1154,7 @@ Returns the list of hash table keys.
</blockquote>
<H3><a name="Extending_nn17"></a>28.5.3 Lists</H3>
<H3><a name="Extending_nn17"></a>29.5.3 Lists</H3>
<p>
@ -1243,7 +1243,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>
<H3><a name="Extending_nn18"></a>28.5.4 Common operations</H3>
<H3><a name="Extending_nn18"></a>29.5.4 Common operations</H3>
The following operations are applicable to all datatypes.
@ -1298,7 +1298,7 @@ objects and report errors.
Gets the line number associated with <tt>x</tt>.
</blockquote>
<H3><a name="Extending_nn19"></a>28.5.5 Iterating over Lists and Hashes</H3>
<H3><a name="Extending_nn19"></a>29.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:
@ -1342,7 +1342,7 @@ for (j = First(j); j.item; j= Next(j)) {
</pre>
</blockquote>
<H3><a name="Extending_nn20"></a>28.5.6 I/O</H3>
<H3><a name="Extending_nn20"></a>29.5.6 I/O</H3>
Special I/O functions are used for all internal I/O. These operations
@ -1473,7 +1473,7 @@ Printf(f, "%s\n", s);
Similarly, the preprocessor and parser all operate on string-files.
<H2><a name="Extending_nn21"></a>28.6 Navigating and manipulating parse trees</H2>
<H2><a name="Extending_nn21"></a>29.6 Navigating and manipulating parse trees</H2>
Parse trees are built as collections of hash tables. Each node is a hash table in which
@ -1603,7 +1603,7 @@ Deletes a node from the parse tree. Deletion reconnects siblings and properly u
the parent so that sibling nodes are unaffected.
</blockquote>
<H2><a name="Extending_nn22"></a>28.7 Working with attributes</H2>
<H2><a name="Extending_nn22"></a>29.7 Working with attributes</H2>
Since parse tree nodes are just hash tables, attributes are accessed using the <tt>Getattr()</tt>,
@ -1710,14 +1710,14 @@ the attribute is optional. <tt>Swig_restore()</tt> must always be called after
function.
</blockquote>
<H2><a name="Extending_nn23"></a>28.8 Type system</H2>
<H2><a name="Extending_nn23"></a>29.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.
<H3><a name="Extending_nn24"></a>28.8.1 String encoding of types</H3>
<H3><a name="Extending_nn24"></a>29.8.1 String encoding of types</H3>
<p>
@ -1810,7 +1810,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.
<H3><a name="Extending_nn25"></a>28.8.2 Type construction</H3>
<H3><a name="Extending_nn25"></a>29.8.2 Type construction</H3>
The following functions are used to construct types. You should use
@ -1945,7 +1945,7 @@ Returns the prefix of a type. For example, if <tt>ty</tt> is
<tt>ty</tt> is unmodified.
</blockquote>
<H3><a name="Extending_nn26"></a>28.8.3 Type tests</H3>
<H3><a name="Extending_nn26"></a>29.8.3 Type tests</H3>
The following functions can be used to test properties of a datatype.
@ -2030,7 +2030,7 @@ Checks if <tt>ty</tt> is a varargs type.
Checks if <tt>ty</tt> is a templatized type.
</blockquote>
<H3><a name="Extending_nn27"></a>28.8.4 Typedef and inheritance</H3>
<H3><a name="Extending_nn27"></a>29.8.4 Typedef and inheritance</H3>
The behavior of <tt>typedef</tt> declaration is to introduce a type alias.
@ -2122,7 +2122,7 @@ Fully reduces <tt>ty</tt> according to typedef rules. Resulting datatype
will consist only of primitive typenames.
</blockquote>
<H3><a name="Extending_nn28"></a>28.8.5 Lvalues</H3>
<H3><a name="Extending_nn28"></a>29.8.5 Lvalues</H3>
When generating wrapper code, it is necessary to emit datatypes that can
@ -2155,7 +2155,7 @@ Literal y; // type = 'Literal', ltype='p.char'
</pre>
</blockquote>
<H3><a name="Extending_nn29"></a>28.8.6 Output functions</H3>
<H3><a name="Extending_nn29"></a>29.8.6 Output functions</H3>
The following functions produce strings that are suitable for output.
@ -2215,7 +2215,7 @@ SWIG, but is most commonly associated with type-descriptor objects
that appear in wrappers (e.g., <tt>SWIGTYPE_p_double</tt>).
</blockquote>
<H2><a name="Extending_nn30"></a>28.9 Parameters</H2>
<H2><a name="Extending_nn30"></a>29.9 Parameters</H2>
Several type-related functions involve parameter lists. These include
@ -2310,7 +2310,7 @@ included. Used to emit prototypes.
Returns the number of required (non-optional) arguments in <tt>p</tt>.
</blockquote>
<H2><a name="Extending_nn31"></a>28.10 Writing a Language Module</H2>
<H2><a name="Extending_nn31"></a>29.10 Writing a Language Module</H2>
This section briefly outlines the steps needed to create a bare-bones
@ -2319,7 +2319,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.
<H3><a name="Extending_nn32"></a>28.10.1 Execution model</H3>
<H3><a name="Extending_nn32"></a>29.10.1 Execution model</H3>
Code generation modules are defined by inheriting from the <tt>Language</tt> class,
@ -2327,7 +2327,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.
<H3><a name="Extending_nn33"></a>28.10.2 Starting out</H3>
<H3><a name="Extending_nn33"></a>29.10.2 Starting out</H3>
To define a new language module, first create a minimal implementation using
@ -2430,7 +2430,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.
<H3><a name="Extending_nn34"></a>28.10.3 Command line options</H3>
<H3><a name="Extending_nn34"></a>29.10.3 Command line options</H3>
When SWIG starts, the command line options are passed to your language module. This occurs
@ -2487,7 +2487,7 @@ to mark the option as valid. If you forget to do this, SWIG will terminate wit
unrecognized command line option error.
</p>
<H3><a name="Extending_nn35"></a>28.10.4 Configuration and preprocessing</H3>
<H3><a name="Extending_nn35"></a>29.10.4 Configuration and preprocessing</H3>
<p>
@ -2536,7 +2536,7 @@ an implementation file <tt>python.cxx</tt> and a configuration file
<tt>python.swg</tt>.
</p>
<H3><a name="Extending_nn36"></a>28.10.5 Entry point to code generation</H3>
<H3><a name="Extending_nn36"></a>29.10.5 Entry point to code generation</H3>
<p>
@ -2594,13 +2594,13 @@ int Python::top(Node *n) {
</pre>
</blockquote>
<H3><a name="Extending_nn37"></a>28.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn37"></a>29.10.6 Module I/O and wrapper skeleton</H3>
<H3><a name="Extending_nn38"></a>28.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn38"></a>29.10.7 Low-level code generators</H3>
<H3><a name="Extending_nn39"></a>28.10.8 Configuration files</H3>
<H3><a name="Extending_nn39"></a>29.10.8 Configuration files</H3>
<!-- please report bugs in this section to ttn -->
@ -2748,7 +2748,7 @@ 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.
<H3><a name="Extending_nn40"></a>28.10.9 Runtime support</H3>
<H3><a name="Extending_nn40"></a>29.10.9 Runtime support</H3>
<p>
@ -2757,7 +2757,7 @@ Discuss the kinds of functions typically needed for SWIG runtime support (e.g.
the SWIG files that implement those functions.
</p>
<H3><a name="Extending_nn41"></a>28.10.10 Standard library files</H3>
<H3><a name="Extending_nn41"></a>29.10.10 Standard library files</H3>
<p>
@ -2771,7 +2771,7 @@ Discuss the standard library files that most language modules provide, e.g.
<li> stl.i </li>
</ul>
<H3><a name="Extending_nn42"></a>28.10.11 Examples and test cases</H3>
<H3><a name="Extending_nn42"></a>29.10.11 Examples and test cases</H3>
<p>
@ -2798,7 +2798,7 @@ during this process, see the section on <a href="#n37a">configuration
files</a>.
</p>
<H3><a name="Extending_nn43"></a>28.10.12 Documentation</H3>
<H3><a name="Extending_nn43"></a>29.10.12 Documentation</H3>
<p>
@ -2830,13 +2830,13 @@ Some topics that you'll want to be sure to address include:
if available.
</ul>
<H2><a name="Extending_nn44"></a>28.11 Typemaps</H2>
<H2><a name="Extending_nn44"></a>29.11 Typemaps</H2>
<H3><a name="Extending_nn45"></a>28.11.1 Proxy classes</H3>
<H3><a name="Extending_nn45"></a>29.11.1 Proxy classes</H3>
<H2><a name="Extending_nn46"></a>28.12 Guide to parse tree nodes</H2>
<H2><a name="Extending_nn46"></a>29.12 Guide to parse tree nodes</H2>
<p>

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

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<a name="n1"></a>
<H1><a name="Ocaml"></a>21 SWIG and Ocaml</H1>
<H1><a name="Ocaml"></a>22 SWIG and Ocaml</H1>
<!-- INDEX -->
<ul>
<li><a href="#Ocaml_nn2">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>
<H2><a name="Ocaml_nn2"></a>21.1 Preliminaries</H2>
<H2><a name="Ocaml_nn2"></a>22.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.
<H3><a name="Ocaml_nn3"></a>21.1.1 Running SWIG</H3>
<H3><a name="Ocaml_nn3"></a>22.1.1 Running SWIG</H3>
The basics of getting a SWIG Ocaml module up and running
@ -111,7 +111,7 @@ you will compile the file <tt>example_wrap.c</tt> with <tt>ocamlc</tt> or
the resulting .ml and .mli files as well, and do the final link with -custom
(not needed for native link). </p>
<H3><a name="Ocaml_nn4"></a>21.1.2 Compiling the code</H3>
<H3><a name="Ocaml_nn4"></a>22.1.2 Compiling the code</H3>
<p>
@ -147,7 +147,7 @@ the user more freedom with respect to custom typing.
</pre>
</blockquote>
<H3><a name="Ocaml_nn5"></a>21.1.3 The camlp4 module</H3>
<H3><a name="Ocaml_nn5"></a>22.1.3 The camlp4 module</H3>
<p>
@ -223,7 +223,7 @@ let b = C_string (getenv "PATH")
</td></tr>
</table>
<H3><a name="Ocaml_nn6"></a>21.1.4 Using your module</H3>
<H3><a name="Ocaml_nn6"></a>22.1.4 Using your module</H3>
<p>
@ -237,7 +237,7 @@ When linking any ocaml bytecode with your module, use the -custom
option is not needed when you build native code.
</p>
<H3><a name="Ocaml_nn7"></a>21.1.5 Compilation problems and compiling with C++</H3>
<H3><a name="Ocaml_nn7"></a>22.1.5 Compilation problems and compiling with C++</H3>
<p>
@ -248,7 +248,7 @@ liberal with pointer types may not compile under the C++ compiler.
Most code meant to be compiled as C++ will not have problems.
</p>
<H2><a name="Ocaml_nn8"></a>21.2 The low-level Ocaml/C interface</H2>
<H2><a name="Ocaml_nn8"></a>22.2 The low-level Ocaml/C interface</H2>
<p>
@ -346,7 +346,7 @@ is that you must append them to the return list with swig_result = caml_list_a
signature for a function that uses value in this way.
</p>
<H3><a name="Ocaml_nn9"></a>21.2.1 The generated module</H3>
<H3><a name="Ocaml_nn9"></a>22.2.1 The generated module</H3>
<p>
@ -380,7 +380,7 @@ it describes the output SWIG will generate for class definitions.
</td></tr>
</table>
<H3><a name="Ocaml_nn10"></a>21.2.2 Enums</H3>
<H3><a name="Ocaml_nn10"></a>22.2.2 Enums</H3>
<p>
@ -439,10 +439,10 @@ val x : Enum_test.c_obj = C_enum `a
</pre>
</blockquote>
<H3><a name="Ocaml_nn11"></a>21.2.3 Arrays</H3>
<H3><a name="Ocaml_nn11"></a>22.2.3 Arrays</H3>
<H4><a name="Ocaml_nn12"></a>21.2.3.1 Simple types of bounded arrays</H4>
<H4><a name="Ocaml_nn12"></a>22.2.3.1 Simple types of bounded arrays</H4>
<p>
@ -463,7 +463,7 @@ arrays of simple types with known bounds in your code, but this only works
for arrays whose bounds are completely specified.
</p>
<H4><a name="Ocaml_nn13"></a>21.2.3.2 Complex and unbounded arrays</H4>
<H4><a name="Ocaml_nn13"></a>22.2.3.2 Complex and unbounded arrays</H4>
<p>
@ -476,7 +476,7 @@ SWIG can't predict which of these methods will be used in the array,
so you have to specify it for yourself in the form of a typemap.
</p>
<H4><a name="Ocaml_nn14"></a>21.2.3.3 Using an object</H4>
<H4><a name="Ocaml_nn14"></a>22.2.3.3 Using an object</H4>
<p>
@ -490,7 +490,7 @@ Consider writing an object when the ending condition of your array is complex,
such as using a required centinel, etc.
</p>
<H4><a name="Ocaml_nn15"></a>21.2.3.4 Example typemap for a function taking float * and int</H4>
<H4><a name="Ocaml_nn15"></a>22.2.3.4 Example typemap for a function taking float * and int</H4>
<p>
@ -541,7 +541,7 @@ void printfloats( float *tab, int len );
</pre></td></tr></table>
<H3><a name="Ocaml_nn16"></a>21.2.4 C++ Classes</H3>
<H3><a name="Ocaml_nn16"></a>22.2.4 C++ Classes</H3>
C++ classes, along with structs and unions are represented by C_obj
@ -579,7 +579,7 @@ Note that this string belongs to the wrapper object, and not
the underlying pointer, so using create_[x]_from_ptr alters the
returned value for the same object.
<H4><a name="Ocaml_nn17"></a>21.2.4.1 STL vector and string Example</H4>
<H4><a name="Ocaml_nn17"></a>22.2.4.1 STL vector and string Example</H4>
Standard typemaps are now provided for STL vector and string. More are in
@ -657,7 +657,7 @@ baz
#
</pre></blockquote>
<H4><a name="Ocaml_nn18"></a>21.2.4.2 C++ Class Example</H4>
<H4><a name="Ocaml_nn18"></a>22.2.4.2 C++ Class Example</H4>
Here's a simple example using Trolltech's Qt Library:
@ -685,7 +685,7 @@ public:
};
</pre></td></tr></table>
<H4><a name="Ocaml_nn19"></a>21.2.4.3 Compiling the example</H4>
<H4><a name="Ocaml_nn19"></a>22.2.4.3 Compiling the example</H4>
<blockquote><pre>
@ -703,7 +703,7 @@ bash-2.05a$ ocamlmktop -custom swig.cmo -I `camlp4 -where` \
-L$QTPATH/lib -cclib -lqt
</pre></blockquote>
<H4><a name="Ocaml_nn20"></a>21.2.4.4 Sample Session</H4>
<H4><a name="Ocaml_nn20"></a>22.2.4.4 Sample Session</H4>
<blockquote><pre>
@ -730,10 +730,10 @@ Assuming you have a working installation of QT, you will see a window
containing the string "hi" in a button.
</p>
<H3><a name="Ocaml_nn21"></a>21.2.5 Director Classes</H3>
<H3><a name="Ocaml_nn21"></a>22.2.5 Director Classes</H3>
<H4><a name="Ocaml_nn22"></a>21.2.5.1 Director Introduction</H4>
<H4><a name="Ocaml_nn22"></a>22.2.5.1 Director Introduction</H4>
<p>
@ -760,7 +760,7 @@ class foo {
};
</pre></blockquote>
<H4><a name="Ocaml_nn23"></a>21.2.5.2 Overriding Methods in Ocaml</H4>
<H4><a name="Ocaml_nn23"></a>22.2.5.2 Overriding Methods in Ocaml</H4>
<p>
@ -788,7 +788,7 @@ In this example, I'll examine the objective caml code involved in providing
an overloaded class. This example is contained in Examples/ocaml/shapes.
</p>
<H4><a name="Ocaml_nn24"></a>21.2.5.3 Director Usage Example</H4>
<H4><a name="Ocaml_nn24"></a>22.2.5.3 Director Usage Example</H4>
<table border="1" bgcolor="#dddddd" summary="Director usage example">
@ -847,7 +847,7 @@ in a more effortless style in ocaml, while leaving the "engine" part of the
program in C++.
</p>
<H4><a name="Ocaml_nn25"></a>21.2.5.4 Creating director objects</H4>
<H4><a name="Ocaml_nn25"></a>22.2.5.4 Creating director objects</H4>
The definition of the actual object triangle can be described this way:
@ -885,7 +885,7 @@ object from causing a core dump, as long as the object is destroyed
properly.
</p>
<H4><a name="Ocaml_nn26"></a>21.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<H4><a name="Ocaml_nn26"></a>22.2.5.5 Typemaps for directors, <tt>directorin, directorout, directorargout</tt></H4>
<p>
@ -896,7 +896,7 @@ well as a function return value in the same way you provide function arguments,
and to receive arguments the same way you normally receive function returns.
</p>
<H4><a name="Ocaml_nn27"></a>21.2.5.6 <tt>directorin</tt> typemap</H4>
<H4><a name="Ocaml_nn27"></a>22.2.5.6 <tt>directorin</tt> typemap</H4>
<p>
@ -907,7 +907,7 @@ code receives when you are called. In general, a simple <tt>directorin</tt> typ
can use the same body as a simple <tt>out</tt> typemap.
</p>
<H4><a name="Ocaml_nn28"></a>21.2.5.7 <tt>directorout</tt> typemap</H4>
<H4><a name="Ocaml_nn28"></a>22.2.5.7 <tt>directorout</tt> typemap</H4>
<p>
@ -918,7 +918,7 @@ for the same type, except when there are special requirements for object
ownership, etc.
</p>
<H4><a name="Ocaml_nn29"></a>21.2.5.8 <tt>directorargout</tt> typemap</H4>
<H4><a name="Ocaml_nn29"></a>22.2.5.8 <tt>directorargout</tt> typemap</H4>
<p>
@ -935,7 +935,7 @@ In the event that you don't specify all of the necessary values, integral
values will read zero, and struct or object returns have undefined results.
</p>
<H3><a name="Ocaml_nn30"></a>21.2.6 Exceptions</H3>
<H3><a name="Ocaml_nn30"></a>22.2.6 Exceptions</H3>
Catching exceptions is now supported using SWIG's %exception feature. A simple

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Perl5"></a>22 SWIG and Perl5</H1>
<H1><a name="Perl5"></a>23 SWIG and Perl5</H1>
<!-- INDEX -->
<ul>
<li><a href="#Perl5_nn2">Overview</a>
@ -80,7 +80,7 @@ later. Earlier versions are problematic and SWIG generated extensions
may not compile or run correctly.
</p>
<H2><a name="Perl5_nn2"></a>22.1 Overview</H2>
<H2><a name="Perl5_nn2"></a>23.1 Overview</H2>
To build Perl extension modules, SWIG uses a layered approach. At
@ -99,7 +99,7 @@ described. Advanced customization features, typemaps, and other
options are found near the end of the chapter.
</p>
<H2><a name="Perl5_nn3"></a>22.2 Preliminaries</H2>
<H2><a name="Perl5_nn3"></a>23.2 Preliminaries</H2>
<p>
@ -122,7 +122,7 @@ To build the module, you will need to compile the file
<tt>example_wrap.c</tt> and link it with the rest of your program.
</p>
<H3><a name="Perl5_nn4"></a>22.2.1 Getting the right header files</H3>
<H3><a name="Perl5_nn4"></a>23.2.1 Getting the right header files</H3>
<p>
@ -154,7 +154,7 @@ loaded, an easy way to find out is to run Perl itself.
</pre>
</blockquote>
<H3><a name="Perl5_nn5"></a>22.2.2 Compiling a dynamic module</H3>
<H3><a name="Perl5_nn5"></a>23.2.2 Compiling a dynamic module</H3>
The preferred approach to building an extension module is to compile it into
@ -183,7 +183,7 @@ the target should be named `<tt>example.so</tt>',
`<tt>example.sl</tt>', or the appropriate dynamic module name on your system.
</p>
<H3><a name="Perl5_nn6"></a>22.2.3 Building a dynamic module with MakeMaker</H3>
<H3><a name="Perl5_nn6"></a>23.2.3 Building a dynamic module with MakeMaker</H3>
<p>
@ -217,7 +217,7 @@ the preferred approach to compilation. More information about MakeMaker can be
found in "Programming Perl, 2nd ed." by Larry Wall, Tom Christiansen,
and Randal Schwartz.</p>
<H3><a name="Perl5_nn7"></a>22.2.4 Building a static version of Perl</H3>
<H3><a name="Perl5_nn7"></a>23.2.4 Building a static version of Perl</H3>
<p>
@ -284,7 +284,7 @@ added to it. Depending on your machine, you may need to link with
additional libraries such as <tt>-lsocket, -lnsl, -ldl</tt>, etc.
</p>
<H3><a name="Perl5_nn8"></a>22.2.5 Using the module</H3>
<H3><a name="Perl5_nn8"></a>23.2.5 Using the module</H3>
<p>
@ -423,7 +423,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).
<H3><a name="Perl5_nn9"></a>22.2.6 Compilation problems and compiling with C++</H3>
<H3><a name="Perl5_nn9"></a>23.2.6 Compilation problems and compiling with C++</H3>
Compilation of C++ extensions has traditionally been a tricky problem.
@ -553,7 +553,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="http://www.swig.org/mail.html">swig mailing list</a>.
<H3><a name="Perl5_nn10"></a>22.2.7 Compiling for 64-bit platforms</H3>
<H3><a name="Perl5_nn10"></a>23.2.7 Compiling for 64-bit platforms</H3>
On platforms that support 64-bit applications (Solaris, Irix, etc.),
@ -578,7 +578,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H2><a name="Perl5_nn11"></a>22.3 Building Perl Extensions under Windows</H2>
<H2><a name="Perl5_nn11"></a>23.3 Building Perl Extensions under Windows</H2>
Building a SWIG extension to Perl under Windows is roughly
@ -587,7 +587,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.
<H3><a name="Perl5_nn12"></a>22.3.1 Running SWIG from Developer Studio</H3>
<H3><a name="Perl5_nn12"></a>23.3.1 Running SWIG from Developer Studio</H3>
<p>
@ -650,13 +650,13 @@ print "$a\n";
</pre></blockquote>
<H3><a name="Perl5_nn13"></a>22.3.2 Using other compilers</H3>
<H3><a name="Perl5_nn13"></a>23.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">Windows</a> chapter.
<H2><a name="Perl5_nn14"></a>22.4 The low-level interface</H2>
<H2><a name="Perl5_nn14"></a>23.4 The low-level interface</H2>
At its core, the Perl module uses a simple low-level interface
@ -664,7 +664,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.
<H3><a name="Perl5_nn15"></a>22.4.1 Functions</H3>
<H3><a name="Perl5_nn15"></a>23.4.1 Functions</H3>
<p>
@ -687,7 +687,7 @@ use example;
$a = &amp;example::fact(2);
</pre></blockquote>
<H3><a name="Perl5_nn16"></a>22.4.2 Global variables</H3>
<H3><a name="Perl5_nn16"></a>23.4.2 Global variables</H3>
<p>
@ -744,7 +744,7 @@ extern char *path; // Declared later in the input
</pre>
</blockquote>
<H3><a name="Perl5_nn17"></a>22.4.3 Constants</H3>
<H3><a name="Perl5_nn17"></a>23.4.3 Constants</H3>
Constants are wrapped as read-only Perl variables. For example:
@ -767,7 +767,7 @@ $example::FOO = 2; # Error
</pre>
</blockquote>
<H3><a name="Perl5_nn18"></a>22.4.4 Pointers</H3>
<H3><a name="Perl5_nn18"></a>23.4.4 Pointers</H3>
<p>
@ -872,7 +872,7 @@ as XS and <tt>xsubpp</tt>. Given the advancement of the SWIG typesystem and the
SWIG and XS, this is no longer supported.
</p>
<H3><a name="Perl5_nn19"></a>22.4.5 Structures</H3>
<H3><a name="Perl5_nn19"></a>23.4.5 Structures</H3>
<p>
@ -1000,7 +1000,7 @@ void Bar_f_set(Bar *b, Foo *val) {
</blockquote>
<H3><a name="Perl5_nn20"></a>22.4.6 C++ classes</H3>
<H3><a name="Perl5_nn20"></a>23.4.6 C++ classes</H3>
<p>
@ -1061,7 +1061,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.
<H3><a name="Perl5_nn21"></a>22.4.7 C++ classes and type-checking</H3>
<H3><a name="Perl5_nn21"></a>23.4.7 C++ classes and type-checking</H3>
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if you have
@ -1091,7 +1091,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).
<H3><a name="Perl5_nn22"></a>22.4.8 C++ overloaded functions</H3>
<H3><a name="Perl5_nn22"></a>23.4.8 C++ overloaded functions</H3>
If you have a C++ program with overloaded functions or methods, you will need to disambiguate
@ -1129,7 +1129,7 @@ example::Spam_foo_d($s,3.14);
Please refer to the "SWIG Basics" chapter for more information.
<H3><a name="Perl5_nn23"></a>22.4.9 Operators</H3>
<H3><a name="Perl5_nn23"></a>23.4.9 Operators</H3>
C++ operators can also be wrapped using the <tt>%rename</tt> directive. All you need to do is
@ -1156,7 +1156,7 @@ $c = example::add_complex($a,$b);
Some preliminary work on mapping C++ operators into Perl operators has been completed. This is covered later.
<H3><a name="Perl5_nn24"></a>22.4.10 Modules and packages</H3>
<H3><a name="Perl5_nn24"></a>23.4.10 Modules and packages</H3>
<p>
@ -1223,7 +1223,7 @@ print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></blockquote>
-->
<H2><a name="Perl5_nn25"></a>22.5 Input and output parameters</H2>
<H2><a name="Perl5_nn25"></a>23.5 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -1414,7 +1414,7 @@ print "$c\n";
<b>Note:</b> The <tt>REFERENCE</tt> feature is only currently supported for numeric types (integers and floating point).
<H2><a name="Perl5_nn26"></a>22.6 Exception handling </H2>
<H2><a name="Perl5_nn26"></a>23.6 Exception handling </H2>
<p>
@ -1573,7 +1573,7 @@ See the chapter on "<a href="Customization.html#Customization">Customization fea
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.
<H2><a name="Perl5_nn27"></a>22.7 Remapping datatypes with typemaps</H2>
<H2><a name="Perl5_nn27"></a>23.7 Remapping datatypes with typemaps</H2>
<p>
@ -1590,7 +1590,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Perl interface.
</p>
<H3><a name="Perl5_nn28"></a>22.7.1 A simple typemap example</H3>
<H3><a name="Perl5_nn28"></a>23.7.1 A simple typemap example</H3>
<p>
@ -1686,7 +1686,7 @@ example::count("e","Hello World");
</blockquote>
<H3><a name="Perl5_nn29"></a>22.7.2 Perl5 typemaps</H3>
<H3><a name="Perl5_nn29"></a>23.7.2 Perl5 typemaps</H3>
The previous section illustrated an "in" typemap for converting Perl objects to C.
@ -1789,7 +1789,7 @@ Return of C++ member data (all languages).
Check value of input parameter.
</blockquote>
<H3><a name="Perl5_nn30"></a>22.7.3 Typemap variables</H3>
<H3><a name="Perl5_nn30"></a>23.7.3 Typemap variables</H3>
Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear.
@ -1855,7 +1855,7 @@ properly assigned.
The Perl name of the wrapper function being created.
</blockquote>
<H3><a name="Perl5_nn31"></a>22.7.4 Useful functions</H3>
<H3><a name="Perl5_nn31"></a>23.7.4 Useful functions</H3>
<p>
@ -1918,14 +1918,14 @@ int sv_isa(SV *, char *0;
</blockquote>
<H2><a name="Perl5_nn32"></a>22.8 Typemap Examples</H2>
<H2><a name="Perl5_nn32"></a>23.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.
<H3><a name="Perl5_nn33"></a>22.8.1 Converting a Perl5 array to a char ** </H3>
<H3><a name="Perl5_nn33"></a>23.8.1 Converting a Perl5 array to a char ** </H3>
<p>
@ -2017,7 +2017,7 @@ print @$b,"\n"; # Print it out
</pre></blockquote>
<H3><a name="Perl5_nn34"></a>22.8.2 Return values </H3>
<H3><a name="Perl5_nn34"></a>23.8.2 Return values </H3>
<p>
@ -2046,7 +2046,7 @@ can be done using the <tt>EXTEND()</tt> macro as in :
}
</pre></blockquote>
<H3><a name="Perl5_nn35"></a>22.8.3 Returning values from arguments</H3>
<H3><a name="Perl5_nn35"></a>23.8.3 Returning values from arguments</H3>
<p>
@ -2100,7 +2100,7 @@ print "multout(7,13) = @r\n";
($x,$y) = multout(7,13);
</pre></blockquote>
<H3><a name="Perl5_nn36"></a>22.8.4 Accessing array structure members</H3>
<H3><a name="Perl5_nn36"></a>23.8.4 Accessing array structure members</H3>
<p>
@ -2161,7 +2161,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.
<H3><a name="Perl5_nn37"></a>22.8.5 Turning Perl references into C pointers</H3>
<H3><a name="Perl5_nn37"></a>23.8.5 Turning Perl references into C pointers</H3>
<p>
@ -2226,7 +2226,7 @@ print "$c\n";
</pre></blockquote>
<H3><a name="Perl5_nn38"></a>22.8.6 Pointer handling</H3>
<H3><a name="Perl5_nn38"></a>23.8.6 Pointer handling</H3>
<p>
@ -2301,7 +2301,7 @@ For example:
</pre>
</blockquote>
<H2><a name="Perl5_nn39"></a>22.9 Proxy classes</H2>
<H2><a name="Perl5_nn39"></a>23.9 Proxy classes</H2>
<p>
@ -2316,7 +2316,7 @@ to the underlying code. This section describes the implementation
details of the proxy interface.
</p>
<H3><a name="Perl5_nn40"></a>22.9.1 Preliminaries</H3>
<H3><a name="Perl5_nn40"></a>23.9.1 Preliminaries</H3>
To generate proxy classes, you need to use the <tt>-proxy</tt> command line option.
@ -2334,7 +2334,7 @@ you provided with the <tt>%module</tt> directive. Then, in place of the origina
SWIG creates a collection of high-level Perl wrappers. In your scripts, you will use these
high level wrappers. The wrappers, in turn, interact with the low-level procedural module.
<H3><a name="Perl5_nn41"></a>22.9.2 Structure and class wrappers</H3>
<H3><a name="Perl5_nn41"></a>23.9.2 Structure and class wrappers</H3>
<p>
@ -2460,7 +2460,7 @@ $v-&gt;DESTROY();
</pre></blockquote>
<H3><a name="Perl5_nn42"></a>22.9.3 Object Ownership</H3>
<H3><a name="Perl5_nn42"></a>23.9.3 Object Ownership</H3>
<p>
@ -2547,7 +2547,7 @@ counting, garbage collection, or advanced features one might find in
sophisticated languages.
</p>
<H3><a name="Perl5_nn43"></a>22.9.4 Nested Objects</H3>
<H3><a name="Perl5_nn43"></a>23.9.4 Nested Objects</H3>
<p>
@ -2600,7 +2600,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
%${$p-&gt;{v}} = ( x=&gt;0, y=&gt;0, z=&gt;0);
</pre></blockquote>
<H3><a name="Perl5_nn44"></a>22.9.5 Shadow Functions</H3>
<H3><a name="Perl5_nn44"></a>23.9.5 Shadow Functions</H3>
<p>
@ -2634,7 +2634,7 @@ This function replaces the original function, but operates in an
identical manner.
</p>
<H3><a name="Perl5_nn45"></a>22.9.6 Inheritance</H3>
<H3><a name="Perl5_nn45"></a>23.9.6 Inheritance</H3>
<p>

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

@ -6,7 +6,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>23 SWIG and PHP4</H1>
<H1><a name="Php"></a>24 SWIG and PHP4</H1>
<!-- INDEX -->
<ul>
<li><a href="#Php_nn2">Preliminaries</a>
@ -49,7 +49,7 @@ that shadow classes are implemented inside the php module in C++ instead
of in the generated .php file in php.
</p>
<H2><a name="Php_nn2"></a>23.1 Preliminaries</H2>
<H2><a name="Php_nn2"></a>24.1 Preliminaries</H2>
In order to use this module, you will need to have a copy of the PHP 4.0 (or
@ -59,7 +59,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.
<H2><a name="Php_nn3"></a>23.2 Building PHP4 Extensions</H2>
<H2><a name="Php_nn3"></a>24.2 Building PHP4 Extensions</H2>
<p>
@ -100,7 +100,7 @@ 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.
</p>
<H3><a name="Php_nn4"></a>23.2.1 Building a loadable extension</H3>
<H3><a name="Php_nn4"></a>24.2.1 Building a loadable extension</H3>
<p>
@ -176,10 +176,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>.
<H3><a name="Php_nn5"></a>23.2.2 Basic PHP4 interface</H3>
<H3><a name="Php_nn5"></a>24.2.2 Basic PHP4 interface</H3>
<H3><a name="Php_nn6"></a>23.2.3 Functions</H3>
<H3><a name="Php_nn6"></a>24.2.3 Functions</H3>
<p>
@ -205,7 +205,7 @@ $c = bar(3.5); # Use default argument for 2nd parameter
</pre></blockquote>
<H3><a name="Php_nn7"></a>23.2.4 Global Variables</H3>
<H3><a name="Php_nn7"></a>24.2.4 Global Variables</H3>
<p>
@ -241,7 +241,7 @@ SWIG supports global variables of all C datatypes including pointers and complex
objects.
</p>
<H3><a name="Php_nn8"></a>23.2.5 Pointers </H3>
<H3><a name="Php_nn8"></a>24.2.5 Pointers </H3>
<p>
@ -255,7 +255,7 @@ You can also explicitly create a NULL pointer as a string "NULL"
or by passing a null or empty value.
</p>
<H3><a name="Php_nn9"></a>23.2.6 Structures and C++ classes</H3>
<H3><a name="Php_nn9"></a>24.2.6 Structures and C++ classes</H3>
<p>
@ -295,7 +295,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>
<H3><a name="Php_nn10"></a>23.2.7 Constants</H3>
<H3><a name="Php_nn10"></a>24.2.7 Constants</H3>
<p>
@ -404,7 +404,7 @@ both point to the same value, without the case test taking place.
( Apologies, this paragraph needs rewritting to make some sense. )
</p>
<H3><a name="Php_nn11"></a>23.2.8 Shadow classes</H3>
<H3><a name="Php_nn11"></a>24.2.8 Shadow classes</H3>
<p>
@ -439,7 +439,7 @@ functions like before.
.... ( more examples on the way ) ....
</p>
<H3><a name="Php_nn12"></a>23.2.9 Constructors and Destructers</H3>
<H3><a name="Php_nn12"></a>24.2.9 Constructors and Destructers</H3>
<p>
@ -470,7 +470,7 @@ I am not sure if PHP resources are all freed at the end of a script, or
when they each go out of scope.
</p>
<H3><a name="Php_nn13"></a>23.2.10 Static Member Variables</H3>
<H3><a name="Php_nn13"></a>24.2.10 Static Member Variables</H3>
Class variables are not supported in PHP, however class functions are, using
@ -507,7 +507,7 @@ echo "There has now been " . Ko::threats() . " threats\n";
</pre></blockquote>
<H3><a name="Php_nn14"></a>23.2.11 PHP4 Pragmas</H3>
<H3><a name="Php_nn14"></a>24.2.11 PHP4 Pragmas</H3>
There are a few pragmas understood by the PHP4 module. The first,
@ -536,7 +536,7 @@ function is called.
%include "example.h"
</pre></blockquote>
<H3><a name="Php_nn15"></a>23.2.12 Building extensions into php</H3>
<H3><a name="Php_nn15"></a>24.2.12 Building extensions into php</H3>
<p>
@ -594,7 +594,7 @@ which contains your new module. You can test it with a php script which
does not have the 'dl' command as used above.
</p>
<H3><a name="Php_nn16"></a>23.2.13 To be furthered...</H3>
<H3><a name="Php_nn16"></a>24.2.13 To be furthered...</H3>
</body>

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Pike"></a>24 SWIG and Pike</H1>
<H1><a name="Pike"></a>25 SWIG and Pike</H1>
<!-- INDEX -->
<ul>
<li><a href="#Pike_nn2">Preliminaries</a>
@ -43,10 +43,10 @@ least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
chapter.<br>
</p>
<H2><a name="Pike_nn2"></a>24.1 Preliminaries</H2>
<H2><a name="Pike_nn2"></a>25.1 Preliminaries</H2>
<H3><a name="Pike_nn3"></a>24.1.1 Running SWIG</H3>
<H3><a name="Pike_nn3"></a>25.1.1 Running SWIG</H3>
Suppose that you defined a SWIG module such as the following:
@ -80,7 +80,7 @@ can use the <tt>-o</tt> option:
<blockquote>
<pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre>
</blockquote>
<H3><a name="Pike_nn4"></a>24.1.2 Getting the right header files</H3>
<H3><a name="Pike_nn4"></a>25.1.2 Getting the right header files</H3>
<p>
@ -100,7 +100,7 @@ You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt>
and so on.
</p>
<H3><a name="Pike_nn5"></a>24.1.3 Using your module</H3>
<H3><a name="Pike_nn5"></a>25.1.3 Using your module</H3>
To use your module, simply use Pike's <tt>import</tt> statement:
@ -113,10 +113,10 @@ Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend)
(1) Result: 24
</pre></blockquote>
<H2><a name="Pike_nn6"></a>24.2 Basic C/C++ Mapping</H2>
<H2><a name="Pike_nn6"></a>25.2 Basic C/C++ Mapping</H2>
<H3><a name="Pike_nn7"></a>24.2.1 Modules</H3>
<H3><a name="Pike_nn7"></a>25.2.1 Modules</H3>
All of the code for a given SWIG module is wrapped into a single Pike
@ -125,7 +125,7 @@ module ultimately determines the module's name (as far as Pike is
concerned), SWIG's <tt>%module</tt> directive doesn't really have any
significance.
<H3><a name="Pike_nn8"></a>24.2.2 Functions</H3>
<H3><a name="Pike_nn8"></a>25.2.2 Functions</H3>
Global functions are wrapped as new Pike built-in functions. For
@ -146,7 +146,7 @@ exactly as you'd expect it to:
(1) Result: 24
</pre></blockquote>
<H3><a name="Pike_nn9"></a>24.2.3 Global variables</H3>
<H3><a name="Pike_nn9"></a>25.2.3 Global variables</H3>
Global variables are currently wrapped as a pair of of functions, one to get
@ -171,19 +171,19 @@ will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>:
(3) Result: 3.141590
</pre></blockquote>
<H3><a name="Pike_nn10"></a>24.2.4 Constants and enumerated types</H3>
<H3><a name="Pike_nn10"></a>25.2.4 Constants and enumerated types</H3>
Enumerated types in C/C++ declarations are wrapped as Pike constants,
not as Pike enums.
<H3><a name="Pike_nn11"></a>24.2.5 Constructors and Destructors</H3>
<H3><a name="Pike_nn11"></a>25.2.5 Constructors and Destructors</H3>
Constructors are wrapped as <tt>create()</tt> methods, and destructors are
wrapped as <tt>destroy()</tt> methods, for Pike classes.
<H3><a name="Pike_nn12"></a>24.2.6 Static Members</H3>
<H3><a name="Pike_nn12"></a>25.2.6 Static Members</H3>
Since Pike doesn't support static methods or data for Pike classes, static

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Python"></a>25 SWIG and Python</H1>
<H1><a name="Python"></a>26 SWIG and Python</H1>
<!-- INDEX -->
<ul>
<li><a href="#Python_nn2">Overview</a>
@ -108,7 +108,7 @@ very least, make sure you read the "<a href="SWIG.html#SWIG">SWIG
Basics</a>" chapter.
</p>
<H2><a name="Python_nn2"></a>25.1 Overview</H2>
<H2><a name="Python_nn2"></a>26.1 Overview</H2>
<p>
@ -135,10 +135,10 @@ described followed by a discussion of low-level implementation
details.
</p>
<H2><a name="Python_nn3"></a>25.2 Preliminaries</H2>
<H2><a name="Python_nn3"></a>26.2 Preliminaries</H2>
<H3><a name="Python_nn4"></a>25.2.1 Running SWIG</H3>
<H3><a name="Python_nn4"></a>26.2.1 Running SWIG</H3>
<p>
@ -187,7 +187,7 @@ from the module name specified with <tt>%module</tt>. If the module name is <tt
a file <tt>example.py</tt> is created.
</p>
<H3><a name="Python_nn5"></a>25.2.2 Getting the right header files</H3>
<H3><a name="Python_nn5"></a>26.2.2 Getting the right header files</H3>
<p>
@ -216,7 +216,7 @@ Type "copyright", "credits" or "license" for more information.
</pre>
</blockquote>
<H3><a name="Python_nn6"></a>25.2.3 Compiling a dynamic module</H3>
<H3><a name="Python_nn6"></a>26.2.3 Compiling a dynamic module</H3>
<p>
@ -262,10 +262,10 @@ 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.
</p>
<H3><a name="Python_nn7"></a>25.2.4 Using distutils</H3>
<H3><a name="Python_nn7"></a>26.2.4 Using distutils</H3>
<H3><a name="Python_nn8"></a>25.2.5 Static linking</H3>
<H3><a name="Python_nn8"></a>26.2.5 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Python
@ -340,7 +340,7 @@ If using static linking, you might want to rely on a different approach
(perhaps using distutils).
</p>
<H3><a name="Python_nn9"></a>25.2.6 Using your module</H3>
<H3><a name="Python_nn9"></a>26.2.6 Using your module</H3>
<p>
@ -487,7 +487,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).
<H3><a name="Python_nn10"></a>25.2.7 Compilation of C++ extensions</H3>
<H3><a name="Python_nn10"></a>26.2.7 Compilation of C++ extensions</H3>
Compilation of C++ extensions has traditionally been a tricky problem.
@ -566,7 +566,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Python_nn11"></a>25.2.8 Compiling for 64-bit platforms</H3>
<H3><a name="Python_nn11"></a>26.2.8 Compiling for 64-bit platforms</H3>
On platforms that support 64-bit applications (Solaris, Irix, etc.),
@ -591,7 +591,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Python_nn12"></a>25.2.9 Building Python Extensions under Windows</H3>
<H3><a name="Python_nn12"></a>26.2.9 Building Python Extensions under Windows</H3>
Building a SWIG extension to Python under Windows is roughly
@ -676,14 +676,14 @@ you may want to consult the <a href="http://swig.cs.uchicago.edu/cgi-bin/wiki.pl
SWIG Wiki</a>.
</p>
<H2><a name="Python_nn13"></a>25.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Python_nn13"></a>26.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.
<H3><a name="Python_nn14"></a>25.3.1 Modules</H3>
<H3><a name="Python_nn14"></a>26.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Python
@ -694,7 +694,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.
<H3><a name="Python_nn15"></a>25.3.2 Functions</H3>
<H3><a name="Python_nn15"></a>26.3.2 Functions</H3>
<p>
@ -718,7 +718,7 @@ like you think it does:
&gt;&gt;&gt;
</pre></blockquote>
<H3><a name="Python_nn16"></a>25.3.3 Global variables</H3>
<H3><a name="Python_nn16"></a>26.3.3 Global variables</H3>
<p>
@ -845,7 +845,7 @@ that starts with a leading underscore. SWIG does not create <tt>cvar</tt>
if there are no global variables in a module.
</p>
<H3><a name="Python_nn17"></a>25.3.4 Constants and enums</H3>
<H3><a name="Python_nn17"></a>26.3.4 Constants and enums</H3>
<p>
@ -883,7 +883,7 @@ other object. Unfortunately, there is no easy way for SWIG to
generate code that prevents this. You will just have to be careful.
</p>
<H3><a name="Python_nn18"></a>25.3.5 Pointers</H3>
<H3><a name="Python_nn18"></a>26.3.5 Pointers</H3>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with
@ -1024,7 +1024,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.
<H3><a name="Python_nn19"></a>25.3.6 Structures</H3>
<H3><a name="Python_nn19"></a>26.3.6 Structures</H3>
<p>
@ -1197,7 +1197,7 @@ everything works just like you would expect. For example:
</pre>
</blockquote>
<H3><a name="Python_nn20"></a>25.3.7 C++ classes</H3>
<H3><a name="Python_nn20"></a>26.3.7 C++ classes</H3>
<p>
@ -1278,7 +1278,7 @@ they are accessed through <tt>cvar</tt> like this:
</pre>
</blockquote>
<H3><a name="Python_nn21"></a>25.3.8 C++ inheritance</H3>
<H3><a name="Python_nn21"></a>26.3.8 C++ inheritance</H3>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have
@ -1325,7 +1325,7 @@ then the function <tt>spam()</tt> accepts <tt>Foo *</tt> or a pointer to any cla
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Python_nn22"></a>25.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Python_nn22"></a>26.3.9 Pointers, references, values, and arrays</H3>
In C++, there are many different ways a function might receive
@ -1372,7 +1372,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).
<H3><a name="Python_nn23"></a>25.3.10 C++ overloaded functions</H3>
<H3><a name="Python_nn23"></a>26.3.10 C++ overloaded functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -1475,7 +1475,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Python_nn24"></a>25.3.11 C++ operators</H3>
<H3><a name="Python_nn24"></a>26.3.11 C++ operators</H3>
Certain C++ overloaded operators can be handled automatically by SWIG. For example,
@ -1549,7 +1549,7 @@ Also, be aware that certain operators don't map cleanly to Python. For instance
overloaded assignment operators don't map to Python semantics and will be ignored.
</p>
<H3><a name="Python_nn25"></a>25.3.12 C++ namespaces</H3>
<H3><a name="Python_nn25"></a>26.3.12 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1608,7 +1608,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.
<H3><a name="Python_nn26"></a>25.3.13 C++ templates</H3>
<H3><a name="Python_nn26"></a>26.3.13 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1655,7 +1655,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. Some more complicated
examples will appear later.
<H3><a name="Python_nn27"></a>25.3.14 C++ Smart Pointers</H3>
<H3><a name="Python_nn27"></a>26.3.14 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1727,7 +1727,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</blockquote>
<H2><a name="Python_nn28"></a>25.4 Further details on the Python class interface</H2>
<H2><a name="Python_nn28"></a>26.4 Further details on the Python class interface</H2>
In the previous section, a high-level view of Python wrapping was
@ -1738,7 +1738,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.
<H3><a name="Python_nn29"></a>25.4.1 Proxy classes</H3>
<H3><a name="Python_nn29"></a>26.4.1 Proxy classes</H3>
In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters,
@ -1819,7 +1819,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).
<H3><a name="Python_nn30"></a>25.4.2 Memory management</H3>
<H3><a name="Python_nn30"></a>26.4.2 Memory management</H3>
<p>
@ -1987,7 +1987,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.
<H3><a name="Python_nn31"></a>25.4.3 Python 2.2 and classic classes</H3>
<H3><a name="Python_nn31"></a>26.4.3 Python 2.2 and classic classes</H3>
SWIG makes every attempt to preserve backwards compatibility with
@ -2022,7 +2022,7 @@ class itself. In Python-2.1 and earlier, they have to be accessed as a global
function or through an instance (see the earlier section).
</p>
<H2><a name="directors"></a>25.5 Cross language polymorphism (experimental)</H2>
<H2><a name="directors"></a>26.5 Cross language polymorphism (experimental)</H2>
<p>
@ -2056,7 +2056,7 @@ proxy classes, director classes, and C wrapper functions takes care of
all the cross-language method routing transparently.
</p>
<H3><a name="Python_nn33"></a>25.5.1 Enabling directors</H3>
<H3><a name="Python_nn33"></a>26.5.1 Enabling directors</H3>
The director feature is disabled by default. To use directors you
@ -2124,7 +2124,7 @@ public:
</pre>
</blockquote>
<H3><a name="Python_nn34"></a>25.5.2 Director classes</H3>
<H3><a name="Python_nn34"></a>26.5.2 Director classes</H3>
<p>
@ -2203,7 +2203,7 @@ so there is no need for the extra overhead involved with routing the
calls through Python.
</p>
<H3><a name="Python_nn35"></a>25.5.3 Ownership and object destruction</H3>
<H3><a name="Python_nn35"></a>26.5.3 Ownership and object destruction</H3>
<p>
@ -2268,7 +2268,7 @@ deleting all the Foo pointers it contains at some point. Note that no hard
references to the Foo objects remain in Python.
</p>
<H3><a name="Python_nn36"></a>25.5.4 Exception unrolling</H3>
<H3><a name="Python_nn36"></a>26.5.4 Exception unrolling</H3>
With directors routing method calls to Python, and proxies routing them
@ -2323,7 +2323,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.
<H3><a name="Python_nn37"></a>25.5.5 Overhead and code bloat</H3>
<H3><a name="Python_nn37"></a>26.5.5 Overhead and code bloat</H3>
<p>
@ -2357,7 +2357,7 @@ directive) for only those methods that are likely to be extended in
Python.
</p>
<H3><a name="Python_nn38"></a>25.5.6 Typemaps</H3>
<H3><a name="Python_nn38"></a>26.5.6 Typemaps</H3>
<p>
@ -2375,10 +2375,10 @@ for std::string, std::vector, and std::complex, although there's no
guarantee these are fully functional yet.
</p>
<H3><a name="Python_nn39"></a>25.5.7 Miscellaneous</H3>
<H3><a name="Python_nn39"></a>26.5.7 Miscellaneous</H3>
<H2><a name="Python_nn40"></a>25.6 Common customization features</H2>
<H2><a name="Python_nn40"></a>26.6 Common customization features</H2>
The last section presented the absolute basics of C/C++ wrapping. If you do nothing
@ -2388,7 +2388,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.
<H3><a name="Python_nn41"></a>25.6.1 C/C++ helper functions</H3>
<H3><a name="Python_nn41"></a>26.6.1 C/C++ helper functions</H3>
Sometimes when you create a module, it is missing certain bits of functionality. For
@ -2459,7 +2459,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.
<H3><a name="Python_nn42"></a>25.6.2 Adding additional Python code</H3>
<H3><a name="Python_nn42"></a>26.6.2 Adding additional Python code</H3>
If writing support code in C isn't enough, it is also possible to write code in
@ -2507,7 +2507,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.
<H3><a name="Python_nn43"></a>25.6.3 Class extension with %extend</H3>
<H3><a name="Python_nn43"></a>26.6.3 Class extension with %extend</H3>
One of the more interesting features of SWIG is that it can extend
@ -2586,7 +2586,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.
<H3><a name="Python_nn44"></a>25.6.4 Exception handling with %exception</H3>
<H3><a name="Python_nn44"></a>26.6.4 Exception handling with %exception</H3>
<p>
@ -2704,7 +2704,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#Library">SWIG Library</a> chapter.
<H2><a name="Python_nn45"></a>25.7 Tips and techniques</H2>
<H2><a name="Python_nn45"></a>26.7 Tips and techniques</H2>
Although SWIG is largely automatic, there are certain types of wrapping problems that
@ -2712,7 +2712,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.
<H3><a name="Python_nn46"></a>25.7.1 Input and output parameters</H3>
<H3><a name="Python_nn46"></a>26.7.1 Input and output parameters</H3>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -2895,7 +2895,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>.
<H3><a name="Python_nn47"></a>25.7.2 Simple pointers</H3>
<H3><a name="Python_nn47"></a>26.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
@ -2951,7 +2951,7 @@ If you replace <tt>%pointer_functions()</tt> by <tt>%pointer_class(type,name)</t
See the <a href="Library.html#Library">SWIG Library</a> chapter for further details.
<H3><a name="Python_nn48"></a>25.7.3 Unbounded C Arrays</H3>
<H3><a name="Python_nn48"></a>26.7.3 Unbounded C Arrays</H3>
Sometimes a C function expects an array to be passed as a pointer. For example,
@ -3005,7 +3005,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.
<H3><a name="Python_nn49"></a>25.7.4 String handling</H3>
<H3><a name="Python_nn49"></a>26.7.4 String handling</H3>
If a C function has an argument of <tt>char *</tt>, then a Python string
@ -3062,16 +3062,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.
<H3><a name="Python_nn50"></a>25.7.5 Arrays</H3>
<H3><a name="Python_nn50"></a>26.7.5 Arrays</H3>
<H3><a name="Python_nn51"></a>25.7.6 String arrays</H3>
<H3><a name="Python_nn51"></a>26.7.6 String arrays</H3>
<H3><a name="Python_nn52"></a>25.7.7 STL wrappers</H3>
<H3><a name="Python_nn52"></a>26.7.7 STL wrappers</H3>
<H2><a name="Python_nn53"></a>25.8 Typemaps</H2>
<H2><a name="Python_nn53"></a>26.8 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping behavior
@ -3086,7 +3086,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Python interface or if you want to elevate your guru status.
</p>
<H3><a name="Python_nn54"></a>25.8.1 What is a typemap?</H3>
<H3><a name="Python_nn54"></a>26.8.1 What is a typemap?</H3>
<p>
@ -3192,7 +3192,7 @@ parameter is omitted):
</pre>
</blockquote>
<H3><a name="Python_nn55"></a>25.8.2 Python typemaps</H3>
<H3><a name="Python_nn55"></a>26.8.2 Python typemaps</H3>
The previous section illustrated an "in" typemap for converting Python objects to C.
@ -3224,7 +3224,7 @@ $ cat python.swg
Additional typemap examples can also be found in the <tt>typemaps.i</tt> file.
<H3><a name="Python_nn56"></a>25.8.3 Typemap variables</H3>
<H3><a name="Python_nn56"></a>26.8.3 Typemap variables</H3>
Within typemap code, a number of special variables prefaced with a <tt>$</tt> may appear.
@ -3293,7 +3293,7 @@ properly assigned.
The Python name of the wrapper function being created.
</blockquote>
<H3><a name="Python_nn57"></a>25.8.4 Useful Python Functions</H3>
<H3><a name="Python_nn57"></a>26.8.4 Useful Python Functions</H3>
When you write a typemap, you usually have to work directly with Python objects.
@ -3391,14 +3391,14 @@ write me
</pre>
</blockquote>
<H2><a name="Python_nn58"></a>25.9 Typemap Examples</H2>
<H2><a name="Python_nn58"></a>26.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.
<H3><a name="Python_nn59"></a>25.9.1 Converting Python list to a char ** </H3>
<H3><a name="Python_nn59"></a>26.9.1 Converting Python list to a char ** </H3>
<p>
@ -3476,7 +3476,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.
<H3><a name="Python_nn60"></a>25.9.2 Expanding a Python object into multiple arguments</H3>
<H3><a name="Python_nn60"></a>26.9.2 Expanding a Python object into multiple arguments</H3>
Suppose that you had a collection of C functions with arguments
@ -3549,7 +3549,7 @@ to supply the argument count. This is automatically set by the typemap code. F
</pre>
</blockquote>
<H3><a name="Python_nn61"></a>25.9.3 Using typemaps to return arguments</H3>
<H3><a name="Python_nn61"></a>26.9.3 Using typemaps to return arguments</H3>
<p>
@ -3638,7 +3638,7 @@ function can now be used as follows:
&gt;&gt;&gt;
</pre></blockquote>
<H3><a name="Python_nn62"></a>25.9.4 Mapping Python tuples into small arrays</H3>
<H3><a name="Python_nn62"></a>26.9.4 Mapping Python tuples into small arrays</H3>
<p>
@ -3687,7 +3687,7 @@ array, such an approach would not be recommended for huge arrays, but
for small structures, this approach works fine.
</p>
<H3><a name="Python_nn63"></a>25.9.5 Mapping sequences to C arrays</H3>
<H3><a name="Python_nn63"></a>26.9.5 Mapping sequences to C arrays</H3>
Suppose that you wanted to generalize the previous example to handle C
@ -3766,7 +3766,7 @@ static int convert_darray(PyObject *input, double *ptr, int size) {
</pre>
</blockquote>
<H3><a name="Python_nn64"></a>25.9.6 Pointer handling</H3>
<H3><a name="Python_nn64"></a>26.9.6 Pointer handling</H3>
<p>

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

@ -4,7 +4,7 @@
<title>SWIG and Ruby</title>
</head>
<body bgcolor="#ffffff">
<H1><a name="Ruby"></a>26 SWIG and Ruby</H1>
<H1><a name="Ruby"></a>27 SWIG and Ruby</H1>
<!-- INDEX -->
<ul>
<li><a href="#Ruby_nn2">Preliminaries</a>
@ -82,7 +82,7 @@
<p>This chapter describes SWIG's support of Ruby. </p>
<hr><a name="n2"></a>
<H2><a name="Ruby_nn2"></a>26.1 Preliminaries</H2>
<H2><a name="Ruby_nn2"></a>27.1 Preliminaries</H2>
SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given the
@ -99,7 +99,7 @@ earlier chapters. At the very least, make sure you also read the "<a
reader
has a basic understanding of Ruby.
<H3><a name="Ruby_nn3"></a>26.1.1 Running SWIG</H3>
<H3><a name="Ruby_nn3"></a>27.1.1 Running SWIG</H3>
<p>
@ -125,7 +125,7 @@ compile this
file and link it with the rest of your program.
<H3><a name="Ruby_nn4"></a>26.1.2 Getting the right header files</H3>
<H3><a name="Ruby_nn4"></a>27.1.2 Getting the right header files</H3>
<p>
@ -150,7 +150,7 @@ can run Ruby to find out. For example:
</pre>
</blockquote>
<H3><a name="Ruby_nn5"></a>26.1.3 Compiling a dynamic module</H3>
<H3><a name="Ruby_nn5"></a>27.1.3 Compiling a dynamic module</H3>
Ruby extension modules are typically compiled into shared libraries
@ -209,7 +209,7 @@ 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></p>
<H3><a name="Ruby_nn6"></a>26.1.4 Using your module</H3>
<H3><a name="Ruby_nn6"></a>27.1.4 Using your module</H3>
Ruby <i>module</i> names must be capitalized, but the convention for
@ -224,7 +224,7 @@ extension. So for example, a SWIG interface file that begins with:
<blockquote><pre>%module example<br></pre></blockquote>
will result in an extension module using the feature name "example" and
Ruby module name "Example".
<H3><a name="Ruby_nn7"></a>26.1.5 Static linking</H3>
<H3><a name="Ruby_nn7"></a>27.1.5 Static linking</H3>
An alternative approach to dynamic linking is to rebuild the Ruby
@ -241,7 +241,7 @@ adding your directory to the list of extensions in the file, and
finally rebuilding Ruby.
</p>
<p><a name="n8"></a></p>
<H3><a name="Ruby_nn8"></a>26.1.6 Compilation of C++ extensions</H3>
<H3><a name="Ruby_nn8"></a>27.1.6 Compilation of C++ extensions</H3>
<p>
@ -274,7 +274,7 @@ into your extension, e.g.
<pre>require 'mkmf'<br>$libs = append_library($libs, "supc++")<br>create_makefile('example')<br></pre>
</blockquote>
<hr>
<H2><a name="Ruby_nn9"></a>26.2 Building Ruby Extensions under Windows 95/NT</H2>
<H2><a name="Ruby_nn9"></a>27.2 Building Ruby Extensions under Windows 95/NT</H2>
Building a SWIG extension to Ruby under Windows 95/NT is roughly
@ -303,7 +303,7 @@ 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></p>
<H3><a name="Ruby_nn10"></a>26.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Ruby_nn10"></a>27.2.1 Running SWIG from Developer Studio</H3>
If you are developing your application within Microsoft developer
@ -391,13 +391,13 @@ Foo = 3.0
</blockquote>
<hr><a name="n11"></a>
<H2><a name="Ruby_nn11"></a>26.3 The Ruby-to-C/C++ Mapping</H2>
<H2><a name="Ruby_nn11"></a>27.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.
<H3><a name="Ruby_nn12"></a>26.3.1 Modules</H3>
<H3><a name="Ruby_nn12"></a>27.3.1 Modules</H3>
The SWIG <tt>%module</tt> directive specifies the name of the Ruby
@ -457,7 +457,7 @@ take care that the names of your constants, classes and methods don't
conflict
with any of Ruby's built-in names.
<H3><a name="Ruby_nn13"></a>26.3.2 Functions</H3>
<H3><a name="Ruby_nn13"></a>27.3.2 Functions</H3>
Global functions are wrapped as Ruby module methods. For example, given
@ -482,7 +482,7 @@ irb(main):002:0&gt; <b>Example.fact(4)</b>
24
</pre>
</blockquote>
<H3><a name="Ruby_nn14"></a>26.3.3 Variable Linking</H3>
<H3><a name="Ruby_nn14"></a>27.3.3 Variable Linking</H3>
C/C++ global variables are wrapped as a pair of singleton methods for
@ -534,7 +534,7 @@ directive. For example:
The <tt>%immutable</tt> directive stays in effect until it is
explicitly
disabled using <tt>%mutable</tt>.
<H3><a name="Ruby_nn15"></a>26.3.4 Constants</H3>
<H3><a name="Ruby_nn15"></a>27.3.4 Constants</H3>
C/C++ constants are wrapped as module constants initialized to the
@ -554,7 +554,7 @@ irb(main):002:0&gt; <b>Example::PI</b>
3.14159
</pre>
</blockquote>
<H3><a name="Ruby_nn16"></a>26.3.5 Pointers</H3>
<H3><a name="Ruby_nn16"></a>27.3.5 Pointers</H3>
"Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't
@ -576,7 +576,7 @@ internally generated Ruby class:
</blockquote>
A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt>
object.
<H3><a name="Ruby_nn17"></a>26.3.6 Structures</H3>
<H3><a name="Ruby_nn17"></a>27.3.6 Structures</H3>
C/C++ structs are wrapped as Ruby classes, with accessor methods (i.e.
@ -656,7 +656,7 @@ generates accessor functions such as this:
<blockquote>
<pre>Foo *Bar_f_get(Bar *b) {<br> return &amp;b-&gt;f;<br>}<br><br>void Bar_f_set(Bar *b, Foo *val) {<br> b-&gt;f = *val;<br>}<br></pre>
</blockquote>
<H3><a name="Ruby_nn18"></a>26.3.7 C++ classes</H3>
<H3><a name="Ruby_nn18"></a>27.3.7 C++ classes</H3>
Like structs, C++ classes are wrapped by creating a new Ruby class of
@ -692,7 +692,7 @@ In Ruby, these functions are used as follows:
<blockquote>
<pre>require 'Example'<br><br>l = Example::List.new<br><br>l.insert("Ale")<br>l.insert("Stout")<br>l.insert("Lager")<br>Example.print(l)<br>l.length()<br>----- produces the following output <br>Lager<br>Stout<br>Ale<br>3<br></pre>
</blockquote>
<H3><a name="Ruby_nn19"></a>26.3.8 C++ Inheritance</H3>
<H3><a name="Ruby_nn19"></a>27.3.8 C++ Inheritance</H3>
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if
@ -808,7 +808,7 @@ 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>).
<H3><a name="Ruby_nn20"></a>26.3.9 C++ Overloaded Functions</H3>
<H3><a name="Ruby_nn20"></a>27.3.9 C++ Overloaded Functions</H3>
C++ overloaded functions, methods, and constructors are mostly
@ -865,7 +865,7 @@ arises--in this case, the
first declaration takes precedence.
<p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a>
chapter for more information about overloading. <a name="n21"></a></p>
<H3><a name="Ruby_nn21"></a>26.3.10 C++ Operators</H3>
<H3><a name="Ruby_nn21"></a>27.3.10 C++ Operators</H3>
For the most part, overloaded operators are handled automatically by
@ -895,7 +895,7 @@ Now, in Ruby, you can do this:
More details about wrapping C++ operators into Ruby operators is
discussed in
the <a href="#ruby_operator_overloading">section on operator overloading</a>.
<H3><a name="Ruby_nn22"></a>26.3.11 C++ namespaces</H3>
<H3><a name="Ruby_nn22"></a>27.3.11 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -930,7 +930,7 @@ For example, make the module name the same as the namespace and create
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.
<H3><a name="Ruby_nn23"></a>26.3.12 C++ templates</H3>
<H3><a name="Ruby_nn23"></a>27.3.12 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -985,7 +985,7 @@ 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#SWIGPlus">SWIG and C++</a>
chapter.
<H3><a name="ruby_cpp_smart_pointers"></a>26.3.13 C++ Smart Pointers</H3>
<H3><a name="ruby_cpp_smart_pointers"></a>27.3.13 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been
@ -1022,7 +1022,7 @@ simply use the <tt>__deref__()</tt> method. For example:
<blockquote>
<pre>irb(main):004:0&gt; <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre>
</blockquote>
<H3><a name="Ruby_nn25"></a>26.3.14 Cross-Language Polymorphism</H3>
<H3><a name="Ruby_nn25"></a>27.3.14 Cross-Language Polymorphism</H3>
SWIG's Ruby module supports cross-language polymorphism (a.k.a. the
@ -1034,7 +1034,7 @@ this
secton just notes the differences that you need to be aware of when
using this
feature with Ruby.
<H4><a name="Ruby_nn26"></a>26.3.14.1 Exception Unrolling</H4>
<H4><a name="Ruby_nn26"></a>27.3.14.1 Exception Unrolling</H4>
Whenever a C++ director class routes one of its virtual member function
@ -1059,7 +1059,7 @@ Ruby exception
is raised, it will be caught here and a C++ exception is raised in its
place.
<hr><a name="n27"></a>
<H2><a name="Ruby_nn27"></a>26.4 Input and output parameters</H2>
<H2><a name="Ruby_nn27"></a>27.4 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as
@ -1134,7 +1134,7 @@ In Ruby:
<pre>r, c = Example.get_dimensions(m)<br></pre>
</blockquote>
<hr>
<H2><a name="Ruby_nn28"></a>26.5 Simple exception handling </H2>
<H2><a name="Ruby_nn28"></a>27.5 Simple exception handling </H2>
The SWIG <tt>%exception</tt> directive can be used to define a
@ -1189,7 +1189,7 @@ Ruby exception classes, consult a Ruby reference such as <a
href="http://www.rubycentral.com/book"><em>Programming Ruby</em></a>.
</p>
<hr><a name="n29"></a>
<H2><a name="Ruby_nn29"></a>26.6 Typemaps</H2>
<H2><a name="Ruby_nn29"></a>27.6 Typemaps</H2>
This section describes how you can modify SWIG's default wrapping
@ -1206,7 +1206,7 @@ Typemaps are only used if you want to change some aspect of the
primitive
C-Ruby interface.
<H3><a name="Ruby_nn30"></a>26.6.1 What is a typemap?</H3>
<H3><a name="Ruby_nn30"></a>27.6.1 What is a typemap?</H3>
A typemap is nothing more than a code generation rule that is attached
@ -1287,7 +1287,7 @@ follows (notice how the length parameter is omitted):
<blockquote>
<pre>puts Example.count('o','Hello World')<br>2<br></pre>
</blockquote>
<H3><a name="Ruby_nn31"></a>26.6.2 Ruby typemaps</H3>
<H3><a name="Ruby_nn31"></a>27.6.2 Ruby typemaps</H3>
The previous section illustrated an "in" typemap for converting Ruby
@ -1344,7 +1344,7 @@ occur.
Examples of these typemaps appears in the <a href="#ruby_typemap_examples">section on
typemap
examples</a>
<H3><a name="Ruby_nn32"></a>26.6.3 Typemap variables</H3>
<H3><a name="Ruby_nn32"></a>27.6.3 Typemap variables</H3>
Within a typemap, a number of special variables prefaced with a <tt>$</tt>
@ -1387,7 +1387,7 @@ so that their values can be properly assigned.
<tt>$symname</tt>
<blockquote>The Ruby name of the wrapper function being created.
</blockquote>
<H3><a name="Ruby_nn33"></a>26.6.4 Useful Functions</H3>
<H3><a name="Ruby_nn33"></a>27.6.4 Useful Functions</H3>
When you write a typemap, you usually have to work directly with Ruby
@ -1398,19 +1398,19 @@ more can be found in <a href="http://www.rubycentral.com/book"><em>Programming
Ruby</em></a>, by David Thomas
and Andrew Hunt.)
<p><a name="n34"></a></p>
<H4><a name="Ruby_nn34"></a>26.6.4.1 C Datatypes to Ruby Objects</H4>
<H4><a name="Ruby_nn34"></a>27.6.4.1 C Datatypes to Ruby Objects</H4>
<blockquote>
<pre>INT2NUM(long or int) - int to Fixnum or Bignum<br>INT2FIX(long or int) - int to Fixnum (faster than INT2NUM)<br>CHR2FIX(char) - char to Fixnum<br>rb_str_new2(char*) - char* to String<br>rb_float_new(double) - double to Float<br></pre>
</blockquote>
<H4><a name="Ruby_nn35"></a>26.6.4.2 Ruby Objects to C Datatypes</H4>
<H4><a name="Ruby_nn35"></a>27.6.4.2 Ruby Objects to C Datatypes</H4>
<blockquote>
<pre> int NUM2INT(Numeric)<br> int FIX2INT(Numeric)<br> unsigned int NUM2UINT(Numeric)<br> unsigned int FIX2UINT(Numeric)<br> long NUM2LONG(Numeric)<br> long FIX2LONG(Numeric)<br>unsigned long FIX2ULONG(Numeric)<br> char NUM2CHR(Numeric or String)<br> char * STR2CSTR(String)<br> char * rb_str2cstr(String, int*length)<br> double NUM2DBL(Numeric)<br><br></pre>
</blockquote>
<H4><a name="Ruby_nn36"></a>26.6.4.3 Macros for VALUE</H4>
<H4><a name="Ruby_nn36"></a>27.6.4.3 Macros for VALUE</H4>
<p>
@ -1425,7 +1425,7 @@ and Andrew Hunt.)
<blockquote>capacity of the Ruby array</blockquote>
<tt>RARRAY(arr)-&gt;ptr</tt>
<blockquote>pointer to array storage</blockquote>
<H4><a name="Ruby_nn37"></a>26.6.4.4 Exceptions</H4>
<H4><a name="Ruby_nn37"></a>27.6.4.4 Exceptions</H4>
<p>
@ -1483,7 +1483,7 @@ interpreted as with <tt>printf()</tt>.
if Ruby was invoked with the <tt>-w</tt> flag. The given format string
<i>fmt</i> and remaining arguments are interpreted as with <tt>printf()</tt>.
</blockquote>
<H4><a name="Ruby_nn38"></a>26.6.4.5 Iterators</H4>
<H4><a name="Ruby_nn38"></a>27.6.4.5 Iterators</H4>
<p>
@ -1516,13 +1516,13 @@ value)</tt>
<tt>void rb_throw(const char *tag, VALUE value)</tt>
<blockquote> Equivalent to Ruby's <tt>throw</tt>.
</blockquote>
<H3><a name="ruby_typemap_examples"></a>26.6.5 Typemap Examples</H3>
<H3><a name="ruby_typemap_examples"></a>27.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.
<H3><a name="Ruby_nn40"></a>26.6.6 Converting a Ruby array to a char **</H3>
<H3><a name="Ruby_nn40"></a>27.6.6 Converting a Ruby array to a char **</H3>
A common problem in many C programs is the processing of command line
@ -1550,7 +1550,7 @@ 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><a name="Ruby_nn41"></a>26.6.7 Collecting arguments in a hash</H3>
<H3><a name="Ruby_nn41"></a>27.6.7 Collecting arguments in a hash</H3>
Ruby's solution to the "keyword arguments" capability of some other
@ -1706,7 +1706,7 @@ uses
the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
directory
of the SWIG distribution.
<H3><a name="Ruby_nn42"></a>26.6.8 Pointer handling</H3>
<H3><a name="Ruby_nn42"></a>27.6.8 Pointer handling</H3>
Occasionally, it might be necessary to convert pointer values that have
@ -1766,7 +1766,7 @@ typemap variable <tt>$1_descriptor</tt>. For example:
<blockquote>
<pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 1);<br>}<br></pre>
</blockquote>
<H4><a name="Ruby_nn43"></a>26.6.8.1 Ruby Datatype Wrapping</H4>
<H4><a name="Ruby_nn43"></a>27.6.8.1 Ruby Datatype Wrapping</H4>
<p>
@ -1790,7 +1790,7 @@ from the data object
<i>obj</i> and assigns that pointer to <i>ptr</i>.
</blockquote>
<hr>
<H2><a name="ruby_operator_overloading"></a>26.7 Operator overloading</H2>
<H2><a name="ruby_operator_overloading"></a>27.7 Operator overloading</H2>
SWIG allows operator overloading with, by using the <tt>%extend</tt>
@ -1805,7 +1805,7 @@ 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>.
<H3><a name="Ruby_nn45"></a>26.7.1 Example: STL Vector to Ruby Array</H3>
<H3><a name="Ruby_nn45"></a>27.7.1 Example: STL Vector to Ruby Array</H3>
<em><b>FIXME: This example is out of place here!</b></em>
@ -1861,10 +1861,10 @@ types:
}
%enddef
</pre></blockquote>
<H2><a name="Ruby_nn46"></a>26.8 Advanced Topics</H2>
<H2><a name="Ruby_nn46"></a>27.8 Advanced Topics</H2>
<H3><a name="Ruby_nn47"></a>26.8.1 Creating Multi-Module Packages</H3>
<H3><a name="Ruby_nn47"></a>27.8.1 Creating Multi-Module Packages</H3>
The chapter on <a href="Advanced.html#Advanced">Advanced Topics</a> discusses
@ -1954,7 +1954,7 @@ irb(main):005:0&gt; <b>c.getX()</b>
5.0
</pre>
</blockquote>
<H3><a name="Ruby_nn48"></a>26.8.2 Defining Aliases</H3>
<H3><a name="Ruby_nn48"></a>27.8.2 Defining Aliases</H3>
It's a fairly common practice in the Ruby built-ins and standard
@ -2000,7 +2000,7 @@ apply (see the chapter on <a href="Customization.html#Customization">"Customizat
Features"</a>)
for more details).
<H3><a name="Ruby_nn49"></a>26.8.3 Predicate Methods</H3>
<H3><a name="Ruby_nn49"></a>27.8.3 Predicate Methods</H3>
Predicate methods in Ruby are those which return either <tt>true</tt>
@ -2048,7 +2048,7 @@ SWIG's
kinds
of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details).
<H3><a name="Ruby_nn50"></a>26.8.4 Specifying Mixin Modules</H3>
<H3><a name="Ruby_nn50"></a>27.8.4 Specifying Mixin Modules</H3>
The Ruby language doesn't support multiple inheritance, but it does
@ -2098,7 +2098,7 @@ Note that the <tt>%mixin</tt> directive is implemented using SWIG's
kinds
of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
Features"</a>) for more details).
<H3><a name="Ruby_nn51"></a>26.8.5 Interacting with Ruby's Garbage Collector</H3>
<H3><a name="Ruby_nn51"></a>27.8.5 Interacting with Ruby's Garbage Collector</H3>
<b>This section is still unfinished!</b>

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

@ -6,7 +6,7 @@
<body bgcolor="#ffffff">
<H1><a name="Sections"></a>SWIG-1.3 Development Documentation</H1>
Last update : SWIG-1.3.22 (?? ??? 2004)
Last update : SWIG-1.3.22 (28 August 2004)
<H2>Sections</H2>

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

@ -5,7 +5,7 @@
</head>
<body bgcolor="#ffffff">
<H1><a name="Tcl"></a>27 SWIG and Tcl</H1>
<H1><a name="Tcl"></a>28 SWIG and Tcl</H1>
<!-- INDEX -->
<ul>
<li><a href="#Tcl_nn2">Preliminaries</a>
@ -77,7 +77,7 @@ Tcl 8.0 or a later release. Earlier releases of SWIG supported Tcl 7.x, but
this is no longer supported.
</p>
<H2><a name="Tcl_nn2"></a>27.1 Preliminaries</H2>
<H2><a name="Tcl_nn2"></a>28.1 Preliminaries</H2>
<p>
@ -103,7 +103,7 @@ build a Tcl extension module. To finish building the module, you
need to compile this file and link it with the rest of your program.
</p>
<H3><a name="Tcl_nn3"></a>27.1.1 Getting the right header files</H3>
<H3><a name="Tcl_nn3"></a>28.1.1 Getting the right header files</H3>
<p>
@ -119,7 +119,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.
<H3><a name="Tcl_nn4"></a>27.1.2 Compiling a dynamic module</H3>
<H3><a name="Tcl_nn4"></a>28.1.2 Compiling a dynamic module</H3>
<p>
@ -154,7 +154,7 @@ The name of the module is specified using the <tt>%module</tt> directive or the
<tt> -module</tt> command line option.
</p>
<H3><a name="Tcl_nn5"></a>27.1.3 Static linking</H3>
<H3><a name="Tcl_nn5"></a>28.1.3 Static linking</H3>
<p>
@ -218,7 +218,7 @@ minimal in most situations (and quite frankly not worth the extra
hassle in the opinion of this author).
</p>
<H3><a name="Tcl_nn6"></a>27.1.4 Using your module</H3>
<H3><a name="Tcl_nn6"></a>28.1.4 Using your module</H3>
<p>
@ -336,7 +336,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).
<H3><a name="Tcl_nn7"></a>27.1.5 Compilation of C++ extensions</H3>
<H3><a name="Tcl_nn7"></a>28.1.5 Compilation of C++ extensions</H3>
<p>
@ -419,7 +419,7 @@ erratic program behavior. If working with lots of software components, you
might want to investigate using a more formal standard such as COM.
</p>
<H3><a name="Tcl_nn8"></a>27.1.6 Compiling for 64-bit platforms</H3>
<H3><a name="Tcl_nn8"></a>28.1.6 Compiling for 64-bit platforms</H3>
<p>
@ -446,7 +446,7 @@ also introduce problems on platforms that support more than one
linking standard (e.g., -o32 and -n32 on Irix).
</p>
<H3><a name="Tcl_nn9"></a>27.1.7 Setting a package prefix</H3>
<H3><a name="Tcl_nn9"></a>28.1.7 Setting a package prefix</H3>
<p>
@ -465,7 +465,7 @@ option will append the prefix to the name when creating a command and
call it "<tt>Foo_bar</tt>".
</p>
<H3><a name="Tcl_nn10"></a>27.1.8 Using namespaces</H3>
<H3><a name="Tcl_nn10"></a>28.1.8 Using namespaces</H3>
<p>
@ -487,7 +487,7 @@ When the<tt> -namespace</tt> option is used, objects in the module
are always accessed with the namespace name such as <tt>Foo::bar</tt>.
</p>
<H2><a name="Tcl_nn11"></a>27.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<H2><a name="Tcl_nn11"></a>28.2 Building Tcl/Tk Extensions under Windows 95/NT</H2>
<p>
@ -498,7 +498,7 @@ covers the process of using SWIG with Microsoft Visual C++.
although the procedure may be similar with other compilers.
</p>
<H3><a name="Tcl_nn12"></a>27.2.1 Running SWIG from Developer Studio</H3>
<H3><a name="Tcl_nn12"></a>28.2.1 Running SWIG from Developer Studio</H3>
<p>
@ -556,7 +556,7 @@ MSDOS &gt; tclsh80
%
</pre></blockquote>
<H3><a name="Tcl_nn13"></a>27.2.2 Using NMAKE</H3>
<H3><a name="Tcl_nn13"></a>28.2.2 Using NMAKE</H3>
<p>
@ -619,7 +619,7 @@ to get you started. With a little practice, you'll be making lots of
Tcl extensions.
</p>
<H2><a name="Tcl_nn14"></a>27.3 A tour of basic C/C++ wrapping</H2>
<H2><a name="Tcl_nn14"></a>28.3 A tour of basic C/C++ wrapping</H2>
<p>
@ -630,7 +630,7 @@ classes. This section briefly covers the essential aspects of this
wrapping.
</p>
<H3><a name="Tcl_nn15"></a>27.3.1 Modules</H3>
<H3><a name="Tcl_nn15"></a>28.3.1 Modules</H3>
<p>
@ -662,7 +662,7 @@ To fix this, supply an extra argument to <tt>load</tt> like this:
</pre>
</blockquote>
<H3><a name="Tcl_nn16"></a>27.3.2 Functions</H3>
<H3><a name="Tcl_nn16"></a>28.3.2 Functions</H3>
<p>
@ -687,7 +687,7 @@ like you think it does:
%
</pre></blockquote>
<H3><a name="Tcl_nn17"></a>27.3.3 Global variables</H3>
<H3><a name="Tcl_nn17"></a>28.3.3 Global variables</H3>
C/C++ global variables are wrapped by Tcl global variables. For example:
@ -754,7 +754,7 @@ extern char *path; // Read-only (due to %immutable)
</pre>
</blockquote>
<H3><a name="Tcl_nn18"></a>27.3.4 Constants and enums</H3>
<H3><a name="Tcl_nn18"></a>28.3.4 Constants and enums</H3>
C/C++ constants are installed as global Tcl variables containing the
@ -830,7 +830,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.
<H3><a name="Tcl_nn19"></a>27.3.5 Pointers</H3>
<H3><a name="Tcl_nn19"></a>28.3.5 Pointers</H3>
C/C++ pointers are fully supported by SWIG. Furthermore, SWIG has no problem working with
@ -922,7 +922,7 @@ C-style cast may return a bogus result whereas as the C++-style cast will return
<tt>None</tt> if the conversion can't be performed.
</p>
<H3><a name="Tcl_nn20"></a>27.3.6 Structures</H3>
<H3><a name="Tcl_nn20"></a>28.3.6 Structures</H3>
<p>
@ -1176,7 +1176,7 @@ or
Note: Tcl only destroys the underlying object if it has ownership. See the
memory management section that appears shortly.
<H3><a name="Tcl_nn21"></a>27.3.7 C++ classes</H3>
<H3><a name="Tcl_nn21"></a>28.3.7 C++ classes</H3>
<p>
@ -1239,7 +1239,7 @@ In Tcl, the static member is accessed as follows:
</pre>
</blockquote>
<H3><a name="Tcl_nn22"></a>27.3.8 C++ inheritance</H3>
<H3><a name="Tcl_nn22"></a>28.3.8 C++ inheritance</H3>
SWIG is fully aware of issues related to C++ inheritance. Therefore, if you have
@ -1282,7 +1282,7 @@ For instance:
It is safe to use multiple inheritance with SWIG.
</p>
<H3><a name="Tcl_nn23"></a>27.3.9 Pointers, references, values, and arrays</H3>
<H3><a name="Tcl_nn23"></a>28.3.9 Pointers, references, values, and arrays</H3>
In C++, there are many different ways a function might receive
@ -1328,7 +1328,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).
<H3><a name="Tcl_nn24"></a>27.3.10 C++ overloaded functions</H3>
<H3><a name="Tcl_nn24"></a>28.3.10 C++ overloaded functions</H3>
C++ overloaded functions, methods, and constructors are mostly supported by SWIG. For example,
@ -1433,7 +1433,7 @@ first declaration takes precedence.
Please refer to the "SWIG and C++" chapter for more information about overloading.
</p>
<H3><a name="Tcl_nn25"></a>27.3.11 C++ operators</H3>
<H3><a name="Tcl_nn25"></a>28.3.11 C++ operators</H3>
Certain C++ overloaded operators can be handled automatically by SWIG. For example,
@ -1523,7 +1523,7 @@ Complex operator+(double, const Complex &amp;c);
There are ways to make this operator appear as part of the class using the <tt>%extend</tt> directive.
Keep reading.
<H3><a name="Tcl_nn26"></a>27.3.12 C++ namespaces</H3>
<H3><a name="Tcl_nn26"></a>28.3.12 C++ namespaces</H3>
SWIG is aware of C++ namespaces, but namespace names do not appear in
@ -1579,7 +1579,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.
<H3><a name="Tcl_nn27"></a>27.3.13 C++ templates</H3>
<H3><a name="Tcl_nn27"></a>28.3.13 C++ templates</H3>
C++ templates don't present a huge problem for SWIG. However, in order
@ -1625,7 +1625,7 @@ Obviously, there is more to template wrapping than shown in this example.
More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a> chapter. Some more complicated
examples will appear later.
<H3><a name="Tcl_nn28"></a>27.3.14 C++ Smart Pointers</H3>
<H3><a name="Tcl_nn28"></a>28.3.14 C++ Smart Pointers</H3>
In certain C++ programs, it is common to use classes that have been wrapped by
@ -1697,7 +1697,7 @@ simply use the <tt>__deref__()</tt> method. For example:
</pre>
</blockquote>
<H2><a name="Tcl_nn29"></a>27.4 Further details on the Tcl class interface</H2>
<H2><a name="Tcl_nn29"></a>28.4 Further details on the Tcl class interface</H2>
In the previous section, a high-level view of Tcl wrapping was
@ -1708,7 +1708,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.
<H3><a name="Tcl_nn30"></a>27.4.1 Proxy classes</H3>
<H3><a name="Tcl_nn30"></a>28.4.1 Proxy classes</H3>
In the <a href="SWIG.html#SWIG">"SWIG basics"</a> and <a href="SWIGPlus.html#SWIGPlus">"SWIG and C++"</a> chapters,
@ -1765,7 +1765,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.
<H3><a name="Tcl_nn31"></a>27.4.2 Memory management</H3>
<H3><a name="Tcl_nn31"></a>28.4.2 Memory management</H3>
<p>
@ -1939,7 +1939,7 @@ It is also possible to deal with situations like this using
typemaps--an advanced topic discussed later.
<H2><a name="Tcl_nn32"></a>27.5 Input and output parameters</H2>
<H2><a name="Tcl_nn32"></a>28.5 Input and output parameters</H2>
A common problem in some C programs is handling parameters passed as simple pointers. For
@ -2105,7 +2105,7 @@ set c [lindex $dim 1]
</pre>
</blockquote>
<H2><a name="Tcl_nn33"></a>27.6 Exception handling </H2>
<H2><a name="Tcl_nn33"></a>28.6 Exception handling </H2>
<p>
@ -2237,7 +2237,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">Customization Features</a>" for more examples.
<H2><a name="Tcl_nn34"></a>27.7 Typemaps</H2>
<H2><a name="Tcl_nn34"></a>28.7 Typemaps</H2>
<p>
@ -2254,7 +2254,7 @@ Typemaps are only used if you want to change some aspect of the primitive
C-Tcl interface.
</p>
<H3><a name="Tcl_nn35"></a>27.7.1 What is a typemap?</H3>
<H3><a name="Tcl_nn35"></a>28.7.1 What is a typemap?</H3>
<p>
@ -2361,7 +2361,7 @@ parameter is ommitted):
</pre>
</blockquote>
<H3><a name="Tcl_nn36"></a>27.7.2 Tcl typemaps</H3>
<H3><a name="Tcl_nn36"></a>28.7.2 Tcl typemaps</H3>
The previous section illustrated an "in" typemap for converting Tcl objects to C.
@ -2497,7 +2497,7 @@ Initialize an argument to a value before any conversions occur.
Examples of these methods will appear shortly.
</p>
<H3><a name="Tcl_nn37"></a>27.7.3 Typemap variables</H3>
<H3><a name="Tcl_nn37"></a>28.7.3 Typemap variables</H3>
<p>
@ -2568,7 +2568,7 @@ properly assigned.
The Tcl name of the wrapper function being created.
</blockquote>
<H3><a name="Tcl_nn38"></a>27.7.4 Converting a Tcl list to a char ** </H3>
<H3><a name="Tcl_nn38"></a>28.7.4 Converting a Tcl list to a char ** </H3>
<p>
@ -2630,7 +2630,7 @@ argv[2] = Larry
3
</pre></blockquote>
<H3><a name="Tcl_nn39"></a>27.7.5 Returning values in arguments</H3>
<H3><a name="Tcl_nn39"></a>28.7.5 Returning values in arguments</H3>
<p>
@ -2672,7 +2672,7 @@ result, a Tcl function using these typemaps will work like this :
%
</pre></blockquote>
<H3><a name="Tcl_nn40"></a>27.7.6 Useful functions</H3>
<H3><a name="Tcl_nn40"></a>28.7.6 Useful functions</H3>
<p>
@ -2747,7 +2747,7 @@ int Tcl_IsShared(Tcl_Obj *obj);
</pre>
</blockquote>
<H3><a name="Tcl_nn41"></a>27.7.7 Standard typemaps</H3>
<H3><a name="Tcl_nn41"></a>28.7.7 Standard typemaps</H3>
<p>
@ -2819,7 +2819,7 @@ work)
</pre>
</blockquote>
<H3><a name="Tcl_nn42"></a>27.7.8 Pointer handling</H3>
<H3><a name="Tcl_nn42"></a>28.7.8 Pointer handling</H3>
<p>
@ -2893,7 +2893,7 @@ For example:
</pre>
</blockquote>
<H2><a name="Tcl_nn43"></a>27.8 Turning a SWIG module into a Tcl Package.</H2>
<H2><a name="Tcl_nn43"></a>28.8 Turning a SWIG module into a Tcl Package.</H2>
Tcl 7.4 introduced the idea of an extension package. By default, SWIG
@ -2963,7 +2963,7 @@ As a final note, most SWIG examples do not yet use the
to use the <tt>load</tt> command instead.
</p>
<H2><a name="Tcl_nn44"></a>27.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<H2><a name="Tcl_nn44"></a>28.9 Building new kinds of Tcl interfaces (in Tcl)</H2>
<p>
@ -3062,7 +3062,7 @@ danger of blowing something up (although it is easily accomplished
with an out of bounds array access).
</p>
<H3><a name="Tcl_nn45"></a>27.9.1 Shadow classes</H3>
<H3><a name="Tcl_nn45"></a>28.9.1 Shadow classes</H3>
<p>