changes after maketoc.py was run
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@6039 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
parent
9196d9cb09
commit
92aac0f28d
22 changed files with 436 additions and 362 deletions
|
|
@ -5,132 +5,87 @@
|
|||
</head>
|
||||
<body bgcolor="#ffffff">
|
||||
<a name="n1"></a>
|
||||
<h1>23 SWIG and Ruby</h1>
|
||||
<a name="n1"></a><H1>23 SWIG and Ruby</H1>
|
||||
<!-- INDEX -->
|
||||
<ul>
|
||||
<li><a href="#n2">Preliminaries</a>
|
||||
<ul>
|
||||
<li><a href="#n3">Running SWIG</a>
|
||||
</li>
|
||||
<li><a href="#n4">Getting the right header files</a>
|
||||
</li>
|
||||
<li><a href="#n5">Compiling a dynamic module</a>
|
||||
</li>
|
||||
<li><a href="#n6">Using your module</a>
|
||||
</li>
|
||||
<li><a href="#n7">Static linking</a>
|
||||
</li>
|
||||
<li><a href="#n8">Compilation of C++ extensions</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n9">Building Ruby Extensions under Windows 95/NT</a>
|
||||
<ul>
|
||||
<li><a href="#n10">Running SWIG from Developer Studio</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n11">The Ruby-to-C/C++ Mapping</a>
|
||||
<ul>
|
||||
<li><a href="#n12">Modules</a>
|
||||
</li>
|
||||
<li><a href="#n13">Functions</a>
|
||||
</li>
|
||||
<li><a href="#n14">Variable Linking</a>
|
||||
</li>
|
||||
<li><a href="#n15">Constants</a>
|
||||
</li>
|
||||
<li><a href="#n16">Pointers</a>
|
||||
</li>
|
||||
<li><a href="#n17">Structures</a>
|
||||
</li>
|
||||
<li><a href="#n18">C++ classes</a>
|
||||
</li>
|
||||
<li><a href="#n19">C++ Inheritance</a>
|
||||
</li>
|
||||
<li><a href="#n20">C++ Overloaded Functions</a>
|
||||
</li>
|
||||
<li><a href="#n21">C++ Operators</a>
|
||||
</li>
|
||||
<li><a href="#n22">C++ namespaces</a>
|
||||
</li>
|
||||
<li><a href="#n23">C++ templates</a>
|
||||
</li>
|
||||
<li><a href="#n24">C++ Smart Pointers</a>
|
||||
</li>
|
||||
<li><a href="#n25">Cross-Language Polymorphism</a>
|
||||
<ul>
|
||||
<li><a href="#n26">Exception Unrolling</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n27">Input and output parameters</a>
|
||||
</li>
|
||||
<li><a href="#n28">Simple exception handling </a>
|
||||
</li>
|
||||
<li><a href="#n29">Typemaps</a>
|
||||
<ul>
|
||||
<li><a href="#n30">What is a typemap?</a>
|
||||
</li>
|
||||
<li><a href="#n31">Ruby typemaps</a>
|
||||
</li>
|
||||
<li><a href="#n32">Typemap variables</a>
|
||||
</li>
|
||||
<li><a href="#n33">Useful Functions</a>
|
||||
<ul>
|
||||
<li><a href="#n34">C Datatypes to Ruby Objects</a>
|
||||
</li>
|
||||
<li><a href="#n35">Ruby Objects to C Datatypes</a>
|
||||
</li>
|
||||
<li><a href="#n36">Macros for VALUE</a>
|
||||
</li>
|
||||
<li><a href="#n37">Exceptions</a>
|
||||
</li>
|
||||
<li><a href="#n38">Iterators</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n39">Typemap Examples</a>
|
||||
</li>
|
||||
<li><a href="#n40">Converting a Ruby array to a char **</a>
|
||||
</li>
|
||||
<li><a href="#n41">Collecting arguments in a hash</a>
|
||||
</li>
|
||||
<li><a href="#n42">Pointer handling</a>
|
||||
<ul>
|
||||
<li><a href="#n43">Ruby Datatype Wrapping</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n44">Operator overloading</a>
|
||||
<ul>
|
||||
<li><a href="#n45">Example: STL Vector to Ruby Array</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n46">Advanced Topics</a>
|
||||
<ul>
|
||||
<li><a href="#n47">Creating Multi-Module Packages</a>
|
||||
</li>
|
||||
<li><a href="#n48">Defining Aliases</a>
|
||||
</li>
|
||||
<li><a href="#n49">Predicate Methods</a>
|
||||
</li>
|
||||
<li><a href="#n50">Specifying Mixin Modules</a>
|
||||
</li>
|
||||
<li><a href="#n51">Interacting with Ruby's Garbage Collector</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#n2">Preliminaries</a>
|
||||
<ul>
|
||||
<li><a href="#n3">Running SWIG</a>
|
||||
<li><a href="#n4">Getting the right header files</a>
|
||||
<li><a href="#n5">Compiling a dynamic module</a>
|
||||
<li><a href="#n6">Using your module</a>
|
||||
<li><a href="#n7">Static linking</a>
|
||||
<li><a href="#n8">Compilation of C++ extensions</a>
|
||||
</ul>
|
||||
<li><a href="#n9">Building Ruby Extensions under Windows 95/NT</a>
|
||||
<ul>
|
||||
<li><a href="#n10">Running SWIG from Developer Studio</a>
|
||||
</ul>
|
||||
<li><a href="#n11">The Ruby-to-C/C++ Mapping</a>
|
||||
<ul>
|
||||
<li><a href="#n12">Modules</a>
|
||||
<li><a href="#n13">Functions</a>
|
||||
<li><a href="#n14">Variable Linking</a>
|
||||
<li><a href="#n15">Constants</a>
|
||||
<li><a href="#n16">Pointers</a>
|
||||
<li><a href="#n17">Structures</a>
|
||||
<li><a href="#n18">C++ classes</a>
|
||||
<li><a href="#n19">C++ Inheritance</a>
|
||||
<li><a href="#n20">C++ Overloaded Functions</a>
|
||||
<li><a href="#n21">C++ Operators</a>
|
||||
<li><a href="#n22">C++ namespaces</a>
|
||||
<li><a href="#n23">C++ templates</a>
|
||||
<li><a href="#n24">C++ Smart Pointers</a>
|
||||
<li><a href="#n25">Cross-Language Polymorphism</a>
|
||||
<ul>
|
||||
<li><a href="#n26">Exception Unrolling</a>
|
||||
</ul>
|
||||
</ul>
|
||||
<li><a href="#n27">Input and output parameters</a>
|
||||
<li><a href="#n28">Simple exception handling </a>
|
||||
<li><a href="#n29">Typemaps</a>
|
||||
<ul>
|
||||
<li><a href="#n30">What is a typemap?</a>
|
||||
<li><a href="#n31">Ruby typemaps</a>
|
||||
<li><a href="#n32">Typemap variables</a>
|
||||
<li><a href="#n33">Useful Functions</a>
|
||||
<ul>
|
||||
<li><a href="#n34">C Datatypes to Ruby Objects</a>
|
||||
<li><a href="#n35">Ruby Objects to C Datatypes</a>
|
||||
<li><a href="#n36">Macros for VALUE</a>
|
||||
<li><a href="#n37">Exceptions</a>
|
||||
<li><a href="#n38">Iterators</a>
|
||||
</ul>
|
||||
<li><a href="#n39">Typemap Examples</a>
|
||||
<li><a href="#n40">Converting a Ruby array to a char **</a>
|
||||
<li><a href="#n41">Collecting arguments in a hash</a>
|
||||
<li><a href="#n42">Pointer handling</a>
|
||||
<ul>
|
||||
<li><a href="#n43">Ruby Datatype Wrapping</a>
|
||||
</ul>
|
||||
</ul>
|
||||
<li><a href="#n44">Operator overloading</a>
|
||||
<ul>
|
||||
<li><a href="#n45">Example: STL Vector to Ruby Array</a>
|
||||
</ul>
|
||||
<li><a href="#n46">Advanced Topics</a>
|
||||
<ul>
|
||||
<li><a href="#n47">Creating Multi-Module Packages</a>
|
||||
<li><a href="#n48">Defining Aliases</a>
|
||||
<li><a href="#n49">Predicate Methods</a>
|
||||
<li><a href="#n50">Specifying Mixin Modules</a>
|
||||
<li><a href="#n51">Interacting with Ruby's Garbage Collector</a>
|
||||
</ul>
|
||||
</ul>
|
||||
<!-- INDEX -->
|
||||
|
||||
|
||||
|
||||
<p>This chapter describes SWIG's support of Ruby. </p>
|
||||
<hr><a name="n2"></a>
|
||||
<h2>23.1 Preliminaries</h2>
|
||||
<a name="n2"></a><H2>23.1 Preliminaries</H2>
|
||||
|
||||
|
||||
SWIG 1.3 is known to work with Ruby versions 1.6 and later. Given the
|
||||
choice, you should
|
||||
use the latest stable version of Ruby. You should also determine if
|
||||
|
|
@ -145,7 +100,9 @@ earlier chapters. At the very least, make sure you also read the "<a
|
|||
reader
|
||||
has a basic understanding of Ruby.
|
||||
<a name="n3"></a></p>
|
||||
<h3>23.1.1 Running SWIG</h3>
|
||||
<a name="n3"></a><H3>23.1.1 Running SWIG</H3>
|
||||
|
||||
|
||||
<p>
|
||||
To build a Ruby module, run SWIG using the <tt>-ruby</tt> option:</p>
|
||||
<p></p>
|
||||
|
|
@ -169,7 +126,9 @@ Ruby extension module. To finish building the module, you need to
|
|||
compile this
|
||||
file and link it with the rest of your program.
|
||||
<a name="n4"></a></p>
|
||||
<h3>23.1.2 Getting the right header files</h3>
|
||||
<a name="n4"></a><H3>23.1.2 Getting the right header files</H3>
|
||||
|
||||
|
||||
In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
|
||||
header file. This file is usually contained in a directory such as
|
||||
<p></p>
|
||||
|
|
@ -191,7 +150,9 @@ can run Ruby to find out. For example:
|
|||
</pre>
|
||||
</blockquote>
|
||||
<a name="n5"></a>
|
||||
<h3>23.1.3 Compiling a dynamic module</h3>
|
||||
<a name="n5"></a><H3>23.1.3 Compiling a dynamic module</H3>
|
||||
|
||||
|
||||
Ruby extension modules are typically compiled into shared libraries
|
||||
that the
|
||||
interpreter loads dynamically at runtime. Since the exact commands for
|
||||
|
|
@ -249,7 +210,9 @@ 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>23.1.4 Using your module</h3>
|
||||
<a name="n6"></a><H3>23.1.4 Using your module</H3>
|
||||
|
||||
|
||||
Ruby <i>module</i> names must be capitalized, but the convention for
|
||||
Ruby
|
||||
<i>feature</i> names is to use lowercase names. So, for example, the <b>Etc</b>
|
||||
|
|
@ -263,7 +226,9 @@ extension. So for example, a SWIG interface file that begins with:
|
|||
will result in an extension module using the feature name "example" and
|
||||
Ruby module name "Example".
|
||||
<a name="n7"></a>
|
||||
<h3>23.1.5 Static linking</h3>
|
||||
<a name="n7"></a><H3>23.1.5 Static linking</H3>
|
||||
|
||||
|
||||
An alternative approach to dynamic linking is to rebuild the Ruby
|
||||
interpreter with your extension module added to it. In the past,
|
||||
this approach was sometimes necessary due to limitations in dynamic
|
||||
|
|
@ -278,7 +243,9 @@ adding your directory to the list of extensions in the file, and
|
|||
finally rebuilding Ruby.
|
||||
</p>
|
||||
<p><a name="n8"></a></p>
|
||||
<h3>23.1.6 Compilation of C++ extensions</h3>
|
||||
<a name="n8"></a><H3>23.1.6 Compilation of C++ extensions</H3>
|
||||
|
||||
|
||||
<p>
|
||||
On most machines, C++ extension modules should be linked using the C++
|
||||
compiler. For example:
|
||||
|
|
@ -310,7 +277,9 @@ into your extension, e.g.
|
|||
</blockquote>
|
||||
<hr>
|
||||
<a name="n9"></a>
|
||||
<h2>23.2 Building Ruby Extensions under Windows 95/NT</h2>
|
||||
<a name="n9"></a><H2>23.2 Building Ruby Extensions under Windows 95/NT</H2>
|
||||
|
||||
|
||||
Building a SWIG extension to Ruby under Windows 95/NT is roughly
|
||||
similar to the
|
||||
process used with Unix. Normally, you will want to produce a DLL that
|
||||
|
|
@ -337,7 +306,9 @@ 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>23.2.1 Running SWIG from Developer Studio</h3>
|
||||
<a name="n10"></a><H3>23.2.1 Running SWIG from Developer Studio</H3>
|
||||
|
||||
|
||||
If you are developing your application within Microsoft developer
|
||||
studio, SWIG
|
||||
can be invoked as a custom build option. The process roughly follows
|
||||
|
|
@ -426,12 +397,16 @@ Foo = 3.0
|
|||
<p>
|
||||
</p>
|
||||
<hr><a name="n11"></a>
|
||||
<h2>23.3 The Ruby-to-C/C++ Mapping</h2>
|
||||
<a name="n11"></a><H2>23.3 The Ruby-to-C/C++ Mapping</H2>
|
||||
|
||||
|
||||
This section describes the basics of how SWIG maps C or C++
|
||||
declarations
|
||||
in your SWIG interface files to Ruby constructs.
|
||||
<a name="n12"></a>
|
||||
<h3>23.3.1 Modules</h3>
|
||||
<a name="n12"></a><H3>23.3.1 Modules</H3>
|
||||
|
||||
|
||||
The SWIG <tt>%module</tt> directive specifies the name of the Ruby
|
||||
module. If
|
||||
you specify:
|
||||
|
|
@ -489,7 +464,9 @@ take care that the names of your constants, classes and methods don't
|
|||
conflict
|
||||
with any of Ruby's built-in names.
|
||||
<a name="n13"></a></p>
|
||||
<h3>23.3.2 Functions</h3>
|
||||
<a name="n13"></a><H3>23.3.2 Functions</H3>
|
||||
|
||||
|
||||
Global functions are wrapped as Ruby module methods. For example, given
|
||||
the SWIG interface file <tt>example.i</tt>:
|
||||
<p></p>
|
||||
|
|
@ -513,7 +490,9 @@ irb(main):002:0> <b>Example.fact(4)</b>
|
|||
</pre>
|
||||
</blockquote>
|
||||
<a name="n14"></a>
|
||||
<h3>23.3.3 Variable Linking</h3>
|
||||
<a name="n14"></a><H3>23.3.3 Variable Linking</H3>
|
||||
|
||||
|
||||
C/C++ global variables are wrapped as a pair of singleton methods for
|
||||
the
|
||||
module: one to get the value of the global variable and one to set it.
|
||||
|
|
@ -565,7 +544,9 @@ The <tt>%immutable</tt> directive stays in effect until it is
|
|||
explicitly
|
||||
disabled using <tt>%mutable</tt>.
|
||||
<a name="n15"></a>
|
||||
<h3>23.3.4 Constants</h3>
|
||||
<a name="n15"></a><H3>23.3.4 Constants</H3>
|
||||
|
||||
|
||||
C/C++ constants are wrapped as module constants initialized to the
|
||||
appropriate value. To create a constant, use <tt>#define</tt> or the
|
||||
<tt>%constant</tt> directive. For example:
|
||||
|
|
@ -584,7 +565,9 @@ irb(main):002:0> <b>Example::PI</b>
|
|||
</pre>
|
||||
</blockquote>
|
||||
<a name="n16"></a>
|
||||
<h3>23.3.5 Pointers</h3>
|
||||
<a name="n16"></a><H3>23.3.5 Pointers</H3>
|
||||
|
||||
|
||||
"Opaque" pointers to arbitrary C/C++ types (i.e. types that aren't
|
||||
explicitly
|
||||
declared in your SWIG interface file) are wrapped as data objects. So,
|
||||
|
|
@ -605,7 +588,9 @@ internally generated Ruby class:
|
|||
A <tt>NULL</tt> pointer is always represented by the Ruby <tt>nil</tt>
|
||||
object.
|
||||
<a name="n17"></a>
|
||||
<h3>23.3.6 Structures</h3>
|
||||
<a name="n17"></a><H3>23.3.6 Structures</H3>
|
||||
|
||||
|
||||
C/C++ structs are wrapped as Ruby classes, with accessor methods (i.e.
|
||||
"getters"
|
||||
and "setters") for all of the struct members. For example, this struct
|
||||
|
|
@ -684,7 +669,9 @@ generates accessor functions such as this:
|
|||
<pre>Foo *Bar_f_get(Bar *b) {<br> return &b->f;<br>}<br><br>void Bar_f_set(Bar *b, Foo *val) {<br> b->f = *val;<br>}<br></pre>
|
||||
</blockquote>
|
||||
<a name="n18"></a>
|
||||
<h3>23.3.7 C++ classes</h3>
|
||||
<a name="n18"></a><H3>23.3.7 C++ classes</H3>
|
||||
|
||||
|
||||
Like structs, C++ classes are wrapped by creating a new Ruby class of
|
||||
the same
|
||||
name with accessor methods for the public class member data.
|
||||
|
|
@ -719,7 +706,9 @@ In Ruby, these functions are used as follows:
|
|||
<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>
|
||||
<a name="n19"></a>
|
||||
<h3>23.3.8 C++ Inheritance</h3>
|
||||
<a name="n19"></a><H3>23.3.8 C++ Inheritance</H3>
|
||||
|
||||
|
||||
The SWIG type-checker is fully aware of C++ inheritance. Therefore, if
|
||||
you have
|
||||
classes like this:
|
||||
|
|
@ -831,7 +820,9 @@ and <tt>Base2</tt>
|
|||
(i.e. they exhibit <a href="http://c2.com/cgi/wiki?DuckTyping">"Duck
|
||||
Typing"</a>).
|
||||
<a name="n20"></a>
|
||||
<h3>23.3.9 C++ Overloaded Functions</h3>
|
||||
<a name="n20"></a><H3>23.3.9 C++ Overloaded Functions</H3>
|
||||
|
||||
|
||||
C++ overloaded functions, methods, and constructors are mostly
|
||||
supported by SWIG. For example,
|
||||
if you have two functions like this:
|
||||
|
|
@ -883,7 +874,9 @@ arises--in this case, the
|
|||
first declaration takes precedence.
|
||||
<p>Please refer to the <a href="SWIGPlus.html">"SWIG and C++"</a>
|
||||
chapter for more information about overloading. <a name="n21"></a></p>
|
||||
<h3>23.3.10 C++ Operators</h3>
|
||||
<a name="n21"></a><H3>23.3.10 C++ Operators</H3>
|
||||
|
||||
|
||||
For the most part, overloaded operators are handled automatically by
|
||||
SWIG
|
||||
and do not require any special treatment on your part. So if your class
|
||||
|
|
@ -912,7 +905,9 @@ More details about wrapping C++ operators into Ruby operators is
|
|||
discussed in
|
||||
the <a href="#n39">section on operator overloading</a>.
|
||||
<a name="n22"></a>
|
||||
<h3>23.3.11 C++ namespaces</h3>
|
||||
<a name="n22"></a><H3>23.3.11 C++ namespaces</H3>
|
||||
|
||||
|
||||
SWIG is aware of C++ namespaces, but namespace names do not appear in
|
||||
the module nor do namespaces result in a module that is broken up into
|
||||
submodules or packages. For example, if you have a file like this,
|
||||
|
|
@ -946,7 +941,9 @@ extension modules for each namespace separately. If your program
|
|||
utilizes thousands of small deeply nested namespaces each with
|
||||
identical symbol names, well, then you get what you deserve.
|
||||
<a name="n23"></a>
|
||||
<h3>23.3.12 C++ templates</h3>
|
||||
<a name="n23"></a><H3>23.3.12 C++ templates</H3>
|
||||
|
||||
|
||||
C++ templates don't present a huge problem for SWIG. However, in order
|
||||
to create wrappers, you have to tell SWIG to create wrappers for a
|
||||
particular
|
||||
|
|
@ -1000,7 +997,9 @@ examples.
|
|||
More details can be found in the <a href="SWIGPlus.html">SWIG and C++</a>
|
||||
chapter.
|
||||
<a name="n24"></a>
|
||||
<h3>23.3.13 C++ Smart Pointers</h3>
|
||||
<a name="n24"></a><H3>23.3.13 C++ Smart Pointers</H3>
|
||||
|
||||
|
||||
In certain C++ programs, it is common to use classes that have been
|
||||
wrapped by
|
||||
so-called "smart pointers." Generally, this involves the use of a
|
||||
|
|
@ -1036,7 +1035,9 @@ simply use the <tt>__deref__()</tt> method. For example:
|
|||
<pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre>
|
||||
</blockquote>
|
||||
<a name="n25"></a>
|
||||
<h3>23.3.14 Cross-Language Polymorphism</h3>
|
||||
<a name="n25"></a><H3>23.3.14 Cross-Language Polymorphism</H3>
|
||||
|
||||
|
||||
SWIG's Ruby module supports cross-language polymorphism (a.k.a. the
|
||||
"directors"
|
||||
feature) similar to that for SWIG's Python module. Rather than
|
||||
|
|
@ -1047,7 +1048,9 @@ secton just notes the differences that you need to be aware of when
|
|||
using this
|
||||
feature with Ruby.
|
||||
<a name="n26"></a>
|
||||
<h4>23.3.14.1 Exception Unrolling</h4>
|
||||
<a name="n26"></a><H4>23.3.14.1 Exception Unrolling</H4>
|
||||
|
||||
|
||||
Whenever a C++ director class routes one of its virtual member function
|
||||
calls to a
|
||||
Ruby instance method, there's always the possibility that an exception
|
||||
|
|
@ -1070,7 +1073,9 @@ Ruby exception
|
|||
is raised, it will be caught here and a C++ exception is raised in its
|
||||
place.
|
||||
<hr><a name="n27"></a>
|
||||
<h2>23.4 Input and output parameters</h2>
|
||||
<a name="n27"></a><H2>23.4 Input and output parameters</H2>
|
||||
|
||||
|
||||
A common problem in some C programs is handling parameters passed as
|
||||
simple
|
||||
pointers. For example:
|
||||
|
|
@ -1144,7 +1149,9 @@ In Ruby:
|
|||
</blockquote>
|
||||
<hr>
|
||||
<a name="n28"></a>
|
||||
<h2>23.5 Simple exception handling </h2>
|
||||
<a name="n28"></a><H2>23.5 Simple exception handling </H2>
|
||||
|
||||
|
||||
The SWIG <tt>%exception</tt> directive can be used to define a
|
||||
user-definable
|
||||
exception handler that can convert C/C++ errors into Ruby exceptions.
|
||||
|
|
@ -1197,7 +1204,9 @@ 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>23.6 Typemaps</h2>
|
||||
<a name="n29"></a><H2>23.6 Typemaps</H2>
|
||||
|
||||
|
||||
This section describes how you can modify SWIG's default wrapping
|
||||
behavior
|
||||
for various C/C++ datatypes using the <tt>%typemap</tt> directive.
|
||||
|
|
@ -1212,7 +1221,9 @@ Typemaps are only used if you want to change some aspect of the
|
|||
primitive
|
||||
C-Ruby interface.
|
||||
<a name="n30"></a></p>
|
||||
<h3>23.6.1 What is a typemap?</h3>
|
||||
<a name="n30"></a><H3>23.6.1 What is a typemap?</H3>
|
||||
|
||||
|
||||
A typemap is nothing more than a code generation rule that is attached
|
||||
to a specific C datatype. For example, to convert integers from Ruby to
|
||||
C,
|
||||
|
|
@ -1292,7 +1303,9 @@ follows (notice how the length parameter is omitted):
|
|||
<pre>puts Example.count('o','Hello World')<br>2<br></pre>
|
||||
</blockquote>
|
||||
<a name="n31"></a>
|
||||
<h3>23.6.2 Ruby typemaps</h3>
|
||||
<a name="n31"></a><H3>23.6.2 Ruby typemaps</H3>
|
||||
|
||||
|
||||
The previous section illustrated an "in" typemap for converting Ruby
|
||||
objects to
|
||||
C. A variety of different typemap methods are defined by the Ruby
|
||||
|
|
@ -1348,7 +1361,9 @@ Examples of these typemaps appears in the <a href="#n34">section on
|
|||
typemap
|
||||
examples</a>
|
||||
<a name="n32"></a>
|
||||
<h3>23.6.3 Typemap variables</h3>
|
||||
<a name="n32"></a><H3>23.6.3 Typemap variables</H3>
|
||||
|
||||
|
||||
Within a typemap, a number of special variables prefaced with a <tt>$</tt>
|
||||
may appear. A full list of variables can be found in the "<a
|
||||
href="Typemaps.html">Typemaps</a>" chapter. This is a list of the most
|
||||
|
|
@ -1390,7 +1405,9 @@ so that their values can be properly assigned.
|
|||
<blockquote>The Ruby name of the wrapper function being created.
|
||||
</blockquote>
|
||||
<a name="n33"></a>
|
||||
<h3>23.6.4 Useful Functions</h3>
|
||||
<a name="n33"></a><H3>23.6.4 Useful Functions</H3>
|
||||
|
||||
|
||||
When you write a typemap, you usually have to work directly with Ruby
|
||||
objects.
|
||||
The following functions may prove to be useful. (These functions plus
|
||||
|
|
@ -1399,17 +1416,23 @@ 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>23.6.4.1 C Datatypes to Ruby Objects</h4>
|
||||
<a name="n34"></a><H4>23.6.4.1 C Datatypes to Ruby Objects</H4>
|
||||
|
||||
|
||||
<blockquote>
|
||||
<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>
|
||||
<a name="n35"></a>
|
||||
<h4>23.6.4.2 Ruby Objects to C Datatypes</h4>
|
||||
<a name="n35"></a><H4>23.6.4.2 Ruby Objects to C Datatypes</H4>
|
||||
|
||||
|
||||
<blockquote>
|
||||
<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>
|
||||
<a name="n36"></a>
|
||||
<h4>23.6.4.3 Macros for VALUE</h4>
|
||||
<a name="n36"></a><H4>23.6.4.3 Macros for VALUE</H4>
|
||||
|
||||
|
||||
<p>
|
||||
<tt>RSTRING(str)->len</tt>
|
||||
</p>
|
||||
|
|
@ -1423,7 +1446,9 @@ and Andrew Hunt.)
|
|||
<tt>RARRAY(arr)->ptr</tt>
|
||||
<blockquote>pointer to array storage</blockquote>
|
||||
<a name="n37"></a>
|
||||
<h4>23.6.4.4 Exceptions</h4>
|
||||
<a name="n37"></a><H4>23.6.4.4 Exceptions</H4>
|
||||
|
||||
|
||||
<p>
|
||||
<tt>void rb_raise(VALUE exception, const char *fmt, ...)</tt>
|
||||
</p>
|
||||
|
|
@ -1480,7 +1505,9 @@ 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>
|
||||
<a name="n38"></a>
|
||||
<h4>23.6.4.5 Iterators</h4>
|
||||
<a name="n38"></a><H4>23.6.4.5 Iterators</H4>
|
||||
|
||||
|
||||
<p>
|
||||
<tt>void rb_iter_break()</tt>
|
||||
</p>
|
||||
|
|
@ -1512,12 +1539,16 @@ value)</tt>
|
|||
<blockquote> Equivalent to Ruby's <tt>throw</tt>.
|
||||
</blockquote>
|
||||
<a name="n39"></a>
|
||||
<h3>23.6.5 Typemap Examples</h3>
|
||||
<a name="n39"></a><H3>23.6.5 Typemap Examples</H3>
|
||||
|
||||
|
||||
This section includes a few examples of typemaps. For more examples,
|
||||
you
|
||||
might look at the examples in the <tt>Example/ruby</tt> directory.
|
||||
<a name="n40"></a>
|
||||
<h3>23.6.6 Converting a Ruby array to a char **</h3>
|
||||
<a name="n40"></a><H3>23.6.6 Converting a Ruby array to a char **</H3>
|
||||
|
||||
|
||||
A common problem in many C programs is the processing of command line
|
||||
arguments, which are usually passed in an array of <tt>NULL</tt>
|
||||
terminated
|
||||
|
|
@ -1543,7 +1574,9 @@ 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>23.6.7 Collecting arguments in a hash</h3>
|
||||
<a name="n41"></a><H3>23.6.7 Collecting arguments in a hash</H3>
|
||||
|
||||
|
||||
Ruby's solution to the "keyword arguments" capability of some other
|
||||
languages is
|
||||
to allow the programmer to pass in one or more key-value pairs as
|
||||
|
|
@ -1681,7 +1714,9 @@ the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
|
|||
directory
|
||||
of the SWIG distribution.
|
||||
<a name="n42"></a>
|
||||
<h3>23.6.8 Pointer handling</h3>
|
||||
<a name="n42"></a><H3>23.6.8 Pointer handling</H3>
|
||||
|
||||
|
||||
Occasionally, it might be necessary to convert pointer values that have
|
||||
been
|
||||
stored using the SWIG typed-pointer representation. Since there are
|
||||
|
|
@ -1740,7 +1775,9 @@ typemap variable <tt>$1_descriptor</tt>. For example:
|
|||
<pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);<br>}<br></pre>
|
||||
</blockquote>
|
||||
<a name="n43"></a>
|
||||
<h4>23.6.8.1 Ruby Datatype Wrapping</h4>
|
||||
<a name="n43"></a><H4>23.6.8.1 Ruby Datatype Wrapping</H4>
|
||||
|
||||
|
||||
<p>
|
||||
<tt>VALUE Data_Wrap_Struct(VALUE class, void (*mark)(void *), void
|
||||
(*free)(void *), void *ptr)</tt>
|
||||
|
|
@ -1763,7 +1800,9 @@ from the data object
|
|||
</blockquote>
|
||||
<hr>
|
||||
<a name="n44"></a>
|
||||
<h2>23.7 Operator overloading</h2>
|
||||
<a name="n44"></a><H2>23.7 Operator overloading</H2>
|
||||
|
||||
|
||||
SWIG allows operator overloading with, by using the <tt>%extend</tt>
|
||||
or
|
||||
<tt>%rename</tt> commands in SWIG and the following operator names
|
||||
|
|
@ -1777,7 +1816,9 @@ for defining an equivalence operator, there is no separate method for
|
|||
handling <i>inequality</i> since Ruby parses the expression <i>a != b</i>
|
||||
as <i>!(a == b)</i>.
|
||||
<a name="n45"></a>
|
||||
<h3>23.7.1 Example: STL Vector to Ruby Array</h3>
|
||||
<a name="n45"></a><H3>23.7.1 Example: STL Vector to Ruby Array</H3>
|
||||
|
||||
|
||||
<em><b>FIXME: This example is out of place here!</b></em>
|
||||
<p>Another use for macros and type maps is to create a Ruby array from
|
||||
a STL
|
||||
|
|
@ -1831,9 +1872,13 @@ types:
|
|||
%enddef
|
||||
</blockquote></pre>
|
||||
<a name="n46"></a>
|
||||
<h2>23.8 Advanced Topics</h2>
|
||||
<a name="n46"></a><H2>23.8 Advanced Topics</H2>
|
||||
|
||||
|
||||
<a name="n47"></a>
|
||||
<h3>23.8.1 Creating Multi-Module Packages</h3>
|
||||
<a name="n47"></a><H3>23.8.1 Creating Multi-Module Packages</H3>
|
||||
|
||||
|
||||
The chapter on <a href="Advanced.html">Advanced Topics</a> discusses
|
||||
the basics
|
||||
of creating multi-module extensions with SWIG, and in particular
|
||||
|
|
@ -1922,7 +1967,9 @@ irb(main):005:0> <b>c.getX()</b>
|
|||
</pre>
|
||||
</blockquote>
|
||||
<a name="n48"></a>
|
||||
<h3>23.8.2 Defining Aliases</h3>
|
||||
<a name="n48"></a><H3>23.8.2 Defining Aliases</H3>
|
||||
|
||||
|
||||
It's a fairly common practice in the Ruby built-ins and standard
|
||||
library to
|
||||
provide aliases for method names. For example, <em>Array#size</em> is
|
||||
|
|
@ -1966,7 +2013,9 @@ apply (see the chapter on <a href="Customization.html">"Customization
|
|||
Features"</a>)
|
||||
for more details).
|
||||
<a name="n49"></a></p>
|
||||
<h3>23.8.3 Predicate Methods</h3>
|
||||
<a name="n49"></a><H3>23.8.3 Predicate Methods</H3>
|
||||
|
||||
|
||||
Predicate methods in Ruby are those which return either <tt>true</tt>
|
||||
or
|
||||
<tt>false</tt>. By convention, these methods' names end in a question
|
||||
|
|
@ -2013,7 +2062,9 @@ kinds
|
|||
of features apply (see the chapter on <a href="Customization.html">"Customization
|
||||
Features"</a>) for more details).
|
||||
<a name="n50"></a>
|
||||
<h3>23.8.4 Specifying Mixin Modules</h3>
|
||||
<a name="n50"></a><H3>23.8.4 Specifying Mixin Modules</H3>
|
||||
|
||||
|
||||
The Ruby language doesn't support multiple inheritance, but it does
|
||||
allow you
|
||||
to mix one or more modules into a class using Ruby's <tt>include</tt>
|
||||
|
|
@ -2062,7 +2113,9 @@ kinds
|
|||
of features apply (see the chapter on <a href="Customization.html">"Customization
|
||||
Features"</a>) for more details).
|
||||
<a name="n51"></a>
|
||||
<h3>23.8.5 Interacting with Ruby's Garbage Collector</h3>
|
||||
<a name="n51"></a><H3>23.8.5 Interacting with Ruby's Garbage Collector</H3>
|
||||
|
||||
|
||||
<b>This section is still unfinished!</b>
|
||||
<p>By default, SWIG ensures that any C++ objects it creates are
|
||||
destroyed when the
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue