Update html chapter numbering for added Doxygen chapter
This commit is contained in:
William S Fulton
parent
62814e4ab7
commit
4cdca98709
31 changed files with 1062 additions and 1039 deletions
|
|
@ -8,7 +8,7 @@
|
|||
|
||||
<body bgcolor="#ffffff">
|
||||
|
||||
<H1><a name="Ruby">39 SWIG and Ruby</a></H1>
|
||||
<H1><a name="Ruby">40 SWIG and Ruby</a></H1>
|
||||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
|
|
@ -149,7 +149,7 @@
|
|||
|
||||
<p>This chapter describes SWIG's support of Ruby.</p>
|
||||
|
||||
<H2><a name="Ruby_nn2">39.1 Preliminaries</a></H2>
|
||||
<H2><a name="Ruby_nn2">40.1 Preliminaries</a></H2>
|
||||
|
||||
|
||||
<p> SWIG 3.0 is known to work with Ruby versions 1.8 and later.
|
||||
|
|
@ -164,7 +164,7 @@ read the "<a href="SWIG.html#SWIG">SWIG Basics</a>"
|
|||
chapter. It is also assumed that the reader has a basic understanding
|
||||
of Ruby. </p>
|
||||
|
||||
<H3><a name="Ruby_nn3">39.1.1 Running SWIG</a></H3>
|
||||
<H3><a name="Ruby_nn3">40.1.1 Running SWIG</a></H3>
|
||||
|
||||
|
||||
<p> To build a Ruby module, run SWIG using the <tt>-ruby</tt>
|
||||
|
|
@ -188,7 +188,7 @@ if compiling a C++ extension) that contains all of the code needed to
|
|||
build a Ruby extension module. To finish building the module, you need
|
||||
to compile this file and link it with the rest of your program. </p>
|
||||
|
||||
<H3><a name="Ruby_nn4">39.1.2 Getting the right header files</a></H3>
|
||||
<H3><a name="Ruby_nn4">40.1.2 Getting the right header files</a></H3>
|
||||
|
||||
|
||||
<p> In order to compile the wrapper code, the compiler needs the <tt>ruby.h</tt>
|
||||
|
|
@ -202,7 +202,7 @@ the compiler options needed to compile the code is to ask Ruby itself:</p>
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn5">39.1.3 Compiling a dynamic module</a></H3>
|
||||
<H3><a name="Ruby_nn5">40.1.3 Compiling a dynamic module</a></H3>
|
||||
|
||||
|
||||
<p> Ruby extension modules are typically compiled into shared
|
||||
|
|
@ -275,7 +275,7 @@ manual pages for your compiler and linker to determine the correct set
|
|||
of options. You might also check the <a href="https://github.com/swig/swig/wiki">SWIG Wiki</a>
|
||||
for additional information. </p>
|
||||
|
||||
<H3><a name="Ruby_nn6">39.1.4 Using your module</a></H3>
|
||||
<H3><a name="Ruby_nn6">40.1.4 Using your module</a></H3>
|
||||
|
||||
|
||||
<p> Ruby <i>module</i> names must be capitalized,
|
||||
|
|
@ -305,7 +305,7 @@ begins with: </p>
|
|||
<p> will result in an extension module using the feature name
|
||||
"example" and Ruby module name "Example". </p>
|
||||
|
||||
<H3><a name="Ruby_nn7">39.1.5 Static linking</a></H3>
|
||||
<H3><a name="Ruby_nn7">40.1.5 Static linking</a></H3>
|
||||
|
||||
|
||||
<p> An alternative approach to dynamic linking is to rebuild the
|
||||
|
|
@ -320,7 +320,7 @@ finding the Ruby source, adding an entry to the <tt>ext/Setup</tt>
|
|||
file, adding your directory to the list of extensions in the file, and
|
||||
finally rebuilding Ruby. </p>
|
||||
|
||||
<H3><a name="Ruby_nn8">39.1.6 Compilation of C++ extensions</a></H3>
|
||||
<H3><a name="Ruby_nn8">40.1.6 Compilation of C++ extensions</a></H3>
|
||||
|
||||
|
||||
<p> On most machines, C++ extension modules should be linked
|
||||
|
|
@ -352,7 +352,7 @@ $libs = append_library($libs, "supc++")
|
|||
create_makefile('example')</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Ruby_nn9">39.2 Building Ruby Extensions under Windows 95/NT</a></H2>
|
||||
<H2><a name="Ruby_nn9">40.2 Building Ruby Extensions under Windows 95/NT</a></H2>
|
||||
|
||||
|
||||
<p> Building a SWIG extension to Ruby under Windows 95/NT is
|
||||
|
|
@ -377,7 +377,7 @@ order to build extensions, you may need to download the source
|
|||
distribution to the Ruby package, as you will need the Ruby header
|
||||
files. </p>
|
||||
|
||||
<H3><a name="Ruby_nn10">39.2.1 Running SWIG from Developer Studio</a></H3>
|
||||
<H3><a name="Ruby_nn10">40.2.1 Running SWIG from Developer Studio</a></H3>
|
||||
|
||||
|
||||
<p> If you are developing your application within Microsoft
|
||||
|
|
@ -441,13 +441,13 @@ Foo = 3.0
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Ruby_nn11">39.3 The Ruby-to-C/C++ Mapping</a></H2>
|
||||
<H2><a name="Ruby_nn11">40.3 The Ruby-to-C/C++ Mapping</a></H2>
|
||||
|
||||
|
||||
<p> This section describes the basics of how SWIG maps C or C++
|
||||
declarations in your SWIG interface files to Ruby constructs. </p>
|
||||
|
||||
<H3><a name="Ruby_nn12">39.3.1 Modules</a></H3>
|
||||
<H3><a name="Ruby_nn12">40.3.1 Modules</a></H3>
|
||||
|
||||
|
||||
<p> The SWIG <tt>%module</tt> directive specifies
|
||||
|
|
@ -519,7 +519,7 @@ option to wrap everything into the global module, take care that the
|
|||
names of your constants, classes and methods don't conflict with any of
|
||||
Ruby's built-in names. </p>
|
||||
|
||||
<H3><a name="Ruby_nn13">39.3.2 Functions</a></H3>
|
||||
<H3><a name="Ruby_nn13">40.3.2 Functions</a></H3>
|
||||
|
||||
|
||||
<p> Global functions are wrapped as Ruby module methods. For
|
||||
|
|
@ -553,7 +553,7 @@ irb(main):002:0> <b>Example.fact(4)</b>
|
|||
24</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn14">39.3.3 Variable Linking</a></H3>
|
||||
<H3><a name="Ruby_nn14">40.3.3 Variable Linking</a></H3>
|
||||
|
||||
|
||||
<p> C/C++ global variables are wrapped as a pair of singleton
|
||||
|
|
@ -615,7 +615,7 @@ directive. For example: </p>
|
|||
effect until it is explicitly disabled using <tt>%mutable</tt>.
|
||||
</p>
|
||||
|
||||
<H3><a name="Ruby_nn15">39.3.4 Constants</a></H3>
|
||||
<H3><a name="Ruby_nn15">40.3.4 Constants</a></H3>
|
||||
|
||||
|
||||
<p> C/C++ constants are wrapped as module constants initialized
|
||||
|
|
@ -643,7 +643,7 @@ irb(main):002:0> <b>Example::PI</b>
|
|||
3.14159</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn16">39.3.5 Pointers</a></H3>
|
||||
<H3><a name="Ruby_nn16">40.3.5 Pointers</a></H3>
|
||||
|
||||
|
||||
<p> "Opaque" pointers to arbitrary C/C++ types (i.e. types that
|
||||
|
|
@ -667,7 +667,7 @@ returns an instance of an internally generated Ruby class: </p>
|
|||
<p> A <tt>NULL</tt> pointer is always represented by
|
||||
the Ruby <tt>nil</tt> object. </p>
|
||||
|
||||
<H3><a name="Ruby_nn17">39.3.6 Structures</a></H3>
|
||||
<H3><a name="Ruby_nn17">40.3.6 Structures</a></H3>
|
||||
|
||||
|
||||
<p> C/C++ structs are wrapped as Ruby classes, with accessor
|
||||
|
|
@ -772,7 +772,7 @@ void Bar_f_set(Bar *b, Foo *val) {
|
|||
}</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn18">39.3.7 C++ classes</a></H3>
|
||||
<H3><a name="Ruby_nn18">40.3.7 C++ classes</a></H3>
|
||||
|
||||
|
||||
<p> Like structs, C++ classes are wrapped by creating a new Ruby
|
||||
|
|
@ -827,7 +827,7 @@ Ale
|
|||
3</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn19">39.3.8 C++ Inheritance</a></H3>
|
||||
<H3><a name="Ruby_nn19">40.3.8 C++ Inheritance</a></H3>
|
||||
|
||||
|
||||
<p> The SWIG type-checker is fully aware of C++ inheritance.
|
||||
|
|
@ -980,7 +980,7 @@ 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>). </p>
|
||||
|
||||
<H3><a name="Ruby_nn20">39.3.9 C++ Overloaded Functions</a></H3>
|
||||
<H3><a name="Ruby_nn20">40.3.9 C++ Overloaded Functions</a></H3>
|
||||
|
||||
|
||||
<p> C++ overloaded functions, methods, and constructors are
|
||||
|
|
@ -1070,7 +1070,7 @@ arises--in this case, the first declaration takes precedence. </p>
|
|||
<p>Please refer to the <a href="SWIGPlus.html#SWIGPlus">"SWIG
|
||||
and C++"</a> chapter for more information about overloading. </p>
|
||||
|
||||
<H3><a name="Ruby_nn21">39.3.10 C++ Operators</a></H3>
|
||||
<H3><a name="Ruby_nn21">40.3.10 C++ Operators</a></H3>
|
||||
|
||||
|
||||
<p> For the most part, overloaded operators are handled
|
||||
|
|
@ -1112,7 +1112,7 @@ c = Example.add_complex(a, b)</pre>
|
|||
is discussed in the <a href="#Ruby_operator_overloading">section
|
||||
on operator overloading</a>. </p>
|
||||
|
||||
<H3><a name="Ruby_nn22">39.3.11 C++ namespaces</a></H3>
|
||||
<H3><a name="Ruby_nn22">40.3.11 C++ namespaces</a></H3>
|
||||
|
||||
|
||||
<p> SWIG is aware of C++ namespaces, but namespace names do not
|
||||
|
|
@ -1169,7 +1169,7 @@ 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. </p>
|
||||
|
||||
<H3><a name="Ruby_nn23">39.3.12 C++ templates</a></H3>
|
||||
<H3><a name="Ruby_nn23">40.3.12 C++ templates</a></H3>
|
||||
|
||||
|
||||
<p> C++ templates don't present a huge problem for SWIG. However,
|
||||
|
|
@ -1211,7 +1211,7 @@ irb(main):004:0> <b>p.second</b>
|
|||
4</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn23_1">39.3.13 C++ Standard Template Library (STL)</a></H3>
|
||||
<H3><a name="Ruby_nn23_1">40.3.13 C++ Standard Template Library (STL)</a></H3>
|
||||
|
||||
|
||||
<p> On a related note, the standard SWIG library contains a
|
||||
|
|
@ -1304,7 +1304,7 @@ puts v
|
|||
shown in these examples. More details can be found in the <a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>
|
||||
chapter.</p>
|
||||
|
||||
<H3><a name="Ruby_C_STL_Functors">39.3.14 C++ STL Functors</a></H3>
|
||||
<H3><a name="Ruby_C_STL_Functors">40.3.14 C++ STL Functors</a></H3>
|
||||
|
||||
|
||||
<p>Some containers in the STL allow you to modify their default
|
||||
|
|
@ -1365,7 +1365,7 @@ b
|
|||
</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_C_Iterators">39.3.15 C++ STL Iterators</a></H3>
|
||||
<H3><a name="Ruby_C_Iterators">40.3.15 C++ STL Iterators</a></H3>
|
||||
|
||||
|
||||
<p>The STL is well known for the use of iterators. There
|
||||
|
|
@ -1448,10 +1448,10 @@ i
|
|||
|
||||
<p>If you'd rather have STL classes without any iterators, you should define <tt>-DSWIG_NO_EXPORT_ITERATOR_METHODS</tt> when running swig.</p>
|
||||
|
||||
<H3><a name="Ruby_nn24">39.3.16 C++ Smart Pointers</a></H3>
|
||||
<H3><a name="Ruby_nn24">40.3.16 C++ Smart Pointers</a></H3>
|
||||
|
||||
|
||||
<H4><a name="Ruby_smart_pointers_shared_ptr">39.3.16.1 The shared_ptr Smart Pointer</a></H4>
|
||||
<H4><a name="Ruby_smart_pointers_shared_ptr">40.3.16.1 The shared_ptr Smart Pointer</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -1462,7 +1462,7 @@ in the <a href="Library.html#Library_std_shared_ptr">shared_ptr smart pointer</a
|
|||
</p>
|
||||
|
||||
|
||||
<H4><a name="Ruby_smart_pointers_generic">39.3.16.2 Generic Smart Pointers</a></H4>
|
||||
<H4><a name="Ruby_smart_pointers_generic">40.3.16.2 Generic Smart Pointers</a></H4>
|
||||
|
||||
|
||||
<p> In certain C++ programs, it is common to use classes that
|
||||
|
|
@ -1527,7 +1527,7 @@ method. For example: </p>
|
|||
<pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn25">39.3.17 Cross-Language Polymorphism</a></H3>
|
||||
<H3><a name="Ruby_nn25">40.3.17 Cross-Language Polymorphism</a></H3>
|
||||
|
||||
|
||||
<p> SWIG's Ruby module supports cross-language polymorphism
|
||||
|
|
@ -1536,7 +1536,7 @@ module. Rather than duplicate the information presented in the <a href="Python.h
|
|||
section just notes the differences that you need to be aware of when
|
||||
using this feature with Ruby. </p>
|
||||
|
||||
<H4><a name="Ruby_nn26">39.3.17.1 Exception Unrolling</a></H4>
|
||||
<H4><a name="Ruby_nn26">40.3.17.1 Exception Unrolling</a></H4>
|
||||
|
||||
|
||||
<p> Whenever a C++ director class routes one of its virtual
|
||||
|
|
@ -1559,7 +1559,7 @@ method is "wrapped" using the <tt>rb_rescue2()</tt>
|
|||
function from Ruby's C API. If any Ruby exception is raised, it will be
|
||||
caught here and a C++ exception is raised in its place. </p>
|
||||
|
||||
<H2><a name="Ruby_nn27">39.4 Naming</a></H2>
|
||||
<H2><a name="Ruby_nn27">40.4 Naming</a></H2>
|
||||
|
||||
|
||||
<p>Ruby has several common naming conventions. Constants are
|
||||
|
|
@ -1597,7 +1597,7 @@ generated
|
|||
by SWIG, it is turned off by default in SWIG 1.3.28. However, it is
|
||||
planned to become the default option in future releases.</p>
|
||||
|
||||
<H3><a name="Ruby_nn28">39.4.1 Defining Aliases</a></H3>
|
||||
<H3><a name="Ruby_nn28">40.4.1 Defining Aliases</a></H3>
|
||||
|
||||
|
||||
<p> It's a fairly common practice in the Ruby built-ins and
|
||||
|
|
@ -1667,7 +1667,7 @@ matching rules used for other kinds of features apply (see the chapter
|
|||
on <a href="Customization.html#Customization">"Customization
|
||||
Features"</a>) for more details).</p>
|
||||
|
||||
<H3><a name="Ruby_nn29">39.4.2 Predicate Methods</a></H3>
|
||||
<H3><a name="Ruby_nn29">40.4.2 Predicate Methods</a></H3>
|
||||
|
||||
|
||||
<p> Ruby methods that return a boolean value and end in a
|
||||
|
|
@ -1716,7 +1716,7 @@ using SWIG's "features" mechanism and so the same name matching rules
|
|||
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
|
||||
Features"</a>) for more details). </p>
|
||||
|
||||
<H3><a name="Ruby_nn30">39.4.3 Bang Methods</a></H3>
|
||||
<H3><a name="Ruby_nn30">40.4.3 Bang Methods</a></H3>
|
||||
|
||||
|
||||
<p> Ruby methods that modify an object in-place and end in an
|
||||
|
|
@ -1748,7 +1748,7 @@ using SWIG's "features" mechanism and so the same name matching rules
|
|||
used for other kinds of features apply (see the chapter on <a href="Customization.html#Customization">"Customization
|
||||
Features"</a>) for more details). </p>
|
||||
|
||||
<H3><a name="Ruby_nn31">39.4.4 Getters and Setters</a></H3>
|
||||
<H3><a name="Ruby_nn31">40.4.4 Getters and Setters</a></H3>
|
||||
|
||||
|
||||
<p> Often times a C++ library will expose properties through
|
||||
|
|
@ -1783,7 +1783,7 @@ irb(main):003:0> <b>puts foo.value</b></pre>
|
|||
%rename("value=") Foo::setValue(int value);</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Ruby_nn32">39.5 Input and output parameters</a></H2>
|
||||
<H2><a name="Ruby_nn32">40.5 Input and output parameters</a></H2>
|
||||
|
||||
|
||||
<p> A common problem in some C programs is handling parameters
|
||||
|
|
@ -1922,10 +1922,10 @@ void get_dimensions(Matrix *m, int *rows, int*columns);</pre>
|
|||
<pre>r, c = Example.get_dimensions(m)</pre>
|
||||
</div>
|
||||
|
||||
<H2><a name="Ruby_nn33">39.6 Exception handling </a></H2>
|
||||
<H2><a name="Ruby_nn33">40.6 Exception handling </a></H2>
|
||||
|
||||
|
||||
<H3><a name="Ruby_nn34">39.6.1 Using the %exception directive </a></H3>
|
||||
<H3><a name="Ruby_nn34">40.6.1 Using the %exception directive </a></H3>
|
||||
|
||||
|
||||
<p>The SWIG <tt>%exception</tt> directive can be
|
||||
|
|
@ -2034,7 +2034,7 @@ methods and functions named <tt>getitem</tt> and <tt>setitem</tt>.
|
|||
limited to C++ exception handling. See the chapter on <a href="Customization.html#Customization">Customization
|
||||
Features</a> for more examples.</p>
|
||||
|
||||
<H3><a name="Ruby_nn34_2">39.6.2 Handling Ruby Blocks </a></H3>
|
||||
<H3><a name="Ruby_nn34_2">40.6.2 Handling Ruby Blocks </a></H3>
|
||||
|
||||
|
||||
<p>One of the highlights of Ruby and most of its standard library
|
||||
|
|
@ -2101,7 +2101,7 @@ a special in typemap, like:</p>
|
|||
|
||||
<p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p>
|
||||
|
||||
<H3><a name="Ruby_nn35">39.6.3 Raising exceptions </a></H3>
|
||||
<H3><a name="Ruby_nn35">40.6.3 Raising exceptions </a></H3>
|
||||
|
||||
|
||||
<p>There are three ways to raise exceptions from C++ code to
|
||||
|
|
@ -2258,7 +2258,7 @@ function. The first argument passed to <tt>rb_raise()</tt>
|
|||
is the exception type. You can raise a custom exception type or one of
|
||||
the built-in Ruby exception types.</p>
|
||||
|
||||
<H3><a name="Ruby_nn36">39.6.4 Exception classes </a></H3>
|
||||
<H3><a name="Ruby_nn36">40.6.4 Exception classes </a></H3>
|
||||
|
||||
|
||||
<p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt>
|
||||
|
|
@ -2295,7 +2295,7 @@ end </pre>
|
|||
<p>For another example look at swig/Examples/ruby/exception_class.
|
||||
</p>
|
||||
|
||||
<H2><a name="Ruby_nn37">39.7 Typemaps</a></H2>
|
||||
<H2><a name="Ruby_nn37">40.7 Typemaps</a></H2>
|
||||
|
||||
|
||||
<p> This section describes how you can modify SWIG's default
|
||||
|
|
@ -2310,7 +2310,7 @@ a required part of using SWIG---the default wrapping behavior is enough
|
|||
in most cases. Typemaps are only used if you want to change some aspect
|
||||
of the primitive C-Ruby interface.</p>
|
||||
|
||||
<H3><a name="Ruby_nn38">39.7.1 What is a typemap?</a></H3>
|
||||
<H3><a name="Ruby_nn38">40.7.1 What is a typemap?</a></H3>
|
||||
|
||||
|
||||
<p> A typemap is nothing more than a code generation rule that is
|
||||
|
|
@ -2467,7 +2467,7 @@ to be used as follows (notice how the length parameter is omitted): </p>
|
|||
2</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_Typemap_scope">39.7.2 Typemap scope</a></H3>
|
||||
<H3><a name="Ruby_Typemap_scope">40.7.2 Typemap scope</a></H3>
|
||||
|
||||
|
||||
<p> Once defined, a typemap remains in effect for all of the
|
||||
|
|
@ -2513,7 +2513,7 @@ where the class itself is defined. For example:</p>
|
|||
};</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_Copying_a_typemap">39.7.3 Copying a typemap</a></H3>
|
||||
<H3><a name="Ruby_Copying_a_typemap">40.7.3 Copying a typemap</a></H3>
|
||||
|
||||
|
||||
<p> A typemap is copied by using assignment. For example:</p>
|
||||
|
|
@ -2555,7 +2555,7 @@ rules as for <tt>
|
|||
%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_Deleting_a_typemap">39.7.4 Deleting a typemap</a></H3>
|
||||
<H3><a name="Ruby_Deleting_a_typemap">40.7.4 Deleting a typemap</a></H3>
|
||||
|
||||
|
||||
<p> A typemap can be deleted by simply defining no code. For
|
||||
|
|
@ -2580,7 +2580,7 @@ defined by typemaps, clearing a fundamental type like <tt>int</tt>
|
|||
will make that type unusable unless you also define a new set of
|
||||
typemaps immediately after the clear operation.</p>
|
||||
|
||||
<H3><a name="Ruby_Placement_of_typemaps">39.7.5 Placement of typemaps</a></H3>
|
||||
<H3><a name="Ruby_Placement_of_typemaps">40.7.5 Placement of typemaps</a></H3>
|
||||
|
||||
|
||||
<p> Typemap declarations can be declared in the global scope,
|
||||
|
|
@ -2651,13 +2651,13 @@ In this example, this is done using the class declaration <tt>class
|
|||
string</tt>
|
||||
.</p>
|
||||
|
||||
<H3><a name="Ruby_nn39">39.7.6 Ruby typemaps</a></H3>
|
||||
<H3><a name="Ruby_nn39">40.7.6 Ruby typemaps</a></H3>
|
||||
|
||||
|
||||
<p>The following list details all of the typemap methods that
|
||||
can be used by the Ruby module: </p>
|
||||
|
||||
<H4><a name="Ruby_in_typemap">39.7.6.1 "in" typemap</a></H4>
|
||||
<H4><a name="Ruby_in_typemap">40.7.6.1 "in" typemap</a></H4>
|
||||
|
||||
|
||||
<p>Converts Ruby objects to input
|
||||
|
|
@ -2724,7 +2724,7 @@ arguments to be specified. For example:</p>
|
|||
|
||||
<p> At this time, only zero or one arguments may be converted.</p>
|
||||
|
||||
<H4><a name="Ruby_typecheck_typemap">39.7.6.2 "typecheck" typemap</a></H4>
|
||||
<H4><a name="Ruby_typecheck_typemap">40.7.6.2 "typecheck" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "typecheck" typemap is used to support overloaded
|
||||
|
|
@ -2746,7 +2746,7 @@ program uses overloaded methods, you should also define a collection of
|
|||
"typecheck" typemaps. More details about this follow in a later section
|
||||
on "Typemaps and Overloading."</p>
|
||||
|
||||
<H4><a name="Ruby_out_typemap">39.7.6.3 "out" typemap</a></H4>
|
||||
<H4><a name="Ruby_out_typemap">40.7.6.3 "out" typemap</a></H4>
|
||||
|
||||
|
||||
<p>Converts return value of a C function
|
||||
|
|
@ -2797,7 +2797,7 @@ version of the C datatype matched by the typemap.</td>
|
|||
</table>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_arginit_typemap">39.7.6.4 "arginit" typemap</a></H4>
|
||||
<H4><a name="Ruby_arginit_typemap">40.7.6.4 "arginit" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "arginit" typemap is used to set the initial value of a
|
||||
|
|
@ -2812,7 +2812,7 @@ applications. For example:</p>
|
|||
}</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_default_typemap">39.7.6.5 "default" typemap</a></H4>
|
||||
<H4><a name="Ruby_default_typemap">40.7.6.5 "default" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "default" typemap is used to turn an argument into a
|
||||
|
|
@ -2837,7 +2837,7 @@ arguments that follow must have default values. See the <a href="SWIG.html#SWIG_
|
|||
Default/optional arguments</a> section for further information on
|
||||
default argument wrapping.</p>
|
||||
|
||||
<H4><a name="Ruby_check_typemap">39.7.6.6 "check" typemap</a></H4>
|
||||
<H4><a name="Ruby_check_typemap">40.7.6.6 "check" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "check" typemap is used to supply value checking code
|
||||
|
|
@ -2852,7 +2852,7 @@ arguments have been converted. For example:</p>
|
|||
}</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_argout_typemap_">39.7.6.7 "argout" typemap</a></H4>
|
||||
<H4><a name="Ruby_argout_typemap_">40.7.6.7 "argout" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "argout" typemap is used to return values from arguments.
|
||||
|
|
@ -2906,7 +2906,7 @@ some function like SWIG_Ruby_AppendOutput.</p>
|
|||
|
||||
<p> See the <tt>typemaps.i</tt> library for examples.</p>
|
||||
|
||||
<H4><a name="Ruby_freearg_typemap_">39.7.6.8 "freearg" typemap</a></H4>
|
||||
<H4><a name="Ruby_freearg_typemap_">40.7.6.8 "freearg" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "freearg" typemap is used to cleanup argument data. It is
|
||||
|
|
@ -2933,7 +2933,7 @@ This code is also placed into a special variable <tt>$cleanup</tt>
|
|||
that may be used in other typemaps whenever a wrapper function needs to
|
||||
abort prematurely.</p>
|
||||
|
||||
<H4><a name="Ruby_newfree_typemap">39.7.6.9 "newfree" typemap</a></H4>
|
||||
<H4><a name="Ruby_newfree_typemap">40.7.6.9 "newfree" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt>
|
||||
|
|
@ -2957,7 +2957,7 @@ string *foo();</pre>
|
|||
<p> See <a href="Customization.html#Customization_ownership">Object
|
||||
ownership and %newobject</a> for further details.</p>
|
||||
|
||||
<H4><a name="Ruby_memberin_typemap">39.7.6.10 "memberin" typemap</a></H4>
|
||||
<H4><a name="Ruby_memberin_typemap">40.7.6.10 "memberin" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "memberin" typemap is used to copy data from<em> an
|
||||
|
|
@ -2975,21 +2975,21 @@ example:</p>
|
|||
already provides a default implementation for arrays, strings, and
|
||||
other objects.</p>
|
||||
|
||||
<H4><a name="Ruby_varin_typemap">39.7.6.11 "varin" typemap</a></H4>
|
||||
<H4><a name="Ruby_varin_typemap">40.7.6.11 "varin" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "varin" typemap is used to convert objects in the target
|
||||
language to C for the purposes of assigning to a C/C++ global variable.
|
||||
This is implementation specific.</p>
|
||||
|
||||
<H4><a name="Ruby_varout_typemap_">39.7.6.12 "varout" typemap</a></H4>
|
||||
<H4><a name="Ruby_varout_typemap_">40.7.6.12 "varout" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "varout" typemap is used to convert a C/C++ object to an
|
||||
object in the target language when reading a C/C++ global variable.
|
||||
This is implementation specific.</p>
|
||||
|
||||
<H4><a name="Ruby_throws_typemap">39.7.6.13 "throws" typemap</a></H4>
|
||||
<H4><a name="Ruby_throws_typemap">40.7.6.13 "throws" typemap</a></H4>
|
||||
|
||||
|
||||
<p> The "throws" typemap is only used when SWIG parses a C++
|
||||
|
|
@ -3030,7 +3030,7 @@ specification yet they do throw exceptions, SWIG cannot know how to
|
|||
deal with them. For a neat way to handle these, see the <a href="Customization.html#Customization_exception">Exception
|
||||
handling with %exception</a> section.</p>
|
||||
|
||||
<H4><a name="Ruby_directorin_typemap">39.7.6.14 directorin typemap</a></H4>
|
||||
<H4><a name="Ruby_directorin_typemap">40.7.6.14 directorin typemap</a></H4>
|
||||
|
||||
|
||||
<p>Converts C++ objects in director
|
||||
|
|
@ -3089,7 +3089,7 @@ referring to the class itself.</td>
|
|||
</table>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_directorout_typemap">39.7.6.15 directorout typemap</a></H4>
|
||||
<H4><a name="Ruby_directorout_typemap">40.7.6.15 directorout typemap</a></H4>
|
||||
|
||||
|
||||
<p>Converts Ruby objects in director
|
||||
|
|
@ -3162,7 +3162,7 @@ exception.
|
|||
|
||||
</p>
|
||||
|
||||
<H4><a name="Ruby_directorargout_typemap">39.7.6.16 directorargout typemap</a></H4>
|
||||
<H4><a name="Ruby_directorargout_typemap">40.7.6.16 directorargout typemap</a></H4>
|
||||
|
||||
|
||||
<p>Output argument processing in director
|
||||
|
|
@ -3220,19 +3220,19 @@ referring to the instance of the class itself</td>
|
|||
</table>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_ret_typemap">39.7.6.17 ret typemap</a></H4>
|
||||
<H4><a name="Ruby_ret_typemap">40.7.6.17 ret typemap</a></H4>
|
||||
|
||||
|
||||
<p>Cleanup of function return values
|
||||
</p>
|
||||
|
||||
<H4><a name="Ruby_globalin_typemap">39.7.6.18 globalin typemap</a></H4>
|
||||
<H4><a name="Ruby_globalin_typemap">40.7.6.18 globalin typemap</a></H4>
|
||||
|
||||
|
||||
<p>Setting of C global variables
|
||||
</p>
|
||||
|
||||
<H3><a name="Ruby_nn40">39.7.7 Typemap variables</a></H3>
|
||||
<H3><a name="Ruby_nn40">40.7.7 Typemap variables</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -3282,7 +3282,7 @@ so that their values can be properly assigned. </div>
|
|||
<div class="indent">The Ruby name of the wrapper function
|
||||
being created. </div>
|
||||
|
||||
<H3><a name="Ruby_nn41">39.7.8 Useful Functions</a></H3>
|
||||
<H3><a name="Ruby_nn41">40.7.8 Useful Functions</a></H3>
|
||||
|
||||
|
||||
<p> When you write a typemap, you usually have to work directly
|
||||
|
|
@ -3297,7 +3297,7 @@ stick to the swig functions instead of the native Ruby functions.
|
|||
That should help you avoid having to rewrite a lot of typemaps
|
||||
across multiple languages.</p>
|
||||
|
||||
<H4><a name="Ruby_nn42">39.7.8.1 C Datatypes to Ruby Objects</a></H4>
|
||||
<H4><a name="Ruby_nn42">40.7.8.1 C Datatypes to Ruby Objects</a></H4>
|
||||
|
||||
|
||||
<div class="diagram">
|
||||
|
|
@ -3339,7 +3339,7 @@ SWIG_From_float(float)</td>
|
|||
</table>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_nn43">39.7.8.2 Ruby Objects to C Datatypes</a></H4>
|
||||
<H4><a name="Ruby_nn43">40.7.8.2 Ruby Objects to C Datatypes</a></H4>
|
||||
|
||||
|
||||
<p>Here, while the Ruby versions return the value directly, the SWIG
|
||||
|
|
@ -3407,7 +3407,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
|
|||
</table>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_nn44">39.7.8.3 Macros for VALUE</a></H4>
|
||||
<H4><a name="Ruby_nn44">40.7.8.3 Macros for VALUE</a></H4>
|
||||
|
||||
|
||||
<p> <tt>RSTRING_LEN(str)</tt> </p>
|
||||
|
|
@ -3430,7 +3430,7 @@ versions do not, but return a status value to indicate success (<tt>SWIG_OK</tt>
|
|||
|
||||
<div class="indent">pointer to array storage</div>
|
||||
|
||||
<H4><a name="Ruby_nn45">39.7.8.4 Exceptions</a></H4>
|
||||
<H4><a name="Ruby_nn45">40.7.8.4 Exceptions</a></H4>
|
||||
|
||||
|
||||
<p> <tt>void rb_raise(VALUE exception, const char *fmt,
|
||||
|
|
@ -3509,7 +3509,7 @@ message to standard error 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>. </div>
|
||||
|
||||
<H4><a name="Ruby_nn46">39.7.8.5 Iterators</a></H4>
|
||||
<H4><a name="Ruby_nn46">40.7.8.5 Iterators</a></H4>
|
||||
|
||||
|
||||
<p> <tt>void rb_iter_break()</tt> </p>
|
||||
|
|
@ -3555,14 +3555,14 @@ VALUE), VALUE value)</tt></p>
|
|||
<div class="indent"> Equivalent to Ruby's <tt>throw</tt>.
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn47">39.7.9 Typemap Examples</a></H3>
|
||||
<H3><a name="Ruby_nn47">40.7.9 Typemap Examples</a></H3>
|
||||
|
||||
|
||||
<p> This section includes a few examples of typemaps. For more
|
||||
examples, you might look at the examples in the <tt>Example/ruby</tt>
|
||||
directory. </p>
|
||||
|
||||
<H3><a name="Ruby_nn48">39.7.10 Converting a Ruby array to a char **</a></H3>
|
||||
<H3><a name="Ruby_nn48">40.7.10 Converting a Ruby array to a char **</a></H3>
|
||||
|
||||
|
||||
<p> A common problem in many C programs is the processing of
|
||||
|
|
@ -3627,7 +3627,7 @@ array. Since dynamic memory allocation is used to allocate memory for
|
|||
the array, the "freearg" typemap is used to later release this memory
|
||||
after the execution of the C function. </p>
|
||||
|
||||
<H3><a name="Ruby_nn49">39.7.11 Collecting arguments in a hash</a></H3>
|
||||
<H3><a name="Ruby_nn49">40.7.11 Collecting arguments in a hash</a></H3>
|
||||
|
||||
|
||||
<p> Ruby's solution to the "keyword arguments" capability of some
|
||||
|
|
@ -3841,7 +3841,7 @@ memory leak. Fortunately, this typemap is a lot easier to write: </p>
|
|||
program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt>
|
||||
directory of the SWIG distribution. </p>
|
||||
|
||||
<H3><a name="Ruby_nn50">39.7.12 Pointer handling</a></H3>
|
||||
<H3><a name="Ruby_nn50">40.7.12 Pointer handling</a></H3>
|
||||
|
||||
|
||||
<p> Occasionally, it might be necessary to convert pointer values
|
||||
|
|
@ -3900,7 +3900,7 @@ For example: </p>
|
|||
}</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_nn51">39.7.12.1 Ruby Datatype Wrapping</a></H4>
|
||||
<H4><a name="Ruby_nn51">40.7.12.1 Ruby Datatype Wrapping</a></H4>
|
||||
|
||||
|
||||
<p> <tt>VALUE Data_Wrap_Struct(VALUE class, void
|
||||
|
|
@ -3927,7 +3927,7 @@ as above. </div>
|
|||
type <i>c-type</i> from the data object <i>obj</i>
|
||||
and assigns that pointer to <i>ptr</i>. </div>
|
||||
|
||||
<H3><a name="Ruby_nn52">39.7.13 Example: STL Vector to Ruby Array</a></H3>
|
||||
<H3><a name="Ruby_nn52">40.7.13 Example: STL Vector to Ruby Array</a></H3>
|
||||
|
||||
|
||||
<p>Another use for macros and type maps is to create a Ruby array
|
||||
|
|
@ -4019,7 +4019,7 @@ STL with ruby, you are advised to use the standard swig STL library,
|
|||
which does much more than this. Refer to the section called
|
||||
the<a href="#Ruby_nn23_1"> C++ Standard Template Library</a>.
|
||||
|
||||
<H2><a name="Ruby_nn65">39.8 Docstring Features</a></H2>
|
||||
<H2><a name="Ruby_nn65">40.8 Docstring Features</a></H2>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4053,7 +4053,7 @@ generate ri documentation from a c wrap file, you could do:</p>
|
|||
$ rdoc -r file_wrap.c
|
||||
</pre></div>
|
||||
|
||||
<H3><a name="Ruby_nn66">39.8.1 Module docstring</a></H3>
|
||||
<H3><a name="Ruby_nn66">40.8.1 Module docstring</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4083,7 +4083,7 @@ layout of controls on a panel, etc. to be loaded from an XML file."
|
|||
%module(docstring=DOCSTRING) xrc</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn67">39.8.2 %feature("autodoc")</a></H3>
|
||||
<H3><a name="Ruby_nn67">40.8.2 %feature("autodoc")</a></H3>
|
||||
|
||||
|
||||
<p>Since SWIG does know everything about the function it wraps,
|
||||
|
|
@ -4104,7 +4104,7 @@ several options for autodoc controlled by the value given to the
|
|||
feature, described below.
|
||||
</p>
|
||||
|
||||
<H4><a name="Ruby_nn68">39.8.2.1 %feature("autodoc", "0")</a></H4>
|
||||
<H4><a name="Ruby_nn68">40.8.2.1 %feature("autodoc", "0")</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4128,7 +4128,7 @@ Then Ruby code like this will be generated:
|
|||
...</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_autodoc1">39.8.2.2 %feature("autodoc", "1")</a></H4>
|
||||
<H4><a name="Ruby_autodoc1">40.8.2.2 %feature("autodoc", "1")</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4148,7 +4148,7 @@ this:
|
|||
...</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_autodoc2">39.8.2.3 %feature("autodoc", "2")</a></H4>
|
||||
<H4><a name="Ruby_autodoc2">40.8.2.3 %feature("autodoc", "2")</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4160,7 +4160,7 @@ parameter types with the "2" option will result in Ruby code like
|
|||
this:
|
||||
</p>
|
||||
|
||||
<H4><a name="Ruby_feature_autodoc3">39.8.2.4 %feature("autodoc", "3")</a></H4>
|
||||
<H4><a name="Ruby_feature_autodoc3">40.8.2.4 %feature("autodoc", "3")</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4181,7 +4181,7 @@ Parameters:
|
|||
bar - Bar</pre>
|
||||
</div>
|
||||
|
||||
<H4><a name="Ruby_nn70">39.8.2.5 %feature("autodoc", "docstring")</a></H4>
|
||||
<H4><a name="Ruby_nn70">40.8.2.5 %feature("autodoc", "docstring")</a></H4>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4197,7 +4197,7 @@ generated string. For example:
|
|||
void GetPosition(int* OUTPUT, int* OUTPUT);</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn71">39.8.3 %feature("docstring")</a></H3>
|
||||
<H3><a name="Ruby_nn71">40.8.3 %feature("docstring")</a></H3>
|
||||
|
||||
|
||||
<p>
|
||||
|
|
@ -4208,10 +4208,10 @@ docstring associated with classes, function or methods are output.
|
|||
If an item already has an autodoc string then it is combined with the
|
||||
docstring and they are output together. </p>
|
||||
|
||||
<H2><a name="Ruby_nn53">39.9 Advanced Topics</a></H2>
|
||||
<H2><a name="Ruby_nn53">40.9 Advanced Topics</a></H2>
|
||||
|
||||
|
||||
<H3><a name="Ruby_operator_overloading">39.9.1 Operator overloading</a></H3>
|
||||
<H3><a name="Ruby_operator_overloading">40.9.1 Operator overloading</a></H3>
|
||||
|
||||
|
||||
<p> SWIG allows operator overloading with, by using the <tt>%extend</tt>
|
||||
|
|
@ -4392,7 +4392,7 @@ separate method for handling <i>inequality</i> since Ruby
|
|||
parses the expression <i>a != b</i> as <i>!(a == b)</i>.
|
||||
</p>
|
||||
|
||||
<H3><a name="Ruby_nn55">39.9.2 Creating Multi-Module Packages</a></H3>
|
||||
<H3><a name="Ruby_nn55">40.9.2 Creating Multi-Module Packages</a></H3>
|
||||
|
||||
|
||||
<p> The chapter on <a href="Modules.html#Modules">Working
|
||||
|
|
@ -4518,7 +4518,7 @@ irb(main):005:0> <b>c.getX()</b>
|
|||
5.0</pre>
|
||||
</div>
|
||||
|
||||
<H3><a name="Ruby_nn56">39.9.3 Specifying Mixin Modules</a></H3>
|
||||
<H3><a name="Ruby_nn56">40.9.3 Specifying Mixin Modules</a></H3>
|
||||
|
||||
|
||||
<p> The Ruby language doesn't support multiple inheritance, but
|
||||
|
|
@ -4585,7 +4585,7 @@ matching rules used for other kinds of features apply (see the chapter
|
|||
on <a href="Customization.html#Customization">"Customization
|
||||
Features"</a>) for more details). </p>
|
||||
|
||||
<H2><a name="Ruby_nn57">39.10 Memory Management</a></H2>
|
||||
<H2><a name="Ruby_nn57">40.10 Memory Management</a></H2>
|
||||
|
||||
|
||||
<p>One of the most common issues in generating SWIG bindings for
|
||||
|
|
@ -4608,7 +4608,7 @@ to C++ (or vice versa) depending on what function or methods are
|
|||
invoked. Clearly, developing a SWIG wrapper requires a thorough
|
||||
understanding of how the underlying library manages memory.</p>
|
||||
|
||||
<H3><a name="Ruby_nn58">39.10.1 Mark and Sweep Garbage Collector </a></H3>
|
||||
<H3><a name="Ruby_nn58">40.10.1 Mark and Sweep Garbage Collector </a></H3>
|
||||
|
||||
|
||||
<p>Ruby uses a mark and sweep garbage collector. When the garbage
|
||||
|
|
@ -4639,7 +4639,7 @@ any memory has been allocated in creating the underlying C struct or
|
|||
C++ struct, then a "free" function must be defined that deallocates
|
||||
this memory. </p>
|
||||
|
||||
<H3><a name="Ruby_nn59">39.10.2 Object Ownership</a></H3>
|
||||
<H3><a name="Ruby_nn59">40.10.2 Object Ownership</a></H3>
|
||||
|
||||
|
||||
<p>As described above, memory management depends on clearly
|
||||
|
|
@ -4784,7 +4784,7 @@ public:
|
|||
|
||||
<p> This code can be seen in swig/examples/ruby/tracking.</p>
|
||||
|
||||
<H3><a name="Ruby_nn60">39.10.3 Object Tracking</a></H3>
|
||||
<H3><a name="Ruby_nn60">40.10.3 Object Tracking</a></H3>
|
||||
|
||||
|
||||
<p>The remaining parts of this section will use the class library
|
||||
|
|
@ -5010,7 +5010,7 @@ However, if you implement your own free functions (see below) you may
|
|||
also have to call the <tt>SWIG_RubyRemoveTracking</tt> and <tt>RubyUnlinkObjects</tt>
|
||||
methods.</p>
|
||||
|
||||
<H3><a name="Ruby_nn61">39.10.4 Mark Functions</a></H3>
|
||||
<H3><a name="Ruby_nn61">40.10.4 Mark Functions</a></H3>
|
||||
|
||||
|
||||
<p>With a bit more testing, we see that our class library still
|
||||
|
|
@ -5139,7 +5139,7 @@ irb(main):016:0></pre>
|
|||
|
||||
<p>This code can be seen in swig/examples/ruby/mark_function.</p>
|
||||
|
||||
<H3><a name="Ruby_nn62">39.10.5 Free Functions</a></H3>
|
||||
<H3><a name="Ruby_nn62">40.10.5 Free Functions</a></H3>
|
||||
|
||||
|
||||
<p>By default, SWIG creates a "free" function that is called when
|
||||
|
|
@ -5307,7 +5307,7 @@ been freed, and thus raises a runtime exception.</p>
|
|||
|
||||
<p>This code can be seen in swig/examples/ruby/free_function.</p>
|
||||
|
||||
<H3><a name="Ruby_nn63">39.10.6 Embedded Ruby and the C++ Stack</a></H3>
|
||||
<H3><a name="Ruby_nn63">40.10.6 Embedded Ruby and the C++ Stack</a></H3>
|
||||
|
||||
|
||||
<p>As has been said, the Ruby GC runs and marks objects before
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue