| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <title>SWIG and Ruby</title> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| </head> |
| |
| |
| <body style="background-color: rgb(255, 255, 255);"> |
| |
| |
| |
| |
| |
| <H1><a name="Ruby"></a>31 SWIG and Ruby</H1> |
| <!-- INDEX --> |
| <div class="sectiontoc"> |
| <ul> |
| <li><a href="#Ruby_nn2">Preliminaries</a> |
| <ul> |
| <li><a href="#Ruby_nn3">Running SWIG</a> |
| <li><a href="#Ruby_nn4">Getting the right header files</a> |
| <li><a href="#Ruby_nn5">Compiling a dynamic module</a> |
| <li><a href="#Ruby_nn6">Using your module</a> |
| <li><a href="#Ruby_nn7">Static linking</a> |
| <li><a href="#Ruby_nn8">Compilation of C++ extensions</a> |
| </ul> |
| <li><a href="#Ruby_nn9">Building Ruby Extensions under Windows 95/NT</a> |
| <ul> |
| <li><a href="#Ruby_nn10">Running SWIG from Developer Studio</a> |
| </ul> |
| <li><a href="#Ruby_nn11">The Ruby-to-C/C++ Mapping</a> |
| <ul> |
| <li><a href="#Ruby_nn12">Modules</a> |
| <li><a href="#Ruby_nn13">Functions</a> |
| <li><a href="#Ruby_nn14">Variable Linking</a> |
| <li><a href="#Ruby_nn15">Constants</a> |
| <li><a href="#Ruby_nn16">Pointers</a> |
| <li><a href="#Ruby_nn17">Structures</a> |
| <li><a href="#Ruby_nn18">C++ classes</a> |
| <li><a href="#Ruby_nn19">C++ Inheritance</a> |
| <li><a href="#Ruby_nn20">C++ Overloaded Functions</a> |
| <li><a href="#Ruby_nn21">C++ Operators</a> |
| <li><a href="#Ruby_nn22">C++ namespaces</a> |
| <li><a href="#Ruby_nn23">C++ templates</a> |
| <li><a href="#Ruby_nn23_1">C++ Standard Template Library (STL)</a> |
| <li><a href="#C_STL_Functors">C++ STL Functors</a> |
| <li><a href="#Ruby_C_Iterators">C++ STL Iterators</a> |
| <li><a href="#Ruby_nn24">C++ Smart Pointers</a> |
| <li><a href="#Ruby_nn25">Cross-Language Polymorphism</a> |
| <ul> |
| <li><a href="#Ruby_nn26">Exception Unrolling</a> |
| </ul> |
| </ul> |
| <li><a href="#Ruby_nn27">Naming</a> |
| <ul> |
| <li><a href="#Ruby_nn28">Defining Aliases</a> |
| <li><a href="#Ruby_nn29">Predicate Methods</a> |
| <li><a href="#Ruby_nn30">Bang Methods</a> |
| <li><a href="#Ruby_nn31">Getters and Setters</a> |
| </ul> |
| <li><a href="#Ruby_nn32">Input and output parameters</a> |
| <li><a href="#Ruby_nn33">Exception handling </a> |
| <ul> |
| <li><a href="#Ruby_nn34">Using the %exception directive </a> |
| <li><a href="#Ruby_nn34_2">Handling Ruby Blocks </a> |
| <li><a href="#Ruby_nn35">Raising exceptions </a> |
| <li><a href="#Ruby_nn36">Exception classes </a> |
| </ul> |
| <li><a href="#Ruby_nn37">Typemaps</a> |
| <ul> |
| <li><a href="#Ruby_nn38">What is a typemap?</a> |
| <li><a href="#Ruby_Typemap_scope">Typemap scope</a> |
| <li><a href="#Ruby_Copying_a_typemap">Copying a typemap</a> |
| <li><a href="#Ruby_Deleting_a_typemap">Deleting a typemap</a> |
| <li><a href="#Ruby_Placement_of_typemaps">Placement of typemaps</a> |
| <li><a href="#Ruby_nn39">Ruby typemaps</a> |
| <ul> |
| <li><a href="#Ruby_in_typemap"> "in" typemap</a> |
| <li><a href="#Ruby_typecheck_typemap">"typecheck" typemap</a> |
| <li><a href="#Ruby_out_typemap"> "out" typemap</a> |
| <li><a href="#Ruby_arginit_typemap">"arginit" typemap</a> |
| <li><a href="#Ruby_default_typemap">"default" typemap</a> |
| <li><a href="#Ruby_check_typemap">"check" typemap</a> |
| <li><a href="#Ruby_argout_typemap_">"argout" typemap</a> |
| <li><a href="#Ruby_freearg_typemap_">"freearg" typemap</a> |
| <li><a href="#Ruby_newfree_typemap">"newfree" typemap</a> |
| <li><a href="#Ruby_memberin_typemap">"memberin" typemap</a> |
| <li><a href="#Ruby_varin_typemap">"varin" typemap</a> |
| <li><a href="#Ruby_varout_typemap_">"varout" typemap</a> |
| <li><a href="#Ruby_throws_typemap">"throws" typemap</a> |
| <li><a href="#Ruby_directorin_typemap">directorin typemap</a> |
| <li><a href="#Ruby_directorout_typemap">directorout typemap</a> |
| <li><a href="#Ruby_directorargout_typemap">directorargout typemap</a> |
| <li><a href="#Ruby_ret_typemap">ret typemap</a> |
| <li><a href="#Ruby_globalin_typemap">globalin typemap</a> |
| </ul> |
| <li><a href="#Ruby_nn40">Typemap variables</a> |
| <li><a href="#Ruby_nn41">Useful Functions</a> |
| <ul> |
| <li><a href="#Ruby_nn42">C Datatypes to Ruby Objects</a> |
| <li><a href="#Ruby_nn43">Ruby Objects to C Datatypes</a> |
| <li><a href="#Ruby_nn44">Macros for VALUE</a> |
| <li><a href="#Ruby_nn45">Exceptions</a> |
| <li><a href="#Ruby_nn46">Iterators</a> |
| </ul> |
| <li><a href="#Ruby_nn47">Typemap Examples</a> |
| <li><a href="#Ruby_nn48">Converting a Ruby array to a char **</a> |
| <li><a href="#Ruby_nn49">Collecting arguments in a hash</a> |
| <li><a href="#Ruby_nn50">Pointer handling</a> |
| <ul> |
| <li><a href="#Ruby_nn51">Ruby Datatype Wrapping</a> |
| </ul> |
| <li><a href="#Ruby_nn52">Example: STL Vector to Ruby Array</a> |
| </ul> |
| <li><a href="#Ruby_nn65">Docstring Features</a> |
| <ul> |
| <li><a href="#Ruby_nn66">Module docstring</a> |
| <li><a href="#Ruby_nn67">%feature("autodoc")</a> |
| <ul> |
| <li><a href="#Ruby_nn68">%feature("autodoc", "0")</a> |
| <li><a href="#Ruby_autodoc1">%feature("autodoc", "1")</a> |
| <li><a href="#Ruby_autodoc2">%feature("autodoc", "2")</a> |
| <li><a href="#Ruby_feature_autodoc3">%feature("autodoc", "3")</a> |
| <li><a href="#Ruby_nn70">%feature("autodoc", "docstring")</a> |
| </ul> |
| <li><a href="#Ruby_nn71">%feature("docstring")</a> |
| </ul> |
| <li><a href="#Ruby_nn53">Advanced Topics</a> |
| <ul> |
| <li><a href="#Ruby_nn54">Operator overloading</a> |
| <li><a href="#Ruby_nn55">Creating Multi-Module Packages</a> |
| <li><a href="#Ruby_nn56">Specifying Mixin Modules</a> |
| </ul> |
| <li><a href="#Ruby_nn57">Memory Management</a> |
| <ul> |
| <li><a href="#Ruby_nn58">Mark and Sweep Garbage Collector </a> |
| <li><a href="#Ruby_nn59">Object Ownership</a> |
| <li><a href="#Ruby_nn60">Object Tracking</a> |
| <li><a href="#Ruby_nn61">Mark Functions</a> |
| <li><a href="#Ruby_nn62">Free Functions</a> |
| <li><a href="#Ruby_nn63">Embedded Ruby and the C++ Stack</a> |
| </ul> |
| </ul> |
| </div> |
| <!-- INDEX --> |
| |
| |
| |
| <p>This chapter describes SWIG's support of Ruby.</p> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn2"></a>31.1 Preliminaries</H2> |
| |
| |
| <p> 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 your system supports shared libraries and |
| dynamic loading. SWIG will work with or without dynamic loading, but |
| the compilation process will vary. </p> |
| |
| |
| |
| |
| |
| <p>This chapter covers most SWIG features, but in less depth than |
| is found in earlier chapters. At the very least, make sure you also |
| 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"></a>31.1.1 Running SWIG</H3> |
| |
| |
| <p> To build a Ruby module, run SWIG using the <tt>-ruby</tt> |
| option:</p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -ruby example.i</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If building a C++ extension, add the <tt>-c++</tt> |
| option: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -c++ -ruby example.i</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> This creates a file <tt>example_wrap.c</tt> (<tt>example_wrap.cxx</tt> |
| 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"></a>31.1.2 Getting the right header files</H3> |
| |
| |
| <p> 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> |
| |
| |
| |
| |
| |
| <div class="code shell diagram"> |
| <pre>/usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h<br>/usr/local/lib/ruby/1.6/i686-linux/ruby.h<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The exact location may vary on your machine, but the above |
| location is typical. If you are not entirely sure where Ruby is |
| installed, you can run Ruby to find out. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>ruby -e 'puts $:.join("\n")'</b><br>/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux<br>/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .<br> </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn5"></a>31.1.3 Compiling a dynamic module</H3> |
| |
| |
| <p> Ruby extension modules are typically compiled into shared |
| libraries that the interpreter loads dynamically at runtime. Since the |
| exact commands for doing this vary from platform to platform, your best |
| bet is to follow the steps described in the <tt>README.EXT</tt> |
| file from the Ruby distribution: </p> |
| |
| |
| |
| |
| |
| <ol> |
| |
| |
| |
| |
| |
| <li> |
| |
| |
| |
| |
| <p>Create a file called <tt>extconf.rb</tt> that |
| looks like the following:</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| |
| |
| |
| |
| <pre>require 'mkmf'<br>create_makefile('example')<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li> |
| |
| |
| |
| |
| <p>Type the following to build the extension:</p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| |
| |
| |
| |
| <pre>$ <b>ruby extconf.rb</b><br>$ <b>make</b><br>$ <b>make install</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| </ol> |
| |
| |
| |
| |
| |
| <p> Of course, there is the problem that mkmf does not work |
| correctly on all platforms, e.g, HPUX. If you need to add your own make |
| rules to the file that <tt>extconf.rb</tt> produces, you |
| can add this: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>open("Makefile", "a") { |mf|<br> puts <<EOM<br> # Your make rules go here<br> EOM<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> to the end of the <tt>extconf.rb</tt> file. If |
| for some reason you don't want to use the standard approach, you'll |
| need to determine the correct compiler and linker flags for your build |
| platform. For example, a typical sequence of commands for the Linux |
| operating system would look something like this: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -ruby example.i</b><br>$ <b>gcc -c example.c</b><br>$ <b>gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux</b> <br>$ <b>gcc -shared example.o example_wrap.o -o example.so</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> For other platforms it may be necessary to compile with the <tt>-fPIC</tt> |
| option to generate position-independent code. If in doubt, consult the |
| manual pages for your compiler and linker to determine the correct set |
| of options. You might also check the <a href="http://www.dabeaz.com/cgi-bin/wiki.pl">SWIG Wiki</a> |
| for additional information. </p> |
| |
| <H3><a name="Ruby_nn6"></a>31.1.4 Using your module</H3> |
| |
| |
| <p> 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> extension |
| module is imported by requiring the <b>etc</b> feature: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre># The feature name begins with a lowercase letter...<br>require 'etc'<br><br># ... but the module name begins with an uppercase letter<br>puts "Your login name: #{Etc.getlogin}"<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To stay consistent with this practice, you should always |
| specify a <b>lowercase</b> module name with SWIG's <tt>%module</tt> |
| directive. SWIG will automatically correct the resulting Ruby module |
| name for your extension. So for example, a SWIG interface file that |
| begins with: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> will result in an extension module using the feature name |
| "example" and Ruby module name "Example". </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn7"></a>31.1.5 Static linking</H3> |
| |
| |
| <p> 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 |
| loading support on certain machines. However, the situation has |
| improved greatly over the last few years and you should not consider |
| this approach unless there is really no other option. </p> |
| |
| |
| |
| |
| |
| <p>The usual procedure for adding a new module to Ruby involves |
| 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"></a>31.1.6 Compilation of C++ extensions</H3> |
| |
| |
| <p> On most machines, C++ extension modules should be linked |
| using the C++ compiler. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -c++ -ruby example.i</b><br>$ <b>g++ -c example.cxx</b><br>$ <b>g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux</b><br>$ <b>g++ -shared example.o example_wrap.o -o example.so</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If you've written an <tt>extconf.rb</tt> script |
| to automatically generate a <tt>Makefile</tt> for your C++ |
| extension module, keep in mind that (as of this writing) Ruby still |
| uses <tt>gcc</tt> and not <tt>g++</tt> as its |
| linker. As a result, the required C++ runtime library support will not |
| be automatically linked into your extension module and it may fail to |
| load on some platforms. A workaround for this problem is use the <tt>mkmf</tt> |
| module's <tt>append_library()</tt> method to add one of |
| the C++ runtime libraries to the list of libraries linked into your |
| extension, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>require 'mkmf'<br>$libs = append_library($libs, "supc++")<br>create_makefile('example')<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn9"></a>31.2 Building Ruby Extensions under Windows 95/NT</H2> |
| |
| |
| <p> 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 can be loaded into the Ruby interpreter. For all |
| recent versions of Ruby, the procedure described above (i.e. using an <tt>extconf.rb</tt> |
| script) will work with Windows as well; you should be able to build |
| your code into a DLL by typing: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>C:\swigtest> <b>ruby extconf.rb</b><br>C:\swigtest> <b>nmake</b><br>C:\swigtest> <b>nmake install</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The remainder of this section covers the process of compiling |
| SWIG-generated Ruby extensions with Microsoft Visual C++ 6 (i.e. within |
| the Developer Studio IDE, instead of using the command line tools). In |
| order to build extensions, you may need to download the source |
| distribution to the Ruby package, as you will need the Ruby header |
| files. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn10"></a>31.2.1 Running SWIG from Developer Studio</H3> |
| |
| |
| <p> If you are developing your application within Microsoft |
| developer studio, SWIG can be invoked as a custom build option. The |
| process roughly follows these steps : </p> |
| |
| |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li> Open up a new workspace and use the AppWizard to select a |
| DLL project. </li> |
| |
| |
| |
| |
| |
| <li> Add both the SWIG interface file (the .i file), any |
| supporting C files, and the name of the wrapper file that will be |
| created by SWIG (i.e. <tt>example_wrap.c</tt>). Note : If |
| using C++, choose a different suffix for the wrapper file such as <tt>example_wrap.cxx</tt>. |
| Don't worry if the wrapper file doesn't exist yet--Developer Studio |
| will keep a reference to it around. </li> |
| |
| |
| |
| |
| |
| <li> Select the SWIG interface file and go to the settings |
| menu. Under settings, select the "Custom Build" option. </li> |
| |
| |
| |
| |
| |
| <li> Enter "SWIG" in the description field. </li> |
| |
| |
| |
| |
| |
| <li> Enter "<tt>swig -ruby -o |
| $(ProjDir)\$(InputName)_wrap.c $(InputPath)</tt>" in the "Build |
| command(s) field". You may have to include the path to swig.exe. </li> |
| |
| |
| |
| |
| |
| <li> Enter "<tt>$(ProjDir)\$(InputName)_wrap.c</tt>" |
| in the "Output files(s) field". </li> |
| |
| |
| |
| |
| |
| <li> Next, select the settings for the entire project and go to |
| the C/C++ tab and select the Preprocessor category. Add NT=1 to the |
| Preprocessor definitions. This must be set else you will get |
| compilation errors. Also add IMPORT to the preprocessor definitions, |
| else you may get runtime errors. Also add the include directories for |
| your Ruby installation under "Additional include directories". </li> |
| |
| |
| |
| |
| |
| <li> Next, select the settings for the entire project and go to |
| the Link tab and select the General category. Set the name of the |
| output file to match the name of your Ruby module (i.e.. example.dll). |
| Next add the Ruby library file to your link libraries under |
| Object/Library modules. For example "mswin32-ruby16.lib. You also need |
| to add the path to the library under the Input tab - Additional library |
| path. </li> |
| |
| |
| |
| |
| |
| <li> Build your project. </li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| |
| |
| <p> Now, assuming all went well, SWIG will be automatically |
| invoked when you build your project. Any changes made to the interface |
| file will result in SWIG being automatically invoked to produce a new |
| version of the wrapper file. To run your new Ruby extension, simply run |
| Ruby and use the <tt>require</tt> command as normal. For |
| example if you have this ruby file run.rb:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre># file: run.rb<br>require 'Example'<br><br># Call a c function<br>print "Foo = ", Example.Foo, "\n"<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Ensure the dll just built is in your path or current |
| directory, then run the Ruby script from the DOS/Command prompt: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>C:\swigtest> <b>ruby run.rb</b><br>Foo = 3.0<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn11"></a>31.3 The Ruby-to-C/C++ Mapping</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"></a>31.3.1 Modules</H3> |
| |
| |
| <p> The SWIG <tt>%module</tt> directive specifies |
| the name of the Ruby module. If you specify: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> then everything is wrapped into a Ruby module named <tt>Example</tt> |
| that is nested directly under the global module. You can specify a more |
| deeply nested module by specifying the fully-qualified module name in |
| quotes, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module "foo::bar::spam"</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> An alternate method of specifying a nested module name is to |
| use the <span style="font-family: monospace;">-prefix</span> |
| option on the SWIG command line. The prefix that you specify with this |
| option will be prepended to the module name specified with the <span style="font-family: monospace;">%module</span> |
| directive in your SWIG interface file. So for example, this declaration |
| at the top of your SWIG interface file:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module "foo::bar::spam"</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> will result in a nested module name of <span style="font-family: monospace;">Foo::Bar::Spam</span>, |
| but you can achieve the <span style="font-style: italic;">same</span> |
| effect by specifying:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module spam</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> and then running SWIG with the <span style="font-family: monospace;">-prefix</span> command |
| line option:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -ruby -prefix "foo::bar::" example.i</b></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Starting with SWIG 1.3.20, you can also choose to wrap |
| everything into the global module by specifying the <tt>-globalmodule</tt> |
| option on the SWIG command line, i.e. </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -ruby -globalmodule example.i</b></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note that this does not relieve you of the requirement of |
| specifying the SWIG module name with the <tt>%module</tt> |
| directive (or the <tt>-module</tt> command-line option) as |
| described earlier. </p> |
| |
| |
| |
| |
| |
| <p>When choosing a module name, do not use the same name as a |
| built-in Ruby command or standard module name, as the results may be |
| unpredictable. Similarly, if you're using the <tt>-globalmodule</tt> |
| 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"></a>31.3.2 Functions</H3> |
| |
| |
| <p> Global functions are wrapped as Ruby module methods. For |
| example, given the SWIG interface file <tt>example.i</tt>: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>int fact(int n);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> and C source file <tt>example.c</tt>: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>int fact(int n) {<br> if (n == 0)<br> return 1;<br> return (n * fact(n-1));<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> SWIG will generate a method <i>fact</i> in the <i>Example</i> |
| module that can be used like so: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>Example.fact(4)</b><br>24<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn14"></a>31.3.3 Variable Linking</H3> |
| |
| |
| <p> 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. For example, the following SWIG interface file declares |
| two global variables: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// SWIG interface file with global variables<br>%module example<br>...<br>%inline %{<br>extern int variable1;<br>extern double Variable2;<br>%}<br>...<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Now look at the Ruby interface:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>Example.variable1 = 2</b><br>2<br>irb(main):003:0> <b>Example.Variable2 = 4 * 10.3</b><br>41.2<br>irb(main):004:0> <b>Example.Variable2</b><br>41.2<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If you make an error in variable assignment, you will receive |
| an error message. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):005:0> <b>Example.Variable2 = "hello"</b><br>TypeError: no implicit conversion to float from string<br>from (irb):5:in `Variable2='<br>from (irb):5<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If a variable is declared as <tt>const</tt>, it |
| is wrapped as a read-only variable. Attempts to modify its value will |
| result in an error. </p> |
| |
| |
| |
| |
| |
| <p>To make ordinary variables read-only, you can also use the <tt>%immutable</tt> |
| directive. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%immutable;<br>%inline %{<br>extern char *path;<br>%}<br>%mutable;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The <tt>%immutable</tt> directive stays in |
| effect until it is explicitly disabled using <tt>%mutable</tt>. |
| </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn15"></a>31.3.4 Constants</H3> |
| |
| |
| <p> 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: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>#define PI 3.14159<br>#define VERSION "1.0"<br><br>%constant int FOO = 42;<br>%constant const char *path = "/usr/local";<br><br>const int BAR = 32;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Remember to use the :: operator in Ruby to get at these |
| constant values, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>Example::PI</b><br>3.14159<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn16"></a>31.3.5 Pointers</H3> |
| |
| |
| <p> "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, for example, consider a SWIG interface file |
| containing only the declarations: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>Foo *get_foo();<br>void set_foo(Foo *foo);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> For this case, the <i>get_foo()</i> method |
| returns an instance of an internally generated Ruby class: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>foo = Example::get_foo()</b><br>#<SWIG::TYPE_p_Foo:0x402b1654><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> A <tt>NULL</tt> pointer is always represented by |
| the Ruby <tt>nil</tt> object. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn17"></a>31.3.6 Structures</H3> |
| |
| |
| <p> 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 declaration: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>struct Vector {<br> double x, y;<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> gets wrapped as a <tt>Vector</tt> class, with |
| Ruby instance methods <tt>x</tt>, <tt> x=</tt>, |
| <tt>y</tt> and <tt>y=</tt>. These methods can |
| be used to access structure data from Ruby as follows: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'Example'</b><br>true<br>irb(main):002:0> <b>f = Example::Vector.new</b><br>#<Example::Vector:0x4020b268><br>irb(main):003:0> <b>f.x = 10</b><br>nil<br>irb(main):004:0> <b>f.x</b><br>10.0<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Similar access is provided for unions and the public data |
| members of C++ classes.</p> |
| |
| |
| |
| |
| |
| <p><tt>const</tt> members of a structure are |
| read-only. Data members can also be forced to be read-only using the <tt>%immutable</tt> |
| directive (in C++, <tt>private</tt> may also be used). For |
| example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>struct Foo {<br> ...<br> %immutable;<br> int x; /* Read-only members */<br> char *name;<br> %mutable;<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When <tt>char *</tt> members of a structure are |
| wrapped, the contents are assumed to be dynamically allocated using <tt>malloc</tt> |
| or <tt>new</tt> (depending on whether or not SWIG is run |
| with the <tt>-c++</tt> option). When the structure member |
| is set, the old contents will be released and a new value created. If |
| this is not the behavior you want, you will have to use a typemap |
| (described shortly). </p> |
| |
| |
| |
| |
| |
| <p>Array members are normally wrapped as read-only. For example, |
| this code: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>struct Foo {<br> int x[50];<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> produces a single accessor function like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>int *Foo_x_get(Foo *self) {<br> return self->x;<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If you want to set an array member, you will need to supply a |
| "memberin" typemap described in the <a href="#ruby_cpp_smart_pointers">section on typemaps</a>. |
| As a special case, SWIG does generate code to set array members of type |
| <tt>char</tt> (allowing you to store a Ruby string in the |
| structure). </p> |
| |
| |
| |
| |
| |
| <p>When structure members are wrapped, they are handled as |
| pointers. For example, </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>struct Foo {<br> ...<br>};<br><br>struct Bar {<br> Foo f;<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> generates accessor functions such as this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <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> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn18"></a>31.3.7 C++ classes</H3> |
| |
| |
| <p> 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. Additionally, public member functions for the class are |
| wrapped as Ruby instance methods, and public static member functions |
| are wrapped as Ruby singleton methods. So, given the C++ class |
| declaration: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class List {<br>public:<br> List();<br> ~List();<br> int search(char *item);<br> void insert(char *item);<br> void remove(char *item);<br> char *get(int n);<br> int length;<br> static void print(List *l);<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> SWIG would create a <tt>List</tt> class with: </p> |
| |
| |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li> instance methods <i>search</i>, <i>insert</i>, |
| <i>remove</i>, and <i>get</i>; </li> |
| |
| |
| |
| |
| |
| <li> instance methods <i>length</i> and <i>length=</i> |
| (to get and set the value of the <i>length</i> data |
| member); and, </li> |
| |
| |
| |
| |
| |
| <li> a <i>print</i> singleton method for the |
| class. </li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| |
| |
| <p> In Ruby, these functions are used as follows: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <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> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn19"></a>31.3.8 C++ Inheritance</H3> |
| |
| |
| <p> The SWIG type-checker is fully aware of C++ inheritance. |
| Therefore, if you have classes like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Parent {<br> ...<br>};<br><br>class Child : public Parent {<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> those classes are wrapped into a hierarchy of Ruby classes |
| that reflect the same inheritance structure. All of the usual Ruby |
| utility methods work normally: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>irb(main):001:0> <b>c = Child.new</b><br>#<Bar:0x4016efd4><br>irb(main):002:0> <b>c.instance_of? Child</b><br>true<br>irb(main):003:0> <b>b.instance_of? Parent</b><br>false<br>irb(main):004:0> <b>b.is_a? Child</b><br>true<br>irb(main):005:0> <b>b.is_a? Parent</b><br>true<br>irb(main):006:0> <b>Child < Parent</b><br>true<br>irb(main):007:0> <b>Child > Parent</b><br>false<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Furthermore, if you have a function like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void spam(Parent *f);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> then the function <tt>spam()</tt> accepts <tt>Parent</tt>* |
| or a pointer to any class derived from <tt>Parent</tt>. </p> |
| |
| |
| |
| |
| |
| <p>Until recently, the Ruby module for SWIG didn't support |
| multiple inheritance, and this is still the default behavior. This |
| doesn't mean that you can't wrap C++ classes which inherit from |
| multiple base classes; it simply means that only the <b>first</b> |
| base class listed in the class declaration is considered, and any |
| additional base classes are ignored. As an example, consider a SWIG |
| interface file with a declaration like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Derived : public Base1, public Base2<br>{<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> For this case, the resulting Ruby class (<tt>Derived</tt>) |
| will only consider <tt>Base1</tt> as its superclass. It |
| won't inherit any of <tt>Base2</tt>'s member functions or |
| data and it won't recognize <tt>Base2</tt> as an |
| "ancestor" of <tt>Derived</tt> (i.e. the <em>is_a?</em> |
| relationship would fail). When SWIG processes this interface file, |
| you'll see a warning message like: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.<br>Multiple inheritance is not supported in Ruby.<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Starting with SWIG 1.3.20, the Ruby module for SWIG provides |
| limited support for multiple inheritance. Because the approach for |
| dealing with multiple inheritance introduces some limitations, this is |
| an optional feature that you can activate with the <tt>-minherit</tt> |
| command-line option: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -c++ -ruby -minherit example.i</b></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Using our previous example, if your SWIG interface file |
| contains a declaration like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Derived : public Base1, public Base2<br>{<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> and you run SWIG with the <tt>-minherit</tt> |
| command-line option, then you will end up with a Ruby class <tt>Derived</tt> |
| that appears to "inherit" the member data and functions from both <tt>Base1</tt> |
| and <tt>Base2</tt>. What actually happens is that three |
| different top-level classes are created, with Ruby's <tt>Object</tt> |
| class as their superclass. Each of these classes defines a nested |
| module named <tt>Impl</tt>, and it's in these nested <tt>Impl</tt> |
| modules that the actual instance methods for the classes are defined, |
| i.e. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>class Base1<br> module Impl<br> # Define Base1 methods here<br> end<br> include Impl<br>end<br><br>class Base2<br> module Impl<br> # Define Base2 methods here<br> end<br> include Impl<br>end<br><br>class Derived<br> module Impl<br> include Base1::Impl<br> include Base2::Impl<br> # Define Derived methods here<br> end<br> include Impl<br>end<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Observe that after the nested <tt>Impl</tt> |
| module for a class is defined, it is mixed-in to the class itself. Also |
| observe that the <tt>Derived::Impl</tt> module first |
| mixes-in its base classes' <tt>Impl</tt> modules, thus |
| "inheriting" all of their behavior. </p> |
| |
| |
| |
| |
| |
| <p>The primary drawback is that, unlike the default mode of |
| operation, neither <tt>Base1</tt> nor <tt>Base2</tt> |
| is a true superclass of <tt>Derived</tt> anymore: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>obj = Derived.new<br>obj.is_a? Base1 # this will return false...<br>obj.is_a? Base2 # ... and so will this<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In most cases, this is not a serious problem since objects of |
| type <tt>Derived</tt> 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>). </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn20"></a>31.3.9 C++ Overloaded Functions</H3> |
| |
| |
| <p> C++ overloaded functions, methods, and constructors are |
| mostly supported by SWIG. For example, if you have two functions like |
| this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void foo(int);<br>void foo(char *c);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> You can use them in Ruby in a straightforward manner: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>foo(3)</b> # foo(int)<br>irb(main):002:0> <b>foo("Hello")</b> # foo(char *c)<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Similarly, if you have a class like this,</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Foo {<br>public:<br> Foo();<br> Foo(const Foo &);<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>you can write Ruby code like this:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>f = Foo.new</b> # Create a Foo<br>irb(main):002:0> <b>g = Foo.new(f)</b> # Copy f<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Overloading support is not quite as flexible as in C++. |
| Sometimes there are methods that SWIG can't disambiguate. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void spam(int);<br>void spam(short);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>or</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void foo(Bar *b);<br>void foo(Bar &b);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If declarations such as these appear, you will get a warning |
| message like this: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)<br>at example.i:11.<br> </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To fix this, you either need to ignore or rename one of the |
| methods. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%rename(spam_short) spam(short);<br>...<br>void spam(int); <br>void spam(short); // Accessed as spam_short<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>or</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%ignore spam(short);<br>...<br>void spam(int); <br>void spam(short); // Ignored<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> SWIG resolves overloaded functions and methods using a |
| disambiguation scheme that ranks and sorts declarations according to a |
| set of type-precedence rules. The order in which declarations appear in |
| the input does not matter except in situations where ambiguity |
| 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"></a>31.3.10 C++ Operators</H3> |
| |
| |
| <p> 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 declares an overloaded addition operator, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Complex {<br> ...<br> Complex operator+(Complex &);<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> the resulting Ruby class will also support the addition (+) |
| method correctly. </p> |
| |
| |
| |
| |
| |
| <p>For cases where SWIG's built-in support is not sufficient, C++ |
| operators can be wrapped using the <tt>%rename</tt> |
| directive (available on SWIG 1.3.10 and later releases). All you need |
| to do is give the operator the name of a valid Ruby identifier. For |
| example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%rename(add_complex) operator+(Complex &, Complex &);<br>...<br>Complex operator+(Complex &, Complex &);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Now, in Ruby, you can do this:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>a = Example::Complex.new(2, 3)<br>b = Example::Complex.new(4, -1)<br>c = Example.add_complex(a, b)<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> More details about wrapping C++ operators into Ruby operators |
| is discussed in the <a href="#ruby_operator_overloading">section |
| on operator overloading</a>. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn22"></a>31.3.11 C++ namespaces</H3> |
| |
| |
| <p> 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, </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>namespace foo {<br> int fact(int n);<br> struct Vector {<br> double x,y,z;<br> };<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>it works in Ruby as follows:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>Example.fact(3)</b><br>6<br>irb(main):003:0> <b>v = Example::Vector.new</b><br>#<Example::Vector:0x4016f4d4><br>irb(main):004:0> <b>v.x = 3.4</b><br>3.4<br>irb(main):004:0> <b>v.y</b><br>0.0<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If your program has more than one namespace, name conflicts |
| (if any) can be resolved using <tt>%rename</tt> For |
| example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%rename(Bar_spam) Bar::spam;<br><br>namespace Foo {<br> int spam();<br>}<br><br>namespace Bar {<br> int spam();<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If you have more than one namespace and your want to keep |
| their symbols separate, consider wrapping them as separate SWIG |
| modules. 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. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn23"></a>31.3.12 C++ templates</H3> |
| |
| |
| <p> 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 template instantiation. To do this, you use the <tt>%template</tt> |
| directive. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%{<br>#include "pair.h"<br>%}<br><br>template<class T1, class T2><br>struct pair {<br> typedef T1 first_type;<br> typedef T2 second_type;<br> T1 first;<br> T2 second;<br> pair();<br> pair(const T1&, const T2&);<br> ~pair();<br>};<br><br>%template(Pairii) pair<int,int>;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In Ruby:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>require 'example'</b><br>true<br>irb(main):002:0> <b>p = Example::Pairii.new(3, 4)</b><br>#<Example:Pairii:0x4016f4df><br>irb(main):003:0> <b>p.first</b><br>3<br>irb(main):004:0> <b>p.second</b><br>4<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn23_1"></a>31.3.13 C++ Standard Template Library (STL)</H3> |
| |
| |
| <p> On a related note, the standard SWIG library contains a |
| number of modules that provide typemaps for standard C++ library |
| classes (such as <tt>std::pair</tt>, <tt>std::string</tt> |
| and <tt>std::vector</tt>). These library modules don't |
| provide wrappers around the templates themselves, but they do make it |
| convenient for users of your extension module to pass Ruby objects |
| (such as arrays and strings) to wrapped C++ code that expects instances |
| of standard C++ templates. For example, suppose the C++ library you're |
| wrapping has a function that expects a vector of floats: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>float sum(const std::vector<float>& values);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Rather than go through the hassle of writing an "in" typemap |
| to convert an array of Ruby numbers into a |
| std::vector<float>, you can just use the <tt>std_vector.i</tt> |
| module from the standard SWIG library: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br><b>%include std_vector.i</b><br>float sum(const std::vector<float>& values);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Ruby's STL wrappings provide additional methods to make them |
| behave more similarly to Ruby's native classes.</p> |
| |
| |
| |
| |
| |
| <p>Thus, you can do, for example:</p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>v = IntVector.new<span class="targetlang"><br>v << 2</span><span class="targetlang"><br>v << 3<br>v << 4<br>v.each { |x| puts x }<br><span style="font-weight: bold;"><br>=> 2</span><br style="font-weight: bold;"><span style="font-weight: bold;">3</span><br style="font-weight: bold;"><span style="font-weight: bold;">4<br></span>v.delete_if { |x| x == 3 }<br><span style="font-weight: bold;">=> [2,4]</span></span></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>The SWIG Ruby module provides also the ability for all the STL |
| containers to carry around Ruby native objects (Fixnum, Classes, etc) |
| making them act almost like Ruby's own Array, Hash, etc. To |
| do |
| that, you need to define a container that contains a swig::GC_VALUE, |
| like:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="code">%module |
| nativevector<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %{<br> |
| |
| |
| |
| |
| |
| std::vector< swig::GC_VALUE > NativeVector;<br> |
| |
| |
| |
| |
| |
| %}<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %template(NativeVector) std::vector< swig::GC_VALUE >;<br> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <p>This vector can then contain any Ruby object, making them |
| almost identical to Ruby's own Array class.</p> |
| |
| |
| |
| |
| |
| <div class="targetlang"><span style="font-family: monospace;">require 'nativevector'</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">include NativeVector</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">v = NativeVector.new</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">v << 1</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">v << |
| [1,2]</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">v << |
| 'hello'</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">class A; end</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">v << |
| A.new</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-family: monospace;">puts v</span><br style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <span style="font-weight: bold; font-family: monospace;">=> |
| [1, [1,2], 'hello', #<A:0x245325>]</span></div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <p>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.</p> |
| |
| |
| |
| |
| |
| <H3><a name="C_STL_Functors"></a>31.3.14 C++ STL Functors</H3> |
| |
| |
| <p>Some containers in the STL allow you to modify their default |
| behavior by using so called functors or function objects. |
| Functors are often just a very simple struct with<span style="font-family: monospace;"> operator()</span> |
| redefined or an actual C/C++ function. This allows you, for |
| example, to always keep the sort order of a STL container to your |
| liking.</p> |
| |
| |
| |
| |
| |
| <p>The Ruby STL mappings allows you to modify those containers |
| that |
| support functors using Ruby procs or methods, instead. |
| Currently, |
| this includes <span style="font-family: monospace;">std::set</span>, |
| <span style="font-family: monospace;">set::map</span>, |
| <span style="font-family: monospace;">std::multiset</span> |
| and <span style="font-family: monospace;">std::multimap</span>.</p> |
| |
| |
| |
| |
| |
| <p>The functors in swig are called<span style="font-family: monospace;"> swig::UnaryFunction</span> |
| and <span style="font-family: monospace;">swig::BinaryFunction</span>.<br> |
| |
| |
| |
| |
| |
| For C++ predicates (ie. functors that must return bool as a result) <span style="font-family: monospace;">swig::UnaryPredicate</span> |
| and <span style="font-family: monospace;">swig::BinaryPredicate</span> |
| are provided.</p> |
| |
| |
| |
| |
| |
| <p>As an example, if given this swig file:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="code">%module |
| intset;<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %include std_set.i<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %typemap(IntSet) std::set< int, swig::BinaryPredicate |
| >;</div> |
| |
| |
| |
| |
| |
| <p>You can then use the set from Ruby with or without a proc |
| object as a predicate:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="targetlang">require |
| 'intset'<br> |
| |
| |
| |
| |
| |
| include Intset<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| # Default sorting behavior defined in C++<br> |
| |
| |
| |
| |
| |
| a = IntSet.new<br> |
| |
| |
| |
| |
| |
| a << 1<br> |
| |
| |
| |
| |
| |
| a << 2<br> |
| |
| |
| |
| |
| |
| a << 3<br> |
| |
| |
| |
| |
| |
| a<br> |
| |
| |
| |
| |
| |
| <span style="font-weight: bold;">=> |
| [1,2,3]</span><br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| # Custom sorting behavior defined by a Ruby proc |
| <div><span class="targetlang">b = IntSet.new( proc { |
| |a,b| a > b } )</span><br> |
| |
| |
| |
| |
| |
| b << 1<br> |
| |
| |
| |
| |
| |
| b << 2<br> |
| |
| |
| |
| |
| |
| b << 3<br> |
| |
| |
| |
| |
| |
| b<br style="font-weight: bold;"> |
| |
| |
| |
| |
| |
| <span style="font-weight: bold;">=> |
| [3,2,1]</span> </div> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_C_Iterators"></a>31.3.15 C++ STL Iterators</H3> |
| |
| |
| <p>The STL is well known for the use of iterators. There |
| are a number of iterators possible with different properties, but in |
| general there are two main categories: const iterators and non-const |
| iterators. The const iterators can access and not modify the |
| values they point at, while the non-const iterators can both read and |
| modify the values.</p> |
| |
| |
| |
| |
| |
| <p>The Ruby STL wrappings support both type of iterators by using |
| a proxy class in-between. This proxy class is <span style="font-family: monospace;">swig::Iterator or |
| swig::ConstIterator. </span>Derived from them are template |
| classes that need to be initialized with the actual iterator for the |
| container you are wrapping and often times with the beginning and |
| ending points of the iteration range. </p> |
| |
| |
| |
| |
| |
| <p>The SWIG STL library already provides typemaps to all the |
| standard containers to do this wrapping automatically for you, but if |
| you have your own STL-like iterator, you will need to write your own |
| typemap for them. For out typemaps, the special functions <span style="font-family: monospace;">make_const_iterator</span> and <span style="font-family: monospace;">make_nonconst_iterator</span> are provided.</p> |
| |
| <p>These can be used either like:</p> |
| |
| <div style="font-family: monospace;" class="code">make_const_iterator( iterator, rubyclass );<br> |
| |
| make_const_iterator( iterator, iterator_begin, iterator_end, rubyclass );</div> |
| |
| |
| |
| |
| |
| <p>The iterators support a <span style="font-family: monospace;">next()</span> and <span style="font-family: monospace;">previous() </span>member function to |
| just change the iterator without returning anything. <span style="font-family: monospace;">previous()</span> |
| should obviously only be used for bidirectional iterators. You |
| can also advance the iterator multiple steps by using standard math |
| operations like <span style="font-family: monospace;">+=</span>.</p> |
| |
| <p>The |
| value the iterator points at can be accessed with <span style="font-family: monospace;">value()</span> -- this is equivalent to dereferencing it with <span style="font-family: monospace;">*i</span>. |
| For non-const iterators, a <span style="font-family: monospace;">value=()</span> function |
| is also provided which allows you to change the value pointed by the |
| iterator. This is equivalent to the C++ construct of dereferencing and assignment, like <span style="font-family: monospace;">*i = something</span>. </p> |
| |
| |
| |
| |
| |
| <p>Thus, given say a vector class of doubles defined as:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="code"><span class="code">%module doublevector</span><br class="code"> |
| |
| |
| |
| |
| |
| <span class="code"><br> |
| |
| |
| |
| |
| |
| %include std_vector.i</span><br class="code"> |
| |
| |
| |
| |
| |
| <span class="code"><br> |
| |
| |
| |
| |
| |
| %template(DoubleVector) std::vector<double>;</span></div> |
| |
| |
| |
| |
| |
| <p>Its iterator can then be used from Ruby like:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="targetlang">require |
| 'doublevector'<br> |
| |
| |
| |
| |
| |
| include Doublevector<br> |
| |
| <br> |
| |
| |
| |
| |
| |
| v = DoubleVector.new<br> |
| |
| |
| |
| |
| |
| v << 1<br> |
| |
| |
| |
| |
| |
| v << 2<br> |
| |
| |
| |
| |
| |
| v << 3<br> |
| |
| <br> |
| |
| #<br> |
| |
| # an elaborate and less efficient way of doing v.map! { |x| x+2 }<br> |
| |
| #<br> |
| |
| |
| |
| |
| |
| i = v.begin<br> |
| |
| |
| |
| |
| |
| e = v.end<br> |
| |
| |
| |
| |
| |
| while i != e<br> |
| |
| |
| |
| |
| |
| val = i.value<br> |
| |
| |
| |
| |
| |
| val += 2<br> |
| |
| |
| |
| |
| |
| i.value = val<br> |
| |
| |
| |
| |
| |
| i.next<br> |
| |
| |
| |
| |
| |
| end<br> |
| |
| |
| |
| |
| i<br> |
| |
| |
| |
| |
| <span style="font-weight: bold;">>> [3, 4, 5 ]</span></div> |
| |
| |
| |
| |
| |
| <br> |
| |
| <p>If you'd rather have STL classes without any iterators, you should define<span style="font-family: monospace;"> -DSWIG_NO_EXPORT_ITERATOR_METHODS </span>when running swig.</p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn24"></a>31.3.16 C++ Smart Pointers</H3> |
| |
| |
| <p> 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 template class that implements <tt>operator->()</tt> |
| like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>template<class T> class SmartPtr {<br> ...<br> T *operator->();<br> ...<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Then, if you have a class like this,</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Foo {<br>public:<br> int x;<br> int bar();<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>A smart pointer would be used in C++ as follows:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>SmartPtr<Foo> p = CreateFoo(); // Created somehow (not shown)<br>...<br>p->x = 3; // Foo::x<br>int y = p->bar(); // Foo::bar<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To wrap this in Ruby, simply tell SWIG about the <tt>SmartPtr</tt> |
| class and the low-level <tt>Foo</tt> object. Make sure you |
| instantiate <tt>SmartPtr</tt> using <tt>%template</tt> |
| if necessary. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br>...<br>%template(SmartPtrFoo) SmartPtr<Foo>;<br>...<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Now, in Ruby, everything should just "work":</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>p = Example::CreateFoo()</b> # Create a smart-pointer somehow<br>#<Example::SmartPtrFoo:0x4016f4df><br>irb(main):002:0> <b>p.x = 3</b> # Foo::x<br>3<br>irb(main):003:0> <b>p.bar()</b> # Foo::bar<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If you ever need to access the underlying pointer returned by |
| <tt>operator->()</tt> itself, simply use the <tt>__deref__()</tt> |
| method. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):004:0> <b>f = p.__deref__()</b> # Returns underlying Foo *<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn25"></a>31.3.17 Cross-Language Polymorphism</H3> |
| |
| |
| <p> SWIG's Ruby module supports cross-language polymorphism |
| (a.k.a. the "directors" feature) similar to that for SWIG's Python |
| module. Rather than duplicate the information presented in the <a href="Ruby">Python</a> chapter, this |
| section just notes the differences that you need to be aware of when |
| using this feature with Ruby. </p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn26"></a>31.3.17.1 Exception Unrolling</H4> |
| |
| |
| <p> 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 will be raised in the Ruby code. By |
| default, those exceptions are ignored, which simply means that the |
| exception will be exposed to the Ruby interpreter. If you would like to |
| change this behavior, you can use the <tt>%feature("director:except")</tt> |
| directive to indicate what action should be taken when a Ruby exception |
| is raised. The following code should suffice in most cases: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%feature("director:except") {<br> throw Swig::DirectorMethodException($error);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When this feature is activated, the call to the Ruby instance |
| 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"></a>31.4 Naming</H2> |
| |
| |
| <p>Ruby has several common naming conventions. Constants are |
| generally |
| in upper case, module and class names are in camel case and methods are |
| in lower case with underscores. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <ul> |
| |
| |
| |
| |
| |
| <li><strong>MATH::PI</strong> is a constant name</li> |
| |
| |
| |
| |
| |
| <li><strong>MyClass</strong> is a class name</li> |
| |
| |
| |
| |
| |
| <li><strong>my_method</strong> is a method name</li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Prior to version 1.3.28, SWIG did not support these Ruby |
| conventions. The only modifications it made to names was to capitalize |
| the first letter of constants (which includes module and class names).</p> |
| |
| |
| |
| |
| |
| <p>SWIG 1.3.28 introduces the new -autorename command line |
| parameter. |
| When this parameter is specified, SWIG will automatically change |
| constant, class and method names to conform with the standard Ruby |
| naming conventions. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -ruby -autorename example.i</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>To disable renaming use the -noautorename command line option.</p> |
| |
| |
| |
| |
| |
| <p>Since this change significantly changes the wrapper code |
| 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"></a>31.4.1 Defining Aliases</H3> |
| |
| |
| <p> 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 an alias for <em>Array#length</em>. If you would like |
| to provide an alias for one of your class' instance methods, one |
| approach is to use SWIG's <tt>%extend</tt> directive to |
| add a new method of the aliased name that calls the original function. |
| For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br><br>%extend MyArray {<br> // MyArray#size is an alias for MyArray#length<br> size_t size() const {<br> return $self->length();<br> }<br>}<br> </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> A better solution is to use the <tt>%alias</tt> |
| directive (unique to SWIG's Ruby module). The previous example could |
| then be rewritten as: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// MyArray#size is an alias for MyArray#length<br>%alias MyArray::length "size";<br><br>class MyArray {<br>public:<br> // Construct an empty array<br> MyArray();<br> <br> // Return the size of this array<br> size_t length() const;<br>};<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Multiple aliases can be associated with a method by providing |
| a comma-separated list of aliases to the <tt>%alias</tt> |
| directive, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%alias MyArray::length "amount,quantity,size";</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> From an end-user's standpoint, there's no functional |
| difference between these two approaches; i.e. they should get the same |
| result from calling either <em>MyArray#size</em> or <em>MyArray#length</em>. |
| However, when the <tt>%alias</tt> directive is used, SWIG |
| doesn't need to generate all of the wrapper code that's usually |
| associated with added methods like our <em>MyArray::size()</em> |
| example. </p> |
| |
| |
| |
| |
| |
| <p>Note that the <tt>%alias</tt> directive is |
| implemented 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_nn29"></a>31.4.2 Predicate Methods</H3> |
| |
| |
| <p> Ruby methods that return a boolean value and end in a |
| question mark |
| are known as predicate methods. Examples of predicate methods in |
| standard Ruby classes include <em>Array#empty?</em> (which |
| returns <tt>true</tt> for an array containing no elements) |
| and <em>Object#instance_of?</em> (which returns <tt>true</tt> |
| if the object is an instance of the specified class). For consistency |
| with Ruby conventions, methods that return boolean values should be |
| marked as predicate methods.</p> |
| |
| |
| |
| |
| |
| <p>One cumbersome solution to this problem is to rename the |
| method (using SWIG's <tt>%rename</tt> directive) and |
| provide a custom typemap that converts the function's actual return |
| type to Ruby's <tt>true</tt> or <tt>false</tt>. |
| For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%rename("is_it_safe?") is_it_safe();<br><br>%typemap(out) int is_it_safe <br> "$result = ($1 != 0) ? Qtrue : Qfalse;";<br><br>int is_it_safe();<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> A better solution is to use the <tt>%predicate</tt> |
| directive (unique to SWIG's Ruby module) to designate a method as a |
| predicate method. For the previous example, this would look like: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%predicate is_it_safe();<br><br>int is_it_safe();<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>This method would be invoked from Ruby code like this:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):001:0> <b>Example::is_it_safe?</b><br>true<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The <tt>%predicate</tt> directive is implemented |
| 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"></a>31.4.3 Bang Methods</H3> |
| |
| |
| <p> Ruby methods that modify an object in-place and end in an |
| exclamation mark are known as bang methods. An example of a bang method |
| is <em>Array#sort!</em> which changes the ordering of |
| items in an array. Contrast this with <em>Array#sort</em>, |
| which returns a copy of the array with the items sorted instead of |
| modifying the original array. For consistency with Ruby conventions, |
| methods that modify objects in place should be marked as bang methods.</p> |
| |
| |
| |
| |
| |
| <p>Bang methods can be marked using the <tt>%bang</tt> |
| directive which is unique to the Ruby module and was introduced in SWIG |
| 1.3.28. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%bang sort!(arr);<br><br>int sort(int arr[]); </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>This method would be invoked from Ruby code like this:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>irb(main):001:0> <b>Example::sort!(arr)</b></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The <tt>%bang</tt> directive is implemented |
| 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"></a>31.4.4 Getters and Setters</H3> |
| |
| |
| <p> Often times a C++ library will expose properties through |
| getter and setter methods. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Foo {<br> Foo() {}<br><br> int getValue() { return value_; }<br><br> void setValue(int value) { value_ = value; }<br><br>private:<br> int value_;<br>};</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>By default, SWIG will expose these methods to Ruby as <tt>get_value</tt> |
| and <tt>set_value.</tt> However, it more natural for these |
| methods to be exposed in Ruby as <tt>value</tt> and <tt>value=. |
| </tt> That allows the methods to be used like this:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>irb(main):001:0> <b>foo = Foo.new()</b><br>irb(main):002:0> <b>foo.value = 5</b><br>irb(main):003:0> <b>puts foo.value</b></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> This can be done by using the %rename directive:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%rename("value") Foo::getValue();<br>%rename("value=") Foo::setValue(int value);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> </p> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn32"></a>31.5 Input and output parameters</H2> |
| |
| |
| <p> A common problem in some C programs is handling parameters |
| passed as simple pointers. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void add(int x, int y, int *result) {<br> *result = x + y;<br>}<br>or<br>int sub(int *x, int *y) {<br> return *x-*y;<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The easiest way to handle these situations is to use the <tt>typemaps.i</tt> |
| file. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module Example<br>%include "typemaps.i"<br><br>void add(int, int, int *OUTPUT);<br>int sub(int *INPUT, int *INPUT);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In Ruby, this allows you to pass simple values. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>a = Example.add(3,4)<br>puts a<br>7<br>b = Example.sub(7,4)<br>puts b<br>3<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Notice how the <tt>INPUT</tt> parameters allow |
| integer values to be passed instead of pointers and how the <tt>OUTPUT</tt> |
| parameter creates a return result. </p> |
| |
| |
| |
| |
| |
| <p>If you don't want to use the names <tt>INPUT</tt> |
| or <tt>OUTPUT</tt>, use the <tt>%apply</tt> |
| directive. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module Example<br>%include "typemaps.i"<br><br>%apply int *OUTPUT { int *result };<br>%apply int *INPUT { int *x, int *y};<br><br>void add(int x, int y, int *result);<br>int sub(int *x, int *y);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> If a function mutates one of its parameters like this, </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void negate(int *x) {<br> *x = -(*x);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>you can use <tt>INOUT</tt> like this:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%include "typemaps.i"<br>...<br>void negate(int *INOUT);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In Ruby, a mutated parameter shows up as a return value. For |
| example:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>a = Example.negate(3)<br>print a<br>-3<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The most common use of these special typemap rules is to |
| handle functions that return more than one value. For example, |
| sometimes a function returns a result as well as a special error code: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>/* send message, return number of bytes sent, success code, and error_code */<br>int send_message(char *text, int *success, int *error_code);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To wrap such a function, simply use the <tt>OUTPUT</tt> |
| rule above. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br>%include "typemaps.i"<br>...<br>int send_message(char *, int *OUTPUT, int *OUTPUT);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When used in Ruby, the function will return an array of |
| multiple values. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>bytes, success, error_code = send_message("Hello World")<br>if not success<br> print "error #{error_code} : in send_message"<br>else<br> print "Sent", bytes<br>end<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Another way to access multiple return values is to use the <tt>%apply</tt> |
| rule. In the following example, the parameters rows and columns are |
| related to SWIG as <tt>OUTPUT</tt> values through the use |
| of <tt>%apply</tt> </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module Example<br>%include "typemaps.i"<br>%apply int *OUTPUT { int *rows, int *columns };<br>...<br>void get_dimensions(Matrix *m, int *rows, int*columns);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In Ruby:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>r, c = Example.get_dimensions(m)<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn33"></a>31.6 Exception handling </H2> |
| |
| |
| <H3><a name="Ruby_nn34"></a>31.6.1 Using the %exception directive </H3> |
| |
| |
| <p>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. The chapter on <a href="Customization.html#Customization">Customization |
| Features</a> contains more details, but suppose you have a C++ |
| class like the following : </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class DoubleArray {<br> private:<br> int n;<br> double *ptr;<br> public:<br> // Create a new array of fixed size<br> DoubleArray(int size) {<br> ptr = new double[size];<br> n = size;<br> }<br><br> // Destroy an array<br> ~DoubleArray() {<br> delete ptr;<br> } <br><br> // Return the length of the array<br> int length() {<br> return n;<br> }<br><br> // Get an array item and perform bounds checking.<br> double getitem(int i) {<br> if ((i >= 0) && (i < n))<br> return ptr[i];<br> else<br> throw RangeError();<br> }<br><br> // Set an array item and perform bounds checking.<br> void setitem(int i, double val) {<br> if ((i >= 0) && (i < n))<br> ptr[i] = val;<br> else {<br> throw RangeError();<br> }<br> }<br> };<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Since several methods in this class can throw an exception |
| for an out-of-bounds access, you might want to catch this in the Ruby |
| extension by writing the following in an interface file: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%exception {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error.");<br> }<br>}<br><br>class DoubleArray {<br> ...<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The exception handling code is inserted directly into |
| generated wrapper functions. When an exception handler is defined, |
| errors can be caught and used to gracefully raise a Ruby exception |
| instead of forcing the entire program to terminate with an uncaught |
| error. </p> |
| |
| |
| |
| |
| |
| <p>As shown, the exception handling code will be added to every |
| wrapper function. Because this is somewhat inefficient, you might |
| consider refining the exception handler to only apply to specific |
| methods like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%exception getitem {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error in getitem.");<br> }<br>}<br><br>%exception setitem {<br> try {<br> $action<br> }<br> catch (const RangeError&) {<br> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);<br> rb_raise(cpperror, "Range error in setitem.");<br> }<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In this case, the exception handler is only attached to |
| methods and functions named <tt>getitem</tt> and <tt>setitem</tt>. |
| </p> |
| |
| |
| |
| |
| |
| <p>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.</p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn34_2"></a>31.6.2 Handling Ruby Blocks </H3> |
| |
| |
| <p>One of the highlights of Ruby and most of its standard library |
| is |
| the use of blocks, which allow the easy creation of continuations and |
| other niceties. Blocks in ruby are also often used to |
| simplify the passing of many arguments to a class.</p> |
| |
| |
| |
| |
| |
| <p>In order to make your class constructor support blocks, you |
| can take advantage of the %exception directive, which will get run |
| after the C++ class' constructor was called. </p> |
| |
| |
| |
| |
| |
| <p>For example, this yields the class over after its |
| construction: |
| <br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Window<br>{<br>public:<br> Window(int x, int y, int w, int h);<br>// .... other methods here ....<br>};<br><br>// Add support for yielding self in the Class' constructor.<br>%exception Window::Window {<br> $action<br> if (rb_block_given_p()) {<br> rb_yield(self);<br> }<br>}</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Then, in ruby, it can be used like:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="targetlang">Window.new(0,0,360,480) |
| { |w|<br> |
| |
| |
| |
| |
| |
| w.color = Fltk::RED<br> |
| |
| |
| |
| |
| |
| w.border = false<br> |
| |
| |
| |
| |
| |
| <span class="targetlang">}</span></div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <p>For other methods, you can usually use a dummy parameter with |
| a special in typemap, like:</p> |
| |
| |
| |
| |
| |
| <div class="code" style="font-family: monospace;">//<br> |
| |
| |
| |
| |
| |
| // original function was:<br> |
| |
| |
| |
| |
| |
| //<br> |
| |
| |
| |
| |
| |
| // void func(int x);<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %typemap(in,numinputs=0) int RUBY_YIELD_SELF {<br> |
| |
| |
| |
| |
| |
| if ( !rb_block_given_p() )<br> |
| |
| |
| |
| |
| |
| |
| rb_raise("No block given");<br> |
| |
| |
| |
| |
| |
| return rb_yield(self);<br> |
| |
| |
| |
| |
| |
| }<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| %extend {<br> |
| |
| |
| |
| |
| |
| void func(int x, int |
| RUBY_YIELD_SELF );<br> |
| |
| |
| |
| |
| |
| }</div> |
| |
| |
| |
| |
| |
| <p>For more information on typemaps, see <a href="#Ruby_nn37">Typemaps</a>.</p> |
| |
| |
| <H3><a name="Ruby_nn35"></a>31.6.3 Raising exceptions </H3> |
| |
| |
| <p>There are three ways to raise exceptions from C++ code to |
| Ruby. </p> |
| |
| |
| |
| |
| |
| <p>The first way is to use <tt>SWIG_exception(int code, |
| const char *msg)</tt>. The following table shows the mappings |
| from SWIG error codes to Ruby exceptions:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table class="diagram" summary="Mapping between SWIG error codes and Ruby exceptions." border="1" width="80%"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_MemoryError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eNoMemError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_IOError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eIOError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_RuntimeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eRuntimeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_IndexError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eIndexError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_TypeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eTypeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_DivisionByZero</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eZeroDivError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_OverflowError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eRangeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_SyntaxError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eSyntaxError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_ValueError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eArgError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_SystemError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eFatal</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_AttributeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eRuntimeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_NullReferenceError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eNullReferenceError*</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_ObjectPreviouslyDeletedError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eObjectPreviouslyDeleted*</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>SWIG_UnknownError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> |
| |
| |
| |
| |
| <div>rb_eRuntimeError</div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr class="diagram" style="font-family: monospace;"> |
| |
| |
| |
| |
| |
| <td colspan="2"> |
| |
| |
| |
| |
| <div>* These error classes are created by |
| SWIG and are not built-in Ruby exception classes </div> |
| |
| |
| |
| |
| |
| </td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>The second way to raise errors is to use <tt>SWIG_Raise(obj, |
| type, desc)</tt>. |
| Obj is a C++ instance of an exception class, type is a string |
| specifying the type of exception (for example, "MyError") and desc is |
| the SWIG description of the exception class. For example: </p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="code"> |
| %raise(SWIG_NewPointerObj(e, |
| SWIGTYPE_p_AssertionFailedException, |
| 0), ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);</div> |
| |
| |
| |
| |
| |
| <p>This is useful when you want to pass the current exception |
| object |
| directly to Ruby, particularly when the object is an instance of class |
| marked as an <tt>%exceptionclass</tt> (see the next |
| section for more information).</p> |
| |
| |
| |
| |
| |
| <p>Last, you can raise an exception by directly calling Ruby's C |
| api. This is done by invoking the <tt>rb_raise()</tt> |
| 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"></a>31.6.4 Exception classes </H3> |
| |
| |
| <p>Starting with SWIG 1.3.28, the Ruby module supports the <tt>%exceptionclass</tt> |
| directive, which is used to identify C++ classes that are used as |
| exceptions. Classes that are marked with the <tt>%exceptionclass</tt> |
| directive are exposed in Ruby as child classes of <tt>rb_eRuntimeError</tt>. |
| This allows C++ exceptions to be directly mapped to Ruby exceptions, |
| providing for a more natural integration between C++ code and Ruby code.</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre> %exceptionclass CustomError;<br> <br> %inline %{<br> class CustomError { };<br> <br> class Foo { <br> public:<br> void test() { throw CustomError; }<br> };<br> }<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>From Ruby you can now call this method like this: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>foo = Foo.new<br>begin<br> foo.test()<br>rescue CustomError => e<br> puts "Caught custom error"<br>end </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>For another example look at swig/Examples/ruby/exception_class.<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn37"></a>31.7 Typemaps</H2> |
| |
| |
| <p> This section describes how you can modify SWIG's default |
| wrapping behavior for various C/C++ datatypes using the <tt>%typemap</tt> |
| directive. This is an advanced topic that assumes familiarity with the |
| Ruby C API as well as the material in the "<a href="Typemaps.html#Typemaps">Typemaps</a>" |
| chapter. |
| </p> |
| |
| |
| |
| |
| |
| <p>Before proceeding, it should be stressed that typemaps are not |
| 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"></a>31.7.1 What is a typemap?</H3> |
| |
| |
| <p> A typemap is nothing more than a code generation rule that is |
| attached to a specific C datatype. The general form of this declaration |
| is as follows ( parts enclosed in [...] are optional |
| ): </p> |
| |
| |
| |
| |
| |
| <div class="code"><span style="font-family: monospace;" class="code">%typemap( method [, modifiers...] ) typelist |
| code; </span></div> |
| |
| |
| |
| |
| |
| <p><em> method</em> is a simply a name that specifies |
| what kind of typemap is being defined. It is usually a name like <tt>"in"</tt>, |
| <tt>"out"</tt>, or <tt>"argout"</tt> (or its |
| director variations). The purpose of these methods is described later.</p> |
| |
| |
| |
| |
| |
| <p><em> modifiers</em> is an optional comma separated |
| list of <tt> |
| name="value"</tt> values. These are sometimes to attach extra |
| information to a typemap and is often target-language dependent.</p> |
| |
| |
| |
| |
| |
| <p><em> typelist</em> is a list of the C++ type |
| patterns that the typemap will match. The general form of this list is |
| as follows:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <pre>typelist : typepattern [, typepattern, typepattern, ... ] ;<br><br>typepattern : type [ (parms) ]<br> | type name [ (parms) ]<br> | ( typelist ) [ (parms) ]<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Each type pattern is either a simple type, a simple type and |
| argument name, or a list of types in the case of multi-argument |
| typemaps. In addition, each type pattern can be parameterized with a |
| list of temporary variables (parms). The purpose of these variables |
| will be explained shortly.</p> |
| |
| |
| |
| |
| |
| <p><em>code</em> specifies the C code used in the |
| typemap. It can take any one of the following forms:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <pre>code : { ... }<br> | " ... "<br> | %{ ... %}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>For example, to convert integers |
| from Ruby to C, you might define a typemap like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%typemap(in) int {<br> $1 = (int) NUM2INT($input);<br> printf("Received an integer : %d\n",$1);<br>}<br><br>%inline %{<br>extern int fact(int n);<br>%}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Typemaps are always associated with some specific aspect of |
| code generation. In this case, the "in" method refers to the conversion |
| of input arguments to C/C++. The datatype <tt>int</tt> is |
| the datatype to which the typemap will be applied. The supplied C code |
| is used to convert values. In this code a number of special variables |
| prefaced by a <tt>$</tt> are used. The <tt>$1</tt> |
| variable is placeholder for a local variable of type <tt>int</tt>. |
| The <tt>$input</tt> variable is the input Ruby object. </p> |
| |
| |
| |
| |
| |
| <p>When this example is compiled into a Ruby module, the |
| following sample code: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>require 'example'<br><br>puts Example.fact(6)<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>prints the result:</p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>Received an integer : 6<br>720<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In this example, the typemap is applied to all occurrences of |
| the <tt>int</tt> datatype. You can refine this by |
| supplying an optional parameter name. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%typemap(in) int n {<br> $1 = (int) NUM2INT($input);<br> printf("n = %d\n",$1);<br>}<br><br>%inline %{<br>extern int fact(int n);<br>%}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In this case, the typemap code is only attached to arguments |
| that exactly match "<tt>int n</tt>". </p> |
| |
| |
| |
| |
| |
| <p>The application of a typemap to specific datatypes and |
| argument names involves more than simple text-matching--typemaps are |
| fully integrated into the SWIG type-system. When you define a typemap |
| for <tt>int</tt>, that typemap applies to <tt>int</tt> |
| and qualified variations such as <tt>const int</tt>. In |
| addition, the typemap system follows <tt>typedef</tt> |
| declarations. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) int n {<br> $1 = (int) NUM2INT($input);<br> printf("n = %d\n",$1);<br>}<br><br>typedef int Integer;<br>extern int fact(Integer n); // Above typemap is applied<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> However, the matching of <tt>typedef</tt> only |
| occurs in one direction. If you defined a typemap for <tt>Integer</tt>, |
| it is not applied to arguments of type <tt>int</tt>. </p> |
| |
| |
| |
| |
| |
| <p>Typemaps can also be defined for groups of consecutive |
| arguments. For example: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (char *str, int len) {<br> $1 = STR2CSTR($input);<br> $2 = (int) RSTRING($input)->len;<br>};<br><br>int count(char c, char *str, int len);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When a multi-argument typemap is defined, the arguments are |
| always handled as a single Ruby object. This allows the function <tt>count</tt> |
| to be used as follows (notice how the length parameter is omitted): </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>puts Example.count('o','Hello World')<br>2<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_Typemap_scope"></a>31.7.2 Typemap scope</H3> |
| |
| |
| <p> Once defined, a typemap remains in effect for all of the |
| declarations that follow. A typemap may be redefined for different |
| sections of an input file. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// typemap1<br>%typemap(in) int {<br>...<br>}<br><br>int fact(int); // typemap1<br>int gcd(int x, int y); // typemap1<br><br>// typemap2<br>%typemap(in) int {<br>...<br>}<br><br>int isprime(int); // typemap2<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> One exception to the typemap scoping rules pertains to the <tt> |
| %extend</tt> declaration. <tt>%extend</tt> is used |
| to attach new declarations to a class or structure definition. Because |
| of this, all of the declarations in an <tt>%extend</tt> |
| block are subject to the typemap rules that are in effect at the point |
| where the class itself is defined. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>class Foo {<br> ...<br>};<br><br>%typemap(in) int {<br> ...<br>}<br><br>%extend Foo {<br> int blah(int x); // typemap has no effect. Declaration is attached to Foo which <br> // appears before the %typemap declaration.<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_Copying_a_typemap"></a>31.7.3 Copying a typemap</H3> |
| |
| |
| <p> A typemap is copied by using assignment. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) Integer = int;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> or this:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) Integer, Number, int32_t = int;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Types are often managed by a collection of different |
| typemaps. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) int { ... }<br>%typemap(out) int { ... }<br>%typemap(varin) int { ... }<br>%typemap(varout) int { ... }<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To copy all of these typemaps to a new type, use <tt>%apply</tt>. |
| For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%apply int { Integer }; // Copy all int typemaps to Integer<br>%apply int { Integer, Number }; // Copy all int typemaps to both Integer and Number<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The patterns for <tt>%apply</tt> follow the same |
| rules as for <tt> |
| %typemap</tt>. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%apply int *output { Integer *output }; // Typemap with name<br>%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_Deleting_a_typemap"></a>31.7.4 Deleting a typemap</H3> |
| |
| |
| <p> A typemap can be deleted by simply defining no code. For |
| example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) int; // Clears typemap for int<br>%typemap(in) int, long, short; // Clears typemap for int, long, short<br>%typemap(in) int *output; <br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The <tt>%clear</tt> directive clears all |
| typemaps for a given type. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%clear int; // Removes all types for int<br>%clear int *output, long *output;<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p><b> Note:</b> Since SWIG's default behavior is |
| 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"></a>31.7.5 Placement of typemaps</H3> |
| |
| |
| <p> Typemap declarations can be declared in the global scope, |
| within a C++ namespace, and within a C++ class. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) int {<br> ...<br>}<br><br>namespace std {<br> class string;<br> %typemap(in) string {<br> ...<br> }<br>}<br><br>class Bar {<br>public:<br> typedef const int & const_reference;<br> %typemap(out) const_reference {<br> ...<br> }<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When a typemap appears inside a namespace or class, it stays |
| in effect until the end of the SWIG input (just like before). However, |
| the typemap takes the local scope into account. Therefore, this code</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>namespace std {<br> class string;<br> %typemap(in) string {<br> ...<br> }<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> is really defining a typemap for the type <tt>std::string</tt>. |
| You could have code like this:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>namespace std {<br> class string;<br> %typemap(in) string { /* std::string */<br> ...<br> }<br>}<br><br>namespace Foo {<br> class string;<br> %typemap(in) string { /* Foo::string */<br> ...<br> }<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In this case, there are two completely distinct typemaps that |
| apply to two completely different types (<tt>std::string</tt> |
| and <tt> |
| Foo::string</tt>).</p> |
| |
| |
| |
| |
| |
| <p> It should be noted that for scoping to work, SWIG has to know |
| that <tt> |
| string</tt> is a typename defined within a particular namespace. |
| In this example, this is done using the class declaration <tt>class |
| string</tt> |
| .</p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn39"></a>31.7.6 Ruby typemaps</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"></a>31.7.6.1 "in" typemap</H4> |
| |
| |
| <p>Converts Ruby objects to input |
| function arguments. For example: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) int {<br> $1 = NUM2INT($input);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - in typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$input </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Input object |
| holding value to be converted.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of |
| function/method being wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1...n </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Argument being |
| sent to the function</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_name </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of the |
| argument (if provided)</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_type </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The actual C |
| datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_ltype </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The assignable |
| version of the C datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> This is probably the most commonly redefined typemap because |
| it can be used to implement customized conversions.</p> |
| |
| |
| |
| |
| |
| <p> In addition, the "in" typemap allows the number of converted |
| arguments to be specified. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// Ignored argument.<br>%typemap(in, numinputs=0) int *out (int temp) {<br> $1 = &temp;<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> At this time, only zero or one arguments may be converted.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_typecheck_typemap"></a>31.7.6.2 "typecheck" typemap</H4> |
| |
| |
| <p> The "typecheck" typemap is used to support overloaded |
| functions and methods. It merely checks an argument to see whether or |
| not it matches a specific type. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {<br> $1 = FIXNUM_P($input) ? 1 : 0;<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> For typechecking, the $1 variable is always a simple integer |
| that is set to 1 or 0 depending on whether or not the input argument is |
| the correct type.</p> |
| |
| |
| |
| |
| |
| <p> If you define new "in" typemaps<em> and</em> your |
| 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"></a>31.7.6.3 "out" typemap</H4> |
| |
| |
| <p>Converts return value of a C function |
| to a Ruby object.</p> |
| |
| |
| |
| |
| |
| <div class="code"><tt><br> |
| |
| |
| |
| |
| |
| %typemap(out) int {<br> |
| |
| |
| |
| |
| |
| $result = INT2NUM( $1 );<br> |
| |
| |
| |
| |
| |
| }<br> |
| |
| |
| |
| |
| |
| </tt></div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available.</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - out typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$result </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Result object |
| returned to target language.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of |
| function/method being wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1...n </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Argument being |
| wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_name </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of the |
| argument (if provided)</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_type </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The actual C |
| datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_ltype </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The assignable |
| version of the C datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_arginit_typemap"></a>31.7.6.4 "arginit" typemap</H4> |
| |
| |
| <p> The "arginit" typemap is used to set the initial value of a |
| function argument--before any conversion has occurred. This is not |
| normally necessary, but might be useful in highly specialized |
| applications. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// Set argument to NULL before any conversion occurs<br>%typemap(arginit) int *data {<br> $1 = NULL;<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_default_typemap"></a>31.7.6.5 "default" typemap</H4> |
| |
| |
| <p> The "default" typemap is used to turn an argument into a |
| default argument. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(default) int flags {<br> $1 = DEFAULT_FLAGS;<br>}<br>...<br>int foo(int x, int y, int flags);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The primary use of this typemap is to either change the |
| wrapping of default arguments or specify a default argument in a |
| language where they aren't supported (like C). Target languages that do |
| not support optional arguments, such as Java and C#, effectively ignore |
| the value specified by this typemap as all arguments must be given.</p> |
| |
| |
| |
| |
| |
| <p> Once a default typemap has been applied to an argument, all |
| arguments that follow must have default values. See the <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#SWIG_default_args"> |
| Default/optional arguments</a> section for further information on |
| default argument wrapping.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_check_typemap"></a>31.7.6.6 "check" typemap</H4> |
| |
| |
| <p> The "check" typemap is used to supply value checking code |
| during argument conversion. The typemap is applied<em> after</em> |
| arguments have been converted. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(check) int positive {<br> if ($1 <= 0) {<br> SWIG_exception(SWIG_ValueError,"Expected positive value.");<br> }<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_argout_typemap_"></a>31.7.6.7 "argout" typemap</H4> |
| |
| |
| <p> The "argout" typemap is used to return values from arguments. |
| This is most commonly used to write wrappers for C/C++ functions that |
| need to return multiple values. The "argout" typemap is almost always |
| combined with an "in" typemap---possibly to ignore the input value. For |
| example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>/* Set the input argument to point to a temporary variable */<br>%typemap(in, numinputs=0) int *out (int temp) {<br> $1 = &temp;<br>}<br><br>%typemap(argout, fragment="output_helper") int *out {<br> // Append output value $1 to $result (assuming a single integer in this case)<br> $result = output_helper( $result, INT2NUM(*$1) );<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available.</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - argout typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$result </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Result object |
| returned to target language.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$input </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The original |
| input object passed.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of |
| function/method being wrapped.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The code supplied to the "argout" typemap is always placed |
| after the "out" typemap. If multiple return values are used, the extra |
| return values are often appended to return value of the function.</p> |
| |
| |
| |
| |
| |
| <p>Output helper is a fragment that usually defines a macro to |
| some function like SWIG_Ruby_AppendOutput.</p> |
| |
| |
| |
| |
| |
| <p> See the <tt>typemaps.i</tt> library for examples.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_freearg_typemap_"></a>31.7.6.8 "freearg" typemap</H4> |
| |
| |
| <p> The "freearg" typemap is used to cleanup argument data. It is |
| only used when an argument might have allocated resources that need to |
| be cleaned up when the wrapper function exits. The "freearg" typemap |
| usually cleans up argument resources allocated by the "in" typemap. For |
| example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>// Get a list of integers<br>%typemap(in) int *items {<br> int nitems = Length($input); <br> $1 = (int *) malloc(sizeof(int)*nitems);<br>}<br>// Free the list <br>%typemap(freearg) int *items {<br> free($1);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> The "freearg" typemap inserted at the end of the wrapper |
| function, just before control is returned back to the target language. |
| 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"></a>31.7.6.9 "newfree" typemap</H4> |
| |
| |
| <p> The "newfree" typemap is used in conjunction with the <tt>%newobject</tt> |
| directive and is used to deallocate memory used by the return result of |
| a function. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(newfree) string * {<br> delete $1;<br>}<br>%typemap(out) string * {<br> $result = PyString_FromString($1->c_str());<br>}<br>...<br><br>%newobject foo;<br>...<br>string *foo();<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> See <a href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#ownership">Object |
| ownership and %newobject</a> for further details.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_memberin_typemap"></a>31.7.6.10 "memberin" typemap</H4> |
| |
| |
| <p> The "memberin" typemap is used to copy data from<em> an |
| already converted input value</em> into a structure member. It is |
| typically used to handle array members and other special cases. For |
| example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(memberin) int [4] {<br> memmove($1, $input, 4*sizeof(int));<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> It is rarely necessary to write "memberin" typemaps---SWIG |
| already provides a default implementation for arrays, strings, and |
| other objects.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_varin_typemap"></a>31.7.6.11 "varin" typemap</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_"></a>31.7.6.12 "varout" typemap</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"></a>31.7.6.13 "throws" typemap</H4> |
| |
| |
| <p> The "throws" typemap is only used when SWIG parses a C++ |
| method with an exception specification or has the <tt>%catches</tt> |
| feature attached to the method. It provides a default mechanism for |
| handling C++ methods that have declared the exceptions they will throw. |
| The purpose of this typemap is to convert a C++ exception into an error |
| or exception in the target language. It is slightly different to the |
| other typemaps as it is based around the exception type rather than the |
| type of a parameter or variable. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(throws) const char * %{<br> rb_raise(rb_eRuntimeError, $1);<br> SWIG_fail;<br>%}<br>void bar() throw (const char *);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> As can be seen from the generated code below, SWIG generates |
| an exception handler with the catch block comprising the "throws" |
| typemap content.</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>...<br>try {<br> bar();<br>}<br>catch(char const *_e) {<br> rb_raise(rb_eRuntimeError, _e);<br> SWIG_fail;<br>}<br>...<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note that if your methods do not have an exception |
| 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="http://www.swig.org/Doc1.3/SWIGDocumentation.html#exception">Exception |
| handling with %exception</a> section.</p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_directorin_typemap"></a>31.7.6.14 directorin typemap</H4> |
| |
| |
| <p>Converts C++ objects in director |
| member functions to ruby objects. It is roughly the opposite |
| of the "in" typemap, making its typemap rule often similar to the "out" |
| typemap. |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"><tt><br> |
| |
| |
| |
| |
| |
| %typemap(directorin) int {<br> |
| |
| |
| |
| |
| |
| $result = INT2NUM($1);<br> |
| |
| |
| |
| |
| |
| }<br> |
| |
| |
| |
| |
| |
| </tt></div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available.</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - directorin typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$result </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Result object |
| returned to target language.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of |
| function/method being wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1...n </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Argument being |
| wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_name </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of the |
| argument (if provided)</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_type </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The actual C |
| datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_ltype </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The assignable |
| version of the C datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">this </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> C++ this, |
| referring to the class itself.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_directorout_typemap"></a>31.7.6.15 directorout typemap</H4> |
| |
| |
| <p>Converts Ruby objects in director |
| member functions to C++ objects. It is roughly the opposite |
| of the "out" typemap, making its rule often similar to the "in" |
| typemap. |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"><tt style="font-family: monospace;"><br> |
| |
| |
| |
| |
| |
| %typemap(directorout) int {</tt><tt><br> |
| |
| |
| |
| |
| |
| $result = NUM2INT($1);</tt><br> |
| |
| |
| |
| |
| |
| <tt style="font-family: monospace;">}<br> |
| |
| |
| |
| |
| |
| </tt></div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Special variables - directorout typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of |
| function/method being wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1...n </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Argument being |
| sent to the function</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_name </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> Name of the |
| argument (if provided)</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_type </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The actual C |
| datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_ltype </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> The assignable |
| version of the C datatype matched by the typemap.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">this </td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;"> C++ this, |
| referring to the class itself.</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Currently, the directorout nor the out typemap support the |
| option <span style="font-family: monospace;">numoutputs</span>, |
| but the Ruby module provides that functionality through a %feature |
| directive. Thus, a function can be made to return "nothing" |
| if you do:</p> |
| |
| |
| |
| |
| |
| <div style="font-family: monospace;" class="code">%feature("numoutputs","0") |
| MyClass::function;</div> |
| |
| |
| |
| |
| |
| <p>This feature can be useful if a function returns a status |
| code, which you want to discard but still use the typemap to raise an |
| exception.<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_directorargout_typemap"></a>31.7.6.16 directorargout typemap</H4> |
| |
| |
| <p>Output argument processing in director |
| member functions.</p> |
| |
| |
| |
| |
| |
| <div class="code"><tt style="font-family: monospace;">%typemap(directorargout, |
| fragment="output_helper") int {</tt><tt><br> |
| |
| |
| |
| |
| |
| $result = output_helper( $result, NUM2INT($1) );</tt><br> |
| |
| |
| |
| |
| |
| <tt style="font-family: monospace;">}</tt></div> |
| |
| |
| |
| |
| |
| <p> The following special variables are available:</p> |
| |
| |
| |
| |
| |
| <div class="diagram"> |
| <table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2" summary="Special variables - directorargout typemap"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$result</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">Result that the |
| director function returns</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$symname</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">name of the |
| function/method being wrapped</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1...n</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">Argument being |
| sent to the function</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_name</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">Name of the |
| argument (if provided)</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_type</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">The actual C |
| datatype matched by the typemap</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">$1_ltype</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">The assignable |
| version of the C datatype matched by the typemap</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">this</td> |
| |
| |
| |
| |
| |
| <td style="font-family: monospace;">C++ this, |
| referring to the instance of the class itself</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_ret_typemap"></a>31.7.6.17 ret typemap</H4> |
| |
| |
| <p>Cleanup of function return values |
| </p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_globalin_typemap"></a>31.7.6.18 globalin typemap</H4> |
| |
| |
| <p>Setting of C global variables |
| </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn40"></a>31.7.7 Typemap variables</H3> |
| |
| |
| <p> |
| 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">Typemaps</a>" chapter. |
| This is a list of the most common variables: |
| </p> |
| |
| |
| |
| |
| |
| <p><tt>$1</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent">A C local variable corresponding to |
| the actual type specified in the <tt>%typemap</tt> |
| directive. For input values, this is a C local variable that is |
| supposed to hold an argument value. For output values, this is the raw |
| result that is supposed to be returned to Ruby. </div> |
| |
| |
| |
| |
| |
| <p><tt>$input</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">A <tt>VALUE</tt> holding |
| a raw Ruby object with an argument or variable value. </div> |
| |
| |
| |
| |
| |
| <p><tt>$result</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">A <tt>VALUE</tt> that |
| holds the result to be returned to Ruby. </div> |
| |
| |
| |
| |
| |
| <p><tt>$1_name</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">The parameter name that was matched. </div> |
| |
| |
| |
| |
| |
| <p><tt>$1_type</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">The actual C datatype matched by the |
| typemap. </div> |
| |
| |
| |
| |
| |
| <p><tt>$1_ltype</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">An assignable version of the datatype |
| matched by the typemap (a type that can appear on the left-hand-side of |
| a C assignment operation). This type is stripped of qualifiers and may |
| be an altered version of <tt>$1_type</tt>. All arguments |
| and local variables in wrapper functions are declared using this type |
| so that their values can be properly assigned. </div> |
| |
| |
| |
| |
| |
| <p><tt>$symname</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">The Ruby name of the wrapper function |
| being created. </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn41"></a>31.7.8 Useful Functions</H3> |
| |
| |
| <p> 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 many more can be found in <a href="http://www.rubycentral.com/book"><em>Programming |
| Ruby</em></a>, by David Thomas and Andrew Hunt.) </p> |
| <p>In addition, we list equivalent functions that Swig defines, which |
| provide a language neutral conversion (these functions are defined for |
| each swig language supported). If you are trying to create a swig |
| file that will work under multiple languages, it is recommended you |
| 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"></a>31.7.8.1 C Datatypes to Ruby Objects</H4> |
| |
| |
| <div class="diagram"> |
| <table style="width: 100%;" border="1" cellpadding="2" cellspacing="2" summary="Datatypes"> |
| |
| <tbody> |
| <tr> |
| <th style="font-weight: bold;">RUBY</th> |
| <th style="font-weight: bold;">Swig</th> |
| <td></td> |
| </tr> |
| <tr> |
| <td style="font-family: monospace;">INT2NUM(long or int) </td> |
| <td style="font-family: monospace;">SWIG_From_int(int x)</td> |
| <td> int to Fixnum or Bignum</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">INT2FIX(long or int) </td> |
| <td style="font-family: monospace;"></td> |
| <td> int to Fixnum (faster than INT2NUM)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">CHR2FIX(char) </td> |
| <td style="font-family: monospace;">SWIG_From_char(char x)</td> |
| <td> char to Fixnum</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">rb_str_new2(char*) </td> |
| <td style="font-family: monospace;">SWIG_FromCharPtrAndSize(char*, size_t)</td> |
| <td> char* to String</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">rb_float_new(double) </td> |
| <td style="font-family: monospace;">SWIG_From_double(double),<br> |
| SWIG_From_float(float)</td> |
| <td>float/double to Float</td> |
| </tr> |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn43"></a>31.7.8.2 Ruby Objects to C Datatypes</H4> |
| |
| |
| <p>Here, while the Ruby versions return the value directly, the SWIG |
| versions do not, but return a status value to indicate success (<span style="font-family: monospace;">SWIG_OK</span>). While more akward to use, this allows you to write typemaps that report more helpful error messages, like:</p> |
| <div style="font-family: monospace;" class="code"><br> |
| %typemap(in) size_t (int ok)<br> |
| <br> |
| ok = SWIG_AsVal_size_t($input, &$1);<br> |
| if (!SWIG_IsOK(ok)) {<br> |
| SWIG_exception_fail(SWIG_ArgError(ok), |
| Ruby_Format_TypeError( "$1_name", "$1_type","$symname", $argnum, $input |
| ));<br> |
| }<br> |
| <br> |
| } </div> |
| <div style="font-family: monospace;"> </div> |
| <div class="diagram"> |
| <table border="1" cellpadding="2" cellspacing="2" width="100%" summary="Ruby objects"> |
| |
| <tbody> |
| <tr> |
| <td style="font-family: monospace;">int NUM2INT(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_int(VALUE, int*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">int FIX2INT(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_int(VALUE, int*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">unsigned int NUM2UINT(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">unsigned int FIX2UINT(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">long NUM2LONG(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_long(VALUE, long*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">long FIX2LONG(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_long(VALUE, long*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">unsigned long FIX2ULONG(Numeric)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_unsigned_SS_long(VALUE, unsigned long*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">char NUM2CHR(Numeric or String)</td> |
| <td style="font-family: monospace;">SWIG_AsVal_char(VALUE, int*)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">char * STR2CSTR(String)</td> |
| <td style="font-family: monospace;">SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">char * rb_str2cstr(String, int*length)</td> |
| <td style="font-family: monospace;"></td> |
| </tr> |
| |
| <tr> |
| <td style="font-family: monospace;">double NUM2DBL(Numeric)</td> |
| <td style="font-family: monospace;">(double) SWIG_AsVal_int(VALUE) or similar</td> |
| </tr> |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn44"></a>31.7.8.3 Macros for VALUE</H4> |
| |
| |
| <p> <tt>RSTRING_LEN(str)</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent">length of the Ruby string</div> |
| |
| |
| |
| |
| |
| <p><tt>RSTRING_PTR(str)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">pointer to string storage</div> |
| |
| |
| |
| |
| |
| <p><tt>RARRAY_LEN(arr)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">length of the Ruby array</div> |
| |
| |
| |
| |
| |
| <p><tt>RARRAY(arr)->capa</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">capacity of the Ruby array</div> |
| |
| |
| |
| |
| |
| <p><tt>RARRAY_PTR(arr)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">pointer to array storage</div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn45"></a>31.7.8.4 Exceptions</H4> |
| |
| |
| <p> <tt>void rb_raise(VALUE exception, const char *fmt, |
| ...)</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent"> Raises an exception. The given format |
| string <i>fmt</i> and remaining arguments are interpreted |
| as with <tt>printf()</tt>. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_fatal(const char *fmt, ...)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Raises a fatal exception, terminating |
| the process. No rescue blocks are called, but ensure blocks will be |
| called. The given format string <i>fmt</i> and remaining |
| arguments are interpreted as with <tt>printf()</tt>. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_bug(const char *fmt, ...)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Terminates the process immediately -- |
| no handlers of any sort will be called. The given format string <i>fmt</i> |
| and remaining arguments are interpreted as with <tt>printf()</tt>. |
| You should call this function only if a fatal bug has been exposed. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_sys_fail(const char *msg)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Raises a platform-specific exception |
| corresponding to the last known system error, with the given string <i>msg</i>. |
| </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_rescue(VALUE (*body)(VALUE), VALUE args, |
| VALUE(*rescue)(VALUE, VALUE), VALUE rargs)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Executes <i>body</i> |
| with the given <i>args</i>. If a <tt>StandardError</tt> |
| exception is raised, then execute <i>rescue</i> with the |
| given <i>rargs</i>. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_ensure(VALUE(*body)(VALUE), VALUE args, |
| VALUE(*ensure)(VALUE), VALUE eargs)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Executes <i>body</i> |
| with the given <i>args</i>. Whether or not an exception is |
| raised, execute <i>ensure</i> with the given <i>rargs</i> |
| after <i>body</i> has completed. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_protect(VALUE (*body)(VALUE), VALUE args, |
| int *result)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Executes <i>body</i> |
| with the given <i>args</i> and returns nonzero in result |
| if any exception was raised. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_notimplement()</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Raises a <tt>NotImpError</tt> |
| exception to indicate that the enclosed function is not implemented |
| yet, or not available on this platform. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_exit(int status)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Exits Ruby with the given <i>status</i>. |
| Raises a <tt>SystemExit</tt> exception and calls |
| registered exit functions and finalizers. </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_warn(const char *fmt, ...)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Unconditionally issues a warning |
| message to standard error. The given format string <i>fmt</i> |
| and remaining arguments are interpreted as with <tt>printf()</tt>. |
| </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_warning(const char *fmt, ...)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Conditionally issues a warning |
| 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"></a>31.7.8.5 Iterators</H4> |
| |
| |
| <p> <tt>void rb_iter_break()</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent"> Breaks out of the enclosing iterator |
| block. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_each(VALUE obj)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Invokes the <tt>each</tt> |
| method of the given <i>obj</i>. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_yield(VALUE arg)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Transfers execution to the iterator |
| block in the current context, passing <i>arg</i> as an |
| argument. Multiple values may be passed in an array. </div> |
| |
| |
| |
| |
| |
| <p><tt>int rb_block_given_p()</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Returns <tt>true</tt> if |
| <tt>yield</tt> would execute a block in the current |
| context; that is, if a code block was passed to the current method and |
| is available to be called. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_iterate(VALUE (*method)(VALUE), VALUE args, |
| VALUE (*block)(VALUE, VALUE), VALUE arg2)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Invokes <i>method</i> |
| with argument <i>args</i> and block <i>block</i>. |
| A <tt>yield</tt> from that method will invoke <i>block</i> |
| with the argument given to <tt>yield</tt>, and a second |
| argument <i>arg2</i>. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE rb_catch(const char *tag, VALUE (*proc)(VALUE, |
| VALUE), VALUE value)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Equivalent to Ruby's <tt>catch</tt>. |
| </div> |
| |
| |
| |
| |
| |
| <p><tt>void rb_throw(const char *tag, VALUE value)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent"> Equivalent to Ruby's <tt>throw</tt>. |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn47"></a>31.7.9 Typemap Examples</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"></a>31.7.10 Converting a Ruby array to a char **</H3> |
| |
| |
| <p> 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 strings. The following SWIG interface file allows a Ruby |
| Array instance to be used as a <tt>char **</tt> object. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module argv<br><br>// This tells SWIG to treat char ** as a special case<br>%typemap(in) char ** {<br> /* Get the length of the array */<br> int size = RARRAY($input)->len; <br> int i;<br> $1 = (char **) malloc((size+1)*sizeof(char *));<br> /* Get the first element in memory */<br> VALUE *ptr = RARRAY($input)->ptr; <br> for (i=0; i < size; i++, ptr++)<br> /* Convert Ruby Object String to char* */<br> $1[i]= STR2CSTR(*ptr); <br> $1[i]=NULL; /* End of list */<br>}<br><br>// This cleans up the char ** array created before <br>// the function call<br><br>%typemap(freearg) char ** {<br> free((char *) $1);<br>}<br><br>// Now a test function<br>%inline %{<br>int print_args(char **argv) {<br> int i = 0;<br> while (argv[i]) {<br> printf("argv[%d] = %s\n", i,argv[i]);<br> i++;<br> }<br> return i;<br>}<br>%}<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> When this module is compiled, the wrapped C function now |
| operates as follows : </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>require 'Argv'<br>Argv.print_args(["Dave","Mike","Mary","Jane","John"])<br>argv[0] = Dave<br>argv[1] = Mike<br>argv[2] = Mary<br>argv[3] = Jane<br>argv[4] = John<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In the example, two different typemaps are used. The "in" |
| typemap is used to receive an input argument and convert it to a C |
| array. Since dynamic memory allocation is used to allocate memory for |
| the array, the "freearg" typemap is used to later release this memory |
| after the execution of the C function. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn49"></a>31.7.11 Collecting arguments in a hash</H3> |
| |
| |
| <p> 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 arguments to a function. All of those key-value |
| pairs are collected in a single <tt>Hash</tt> argument |
| that's presented to the function. If it makes sense, you might want to |
| provide similar functionality for your Ruby interface. For example, |
| suppose you'd like to wrap this C function that collects information |
| about people's vital statistics: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>void setVitalStats(const char *person, int nattributes, const char **names, int *values);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> and you'd like to be able to call it from Ruby by passing in |
| an arbitrary number of key-value pairs as inputs, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>setVitalStats("Fred",<br> 'weight' => 270,<br> 'age' => 42<br> )<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To make this work, you need to write a typemap that expects a |
| Ruby <tt>Hash</tt> as its input and somehow extracts the |
| last three arguments (<i>nattributes</i>, <i>names</i> |
| and <i>values</i>) needed by your C function. Let's start |
| with the basics: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br>}<br> </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> This <tt>%typemap</tt> directive tells SWIG that |
| we want to match any function declaration that has the specified types |
| and names of arguments somewhere in the argument list. The fact that we |
| specified the argument names (<i>nattributes</i>, <i>names</i> |
| and <i>values</i>) in our typemap is significant; this |
| ensures that SWIG won't try to apply this typemap to <i>other</i> |
| functions it sees that happen to have a similar declaration with |
| different argument names. The arguments that appear in the second set |
| of parentheses (<i>keys_arr</i>, <i>i</i>, <i>key</i> |
| and <i>val</i>) define local variables that our typemap |
| will need. </p> |
| |
| |
| |
| |
| |
| <p>Since we expect the input argument to be a <tt>Hash</tt>, |
| let's next add a check for that: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> <b>Check_Type($input, T_HASH);</b><br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> <tt>Check_Type()</tt> is just a macro (defined |
| in the Ruby header files) that confirms that the input argument is of |
| the correct type; if it isn't, an exception will be raised. </p> |
| |
| |
| |
| |
| |
| <p>The next task is to determine how many key-value pairs are |
| present in the hash; we'll assign this number to the first typemap |
| argument (<tt>$1</tt>). This is a little tricky since the |
| Ruby/C API doesn't provide a public function for querying the size of a |
| hash, but we can get around that by calling the hash's <i>size</i> |
| method directly and converting its result to a C <tt>int</tt> |
| value: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> <b>$1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));</b><br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> So now we know the number of attributes. Next we need to |
| initialize the second and third typemap arguments (i.e. the two C |
| arrays) to <tt>NULL</tt> and set the stage for extracting |
| the keys and values from the hash: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> <b>$2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> }</b><br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> There are a number of ways we could extract the keys and |
| values from the input hash, but the simplest approach is to first call |
| the hash's <i>keys</i> method (which returns a Ruby array |
| of the keys) and then start looping over the elements in that array: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> <b>keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> }</b><br>}<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Recall that <i>keys_arr</i> and <i>i</i> |
| are local variables for this typemap. For each element in the <i>keys_arr</i> |
| array, we want to get the key itself, as well as the value |
| corresponding to that key in the hash: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> <b>key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);</b><br>}<br>}<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To be safe, we should again use the <tt>Check_Type()</tt> |
| macro to confirm that the key is a <tt>String</tt> and the |
| value is a <tt>Fixnum</tt>: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> <b>Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);</b><br>}<br>}<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Finally, we can convert these Ruby objects into their C |
| equivalents and store them in our local C arrays: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(in) (int nattributes, const char **names, const int *values)<br> (VALUE keys_arr, int i, VALUE key, VALUE val) {<br> Check_Type($input, T_HASH);<br> $1 = NUM2INT(rb_funcall($input, rb_intern("size"), 0, NULL));<br> $2 = NULL;<br> $3 = NULL;<br> if ($1 > 0) {<br> $2 = (char **) malloc($1*sizeof(char *));<br> $3 = (int *) malloc($1*sizeof(int));<br> keys_arr = rb_funcall($input, rb_intern("keys"), 0, NULL);<br> for (i = 0; i < $1; i++) {<br> key = rb_ary_entry(keys_arr, i);<br> val = rb_hash_aref($input, key);<br> Check_Type(key, T_STRING);<br> Check_Type(val, T_FIXNUM);<br> <b>$2[i] = STR2CSTR(key);<br> $3[i] = NUM2INT(val);</b><br>}<br>}<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> We're not done yet. Since we used <tt>malloc()</tt> |
| to dynamically allocate the memory used for the <i>names</i> |
| and <i>values</i> arguments, we need to provide a |
| corresponding "freearg" typemap to free that memory so that there is no |
| memory leak. Fortunately, this typemap is a lot easier to write: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%typemap(freearg) (int nattributes, const char **names, const int *values) {<br> free((void *) $2);<br> free((void *) $3);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> All of the code for this example, as well as a sample Ruby |
| program that uses the extension, can be found in the <tt>Examples/ruby/hashargs</tt> |
| directory of the SWIG distribution. </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn50"></a>31.7.12 Pointer handling</H3> |
| |
| |
| <p> Occasionally, it might be necessary to convert pointer values |
| that have been stored using the SWIG typed-pointer representation. |
| Since there are several ways in which pointers can be represented, the |
| following two functions are used to safely perform this conversion: </p> |
| |
| |
| |
| |
| |
| <p><tt>int SWIG_ConvertPtr(VALUE obj, void **ptr, |
| swig_type_info *ty, int flags)</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent">Converts a Ruby object <i>obj</i> |
| to a C pointer whose address is <i>ptr</i> (i.e. <i>ptr</i> |
| is a pointer to a pointer). The third argument, <i>ty</i>, |
| is a pointer to a SWIG type descriptor structure. If <i>ty</i> |
| is not <tt>NULL</tt>, that type information is used to |
| validate type compatibility and other aspects of the type conversion. |
| If <i>flags</i> is non-zero, any type errors encountered |
| during this validation result in a Ruby <tt>TypeError</tt> |
| exception being raised; if <i>flags</i> is zero, such type |
| errors will cause <tt>SWIG_ConvertPtr()</tt> to return -1 |
| but not raise an exception. If <i>ty</i> is <tt>NULL</tt>, |
| no type-checking is performed. </div> |
| |
| |
| |
| |
| |
| <p> <tt>VALUE SWIG_NewPointerObj(void *ptr, swig_type_info |
| *ty, int own)</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent">Creates a new Ruby pointer object. |
| Here, <i>ptr</i> is the pointer to convert, <i>ty</i> |
| is the SWIG type descriptor structure that describes the type, and <i>own</i> |
| is a flag that indicates whether or not Ruby should take ownership of |
| the pointer (i.e. whether Ruby should free this data when the |
| corresponding Ruby instance is garbage-collected). </div> |
| |
| |
| |
| |
| |
| <p> Both of these functions require the use of a special SWIG |
| type-descriptor structure. This structure contains information about |
| the mangled name of the datatype, type-equivalence information, as well |
| as information about converting pointer values under C++ inheritance. |
| For a type of <tt>Foo *</tt>, the type descriptor |
| structure is usually accessed as follows: </p> |
| |
| |
| |
| |
| |
| <div class="indent code"> |
| <pre>Foo *foo;<br>SWIG_ConvertPtr($input, (void **) &foo, SWIGTYPE_p_Foo, 1);<br><br>VALUE obj;<br>obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> In a typemap, the type descriptor should always be accessed |
| using the special typemap variable <tt>$1_descriptor</tt>. |
| For example: </p> |
| |
| |
| |
| |
| |
| <div class="indent code"> |
| <pre>%typemap(in) Foo * {<br> SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);<br>}<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn51"></a>31.7.12.1 Ruby Datatype Wrapping</H4> |
| |
| |
| <p> <tt>VALUE Data_Wrap_Struct(VALUE class, void |
| (*mark)(void *), void (*free)(void *), void *ptr)</tt> </p> |
| |
| |
| |
| |
| |
| <div class="indent">Given a pointer <i>ptr</i> |
| to some C data, and the two garbage collection routines for this data (<i>mark</i> |
| and <i>free</i>), return a <tt>VALUE</tt> for |
| the Ruby object. </div> |
| |
| |
| |
| |
| |
| <p><tt>VALUE Data_Make_Struct(VALUE class, <i>c-type</i>, |
| void (*mark)(void *), void (*free)(void *), <i>c-type</i> |
| *ptr)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">Allocates a new instance of a C data |
| type <i>c-type</i>, assigns it to the pointer <i>ptr</i>, |
| then wraps that pointer with <tt>Data_Wrap_Struct()</tt> |
| as above. </div> |
| |
| |
| |
| |
| |
| <p><tt>Data_Get_Struct(VALUE obj, <i>c-type</i>, |
| <i>c-type</i> *ptr)</tt></p> |
| |
| |
| |
| |
| |
| <div class="indent">Retrieves the original C pointer of |
| 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"></a>31.7.13 Example: STL Vector to Ruby Array</H3> |
| |
| |
| <p>Another use for macros and type maps is to create a Ruby array |
| from a STL vector of pointers. In essence, copy of all the pointers in |
| the vector into a Ruby array. The use of the macro is to make the |
| typemap so generic that any vector with pointers can use the type map. |
| The following is an example of how to construct this type of |
| macro/typemap and should give insight into constructing similar |
| typemaps for other STL structures: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%define PTR_VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)<br>%typemap(out) vectorclassname &, const vectorclassname & {<br> VALUE arr = rb_ary_new2($1->size());<br> vectorclassname::iterator i = $1->begin(), iend = $1->end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%typemap(out) vectorclassname, const vectorclassname {<br> VALUE arr = rb_ary_new2($1.size());<br> vectorclassname::iterator i = $1.begin(), iend = $1.end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, *i));<br> $result = arr;<br>}<br>%enddef<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note, that the "<tt>c ## classname.klass"</tt> is |
| used in the preprocessor step to determine the actual object from the |
| class name. </p> |
| |
| |
| |
| |
| |
| <p>To use the macro with a class Foo, the following is used: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>PTR_VECTOR_TO_RUBY_ARRAY(vector<foo *="">, Foo)<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> It is also possible to create a STL vector of Ruby objects: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%define RUBY_ARRAY_TO_PTR_VECTOR(vectorclassname, classname)<br>%typemap(in) vectorclassname &, const vectorclassname & {<br> Check_Type($input, T_ARRAY);<br> vectorclassname *vec = new vectorclassname;<br> int len = RARRAY($input)->len;<br> for (int i=0; i!=len; i++) {<br> VALUE inst = rb_ary_entry($input, i);<br> //The following _should_ work but doesn't on HPUX<br> // Check_Type(inst, T_DATA);<br> classname *element = NULL;<br> Data_Get_Struct(inst, classname, element);<br> vec->push_back(element);<br> }<br> $1 = vec;<br>}<br><br>%typemap(freearg) vectorclassname &, const vectorclassname & {<br> delete $1;<br>}<br>%enddef<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> It is also possible to create a Ruby array from a vector of |
| static data types: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%define VECTOR_TO_RUBY_ARRAY(vectorclassname, classname)<br>%typemap(out) vectorclassname &, const vectorclassname & {<br> VALUE arr = rb_ary_new2($1->size()); <br> vectorclassname::iterator i = $1->begin(), iend = $1->end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));<br> $result = arr;<br>}<br>%typemap(out) vectorclassname, const vectorclassname {<br> VALUE arr = rb_ary_new2($1.size()); <br> vectorclassname::iterator i = $1.begin(), iend = $1.end();<br> for ( ; i!=iend; i++ )<br> rb_ary_push(arr, Data_Wrap_Struct(c ## classname.klass, 0, 0, &(*i)));<br> $result = arr;<br>}<br>%enddef<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| Note that this is mostly an example of typemaps. If you want to use the |
| 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>.<br> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn65"></a>31.8 Docstring Features</H2> |
| |
| |
| <p> |
| Using ri and rdoc web pages in Ruby libraries is a common practice. |
| Given the way that SWIG generates the extensions by default, your users |
| will normally not get |
| any documentation for it, even if they run 'rdoc' on the resulting .c |
| or .cxx file.</p> |
| |
| |
| |
| |
| |
| <p>The features described in this section make it easy for you to |
| add |
| rdoc strings to your modules, functions and methods that can then be |
| read by Ruby's rdoc tool to generate html web pages, ri documentation, |
| Windows chm file and an .xml description.</p> |
| |
| |
| |
| |
| |
| <p>rdoc can then be run from a console or shell window on a swig |
| generated file. </p> |
| |
| |
| |
| |
| |
| <p>For example, to generate html web pages from a C++ file, you'd |
| do: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"><span style="font-family: monospace; font-weight: bold;"> |
| $ |
| rdoc -E cxx=c -f html file_wrap.cxx</span></div> |
| |
| |
| |
| |
| |
| <p>To |
| generate ri documentation from a c wrap file, you could do:</p> |
| |
| |
| |
| |
| |
| <div class="code shell"><span style="font-family: monospace; font-weight: bold;">$ rdoc |
| -r file_wrap.c</span> |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn66"></a>31.8.1 Module docstring</H3> |
| |
| |
| <p> |
| Ruby allows a docstring at the beginning of the file |
| before any other statements, and it is typically used to give a |
| general description of the entire module. SWIG supports this by |
| setting an option of the <tt>%module</tt> directive. For |
| example: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module(docstring="This is the example module's docstring") example<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> |
| When you have more than just a line or so then you can retain the easy |
| readability of the <tt>%module</tt> directive by using a |
| macro. For example: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%define DOCSTRING<br>"The `XmlResource` class allows program resources defining menus, <br>layout of controls on a panel, etc. to be loaded from an XML file."<br>%enddef<br><br>%module(docstring=DOCSTRING) xrc<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn67"></a>31.8.2 %feature("autodoc")</H3> |
| |
| |
| <p>Since SWIG does know everything about the function it wraps, |
| it is possible to generate an rdoc containing the parameter types, |
| names |
| and default values. Since Ruby ships with one of the best documentation |
| systems of any language, it makes sense to take advantage of it. |
| </p> |
| |
| |
| |
| |
| |
| <p>SWIG's Ruby module provides support for the "autodoc" |
| feature, |
| which when attached to a node in the parse tree will cause an rdoc |
| comment |
| to be generated in the wrapper file that includes the name of the |
| function, parameter |
| names, default values if any, and return type if any. There are also |
| several options for autodoc controlled by the value given to the |
| feature, described below. |
| </p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn68"></a>31.8.2.1 %feature("autodoc", "0")</H4> |
| |
| |
| <p> |
| When the "0" option is given then the types of the parameters will |
| <em>not</em> be included in the autodoc string. For |
| example, given |
| this function prototype: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%feature("autodoc", "0");<br>bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> |
| Then Ruby code like this will be generated: |
| </p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>function_name(x, y, foo=nil, bar=nil) -> bool<br> ...<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_autodoc1"></a>31.8.2.2 %feature("autodoc", "1")</H4> |
| |
| |
| <p> |
| When the "1" option is used then the parameter types <em>will</em> |
| be used in the rdoc string. In addition, an attempt is made to |
| simplify the type name such that it makes more sense to the Ruby |
| user. Pointer, reference and const info is removed, |
| <tt>%rename</tt>'s are evaluated, etc. (This is not always |
| successful, but works most of the time. See the next section for what |
| to do when it doesn't.) Given the example above, then turning on the |
| parameter types with the "1" option will result in rdoc code like |
| this: |
| </p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool<br> ...<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_autodoc2"></a>31.8.2.3 %feature("autodoc", "2")</H4> |
| |
| |
| <p> |
| When the "2" option is used then the parameter types will not |
| be |
| used in the rdoc string. However, they will be listed in full after the |
| function. Given the example above, then turning on the |
| parameter types with the "2" option will result in Ruby code like |
| this: |
| </p> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_feature_autodoc3"></a>31.8.2.4 %feature("autodoc", "3")</H4> |
| |
| |
| <p> |
| When the "3" option is used then the function will be documented using |
| a combination of "1" and "2" above. Given the example above, |
| then turning on the |
| parameter types with the "2" option will result in Ruby code like |
| this: |
| </p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool<br><br>Parameters:<br> x - int<br> y - int<br> foo - Foo<br> bar - Bar<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H4><a name="Ruby_nn70"></a>31.8.2.5 %feature("autodoc", "docstring")</H4> |
| |
| |
| <p> |
| Finally, there are times when the automatically generated autodoc |
| string will make no sense for a Ruby programmer, particularly when a |
| typemap is involved. So if you give an explicit value for the autodoc |
| feature then that string will be used in place of the automatically |
| generated string. For example: |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;<br>void GetPosition(int* OUTPUT, int* OUTPUT);<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn71"></a>31.8.3 %feature("docstring")</H3> |
| |
| |
| <p> |
| In addition to the autodoc strings described above, you can also |
| attach any arbitrary descriptive text to a node in the parse tree with |
| the "docstring" feature. When the proxy module is generated then any |
| 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"></a>31.9 Advanced Topics</H2> |
| |
| |
| <H3><a name="Ruby_nn54"></a>31.9.1 Operator overloading</H3> |
| |
| |
| <p> SWIG allows operator overloading with, by using the <tt>%extend</tt> |
| or <tt>%rename</tt> commands in SWIG and the following |
| operator names (derived from Python): </p> |
| |
| |
| |
| |
| |
| <div class="code diagram"> |
| <table style="width: 100%; font-family: monospace;" border="1" cellpadding="2" cellspacing="2" summary="operator names"> |
| |
| |
| |
| |
| |
| <tbody> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td><b> General</b></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__repr__ </td> |
| |
| |
| |
| |
| |
| <td> inspect</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__str__ </td> |
| |
| |
| |
| |
| |
| <td> to_s</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__cmp__ </td> |
| |
| |
| |
| |
| |
| <td> <=></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__hash__ </td> |
| |
| |
| |
| |
| |
| <td> hash</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__nonzero__ </td> |
| |
| |
| |
| |
| |
| <td> nonzero?</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td><b> Callable</b></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__call__ </td> |
| |
| |
| |
| |
| |
| <td> call</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td><b> Collection</b></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__len__ </td> |
| |
| |
| |
| |
| |
| <td> length</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__getitem__ </td> |
| |
| |
| |
| |
| |
| <td> []</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__setitem__ </td> |
| |
| |
| |
| |
| |
| <td> []=</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td><b> Numeric</b></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__add__ </td> |
| |
| |
| |
| |
| |
| <td> +</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__sub__ </td> |
| |
| |
| |
| |
| |
| <td> -</td> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__mul__ </td> |
| |
| |
| |
| |
| |
| <td> *</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__div__ </td> |
| |
| |
| |
| |
| |
| <td> /</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__mod__ </td> |
| |
| |
| |
| |
| |
| <td> %</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__divmod__ </td> |
| |
| |
| |
| |
| |
| <td> divmod</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__pow__ </td> |
| |
| |
| |
| |
| |
| <td> **</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__lshift__ </td> |
| |
| |
| |
| |
| |
| <td> <<</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__rshift__ </td> |
| |
| |
| |
| |
| |
| <td> >></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__and__ </td> |
| |
| |
| |
| |
| |
| <td> &</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__xor__ </td> |
| |
| |
| |
| |
| |
| <td> ^</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__or__ </td> |
| |
| |
| |
| |
| |
| <td> |</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__neg__ </td> |
| |
| |
| |
| |
| |
| <td> -@</td> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__pos__ </td> |
| |
| |
| |
| |
| |
| <td> +@</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__abs__ </td> |
| |
| |
| |
| |
| |
| <td> abs</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__invert__ </td> |
| |
| |
| |
| |
| |
| <td> ~</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__int__ </td> |
| |
| |
| |
| |
| |
| <td> to_i</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__float__ </td> |
| |
| |
| |
| |
| |
| <td> to_f</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__coerce__ </td> |
| |
| |
| |
| |
| |
| <td> coerce</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td><b>Additions in 1.3.13 </b></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__lt__ </td> |
| |
| |
| |
| |
| |
| <td> <</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__le__ </td> |
| |
| |
| |
| |
| |
| <td> <=</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__eq__ </td> |
| |
| |
| |
| |
| |
| <td> ==</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__gt__ </td> |
| |
| |
| |
| |
| |
| <td> ></td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| <tr> |
| |
| |
| |
| |
| |
| <td>__ge__ </td> |
| |
| |
| |
| |
| |
| <td> >=</td> |
| |
| |
| |
| |
| |
| </tr> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </tbody> |
| </table> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> 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>. |
| </p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn55"></a>31.9.2 Creating Multi-Module Packages</H3> |
| |
| |
| <p> The chapter on <a href="Modules.html">Working |
| with Modules</a> discusses the basics of creating multi-module |
| extensions with SWIG, and in particular the considerations for sharing |
| runtime type information among the different modules. </p> |
| |
| |
| |
| |
| |
| <p>As an example, consider one module's interface file (<tt>shape.i</tt>) |
| that defines our base class: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module shape<br><br>%{<br>#include "Shape.h"<br>%}<br><br>class Shape {<br>protected:<br> double xpos;<br> double ypos;<br>protected:<br> Shape(double x, double y);<br>public:<br> double getX() const;<br> double getY() const;<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> We also have a separate interface file (<tt>circle.i</tt>) |
| that defines a derived class: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module circle<br><br>%{<br>#include "Shape.h"<br>#include "Circle.h"<br>%}<br><br>// Import the base class definition from Shape module<br>%import shape.i<br><br>class Circle : public Shape {<br>protected:<br> double radius;<br>public:<br> Circle(double x, double y, double r);<br> double getRadius() const;<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> We'll start by building the <b>Shape</b> |
| extension module: </p> |
| |
| |
| |
| |
| |
| <div class="code shell"> |
| <pre>$ <b>swig -c++ -ruby shape.i</b> |
| </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> SWIG generates a wrapper file named <tt>shape_wrap.cxx</tt>. |
| To compile this into a dynamically loadable extension for Ruby, prepare |
| an <tt>extconf.rb</tt> script using this template: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>require 'mkmf'<br><br># Since the SWIG runtime support library for Ruby<br># depends on the Ruby library, make sure it's in the list<br># of libraries.<br>$libs = append_library($libs, Config::CONFIG['RUBY_INSTALL_NAME'])<br><br># Create the makefile<br>create_makefile('shape')<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Run this script to create a <tt>Makefile</tt> |
| and then type <tt>make</tt> to build the shared library: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>ruby extconf.rb</b><br>creating Makefile<br>$ <b>make</b><br>g++ -fPIC -g -O2 -I. -I/usr/local/lib/ruby/1.7/i686-linux \<br>-I. -c shape_wrap.cxx<br>gcc -shared -L/usr/local/lib -o shape.so shape_wrap.o -L. \<br>-lruby -lruby -lc<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note that depending on your installation, the outputs may be |
| slightly different; these outputs are those for a Linux-based |
| development environment. The end result should be a shared library |
| (here, <tt>shape.so</tt>) containing the extension module |
| code. Now repeat this process in a separate directory for the <b>Circle</b> |
| module: </p> |
| |
| |
| |
| |
| |
| <ol> |
| |
| |
| |
| |
| |
| <li> Run SWIG to generate the wrapper code (<tt>circle_wrap.cxx</tt>); |
| </li> |
| |
| |
| |
| |
| |
| <li> Write an <tt>extconf.rb</tt> script that your |
| end-users can use to create a platform-specific <tt>Makefile</tt> |
| for the extension; </li> |
| |
| |
| |
| |
| |
| <li> Build the shared library for this extension by typing <tt>make</tt>. |
| </li> |
| |
| |
| |
| |
| |
| </ol> |
| |
| |
| |
| |
| |
| <p> Once you've built both of these extension modules, you can |
| test them interactively in IRB to confirm that the <tt>Shape</tt> |
| and <tt>Circle</tt> modules are properly loaded and |
| initialized: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <b>require 'shape'</b><br>true<br>irb(main):002:0> <b>require 'circle'</b><br>true<br>irb(main):003:0> <b>c = Circle::Circle.new(5, 5, 20)</b><br>#<Circle::Circle:0xa097208><br>irb(main):004:0> <b>c.kind_of? Shape::Shape</b><br>true<br>irb(main):005:0> <b>c.getX()</b><br>5.0<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn56"></a>31.9.3 Specifying Mixin Modules</H3> |
| |
| |
| <p> 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> |
| method. For example, if you have a Ruby class that defines an <em>each</em> |
| instance method, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>class Set<br> def initialize<br> @members = []<br> end<br> <br> def each<br> @members.each { |m| yield m }<br> end<br>end<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> then you can mix-in Ruby's <tt>Enumerable</tt> |
| module to easily add a lot of functionality to your class: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>class Set<br> <b>include Enumerable</b><br>def initialize<br>@members = []<br>end<br>def each<br>@members.each { |m| yield m }<br>end<br>end<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> To get the same benefit for your SWIG-wrapped classes, you |
| can use the <tt>%mixin</tt> directive to specify the names |
| of one or more modules that should be mixed-in to a class. For the |
| above example, the SWIG interface specification might look like this: </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%mixin Set "Enumerable";<br><br>class Set {<br>public:<br> // Constructor<br> Set();<br> <br> // Iterates through set members<br> void each();<br>};<br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Multiple modules can be mixed into a class by providing a |
| comma-separated list of module names to the <tt>%mixin</tt> |
| directive, e.g. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%mixin Set "Fee,Fi,Fo,Fum";</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note that the <tt>%mixin</tt> directive is |
| implemented 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> |
| |
| |
| |
| |
| |
| <H2><a name="Ruby_nn57"></a>31.10 Memory Management</H2> |
| |
| |
| <p>One of the most common issues in generating SWIG bindings for |
| Ruby is proper memory management. The key to proper memory management |
| is clearly defining whether a wrapper Ruby object owns the underlying C |
| struct or C++ class. There are two possibilities:</p> |
| |
| |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li> The Ruby object is responsible for freeing the C struct or |
| C++ object </li> |
| |
| |
| |
| |
| |
| <li> The Ruby object should not free the C struct or C++ object |
| because it will be freed by the underlying C or C++ code</li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| |
| |
| <p>To complicate matters, object ownership may transfer from Ruby |
| 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"></a>31.10.1 Mark and Sweep Garbage Collector </H3> |
| |
| |
| <p>Ruby uses a mark and sweep garbage collector. When the garbage |
| collector runs, it finds all the "root" objects, including local |
| variables, global variables, global constants, hardware registers and |
| the C stack. For each root object, the garbage collector sets its mark |
| flag to true and calls <tt>rb_gc_mark</tt> on the object. |
| The job of <tt>rb_gc_mark</tt> is to recursively mark all |
| the objects that a Ruby object has a reference to (ignoring those |
| objects that have already been marked). Those objects, in turn, may |
| reference other objects. This process will continue until all active |
| objects have been "marked." After the mark phase comes the sweep phase. |
| In the sweep phase, all objects that have not been marked will be |
| garbage collected. For more information about the Ruby garbage |
| collector please refer to <a href="http://rubygarden.org/ruby/ruby?GCAndExtensions"> <span style="text-decoration: underline;">http://rubygarden.org/ruby/ruby?GCAndExtensions</span></a>.</p> |
| |
| |
| |
| |
| |
| <p>The Ruby C/API provides extension developers two hooks into |
| the garbage collector - a "mark" function and a "sweep" function. By |
| default these functions are set to NULL.</p> |
| |
| |
| |
| |
| |
| <p>If a C struct or C++ class references any other Ruby objects, |
| then it must provide a "mark" function. The "mark" function should |
| identify any referenced Ruby objects by calling the rb_gc_mark function |
| for each one. Unsurprisingly, this function will be called by the Ruby |
| garbage during the "mark" phase.</p> |
| |
| |
| |
| |
| |
| <p>During the sweep phase, Ruby destroys any unused objects. If |
| 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"></a>31.10.2 Object Ownership</H3> |
| |
| |
| <p>As described above, memory management depends on clearly |
| defining who is responsible for freeing the underlying C struct or C++ |
| class. If the Ruby object is responsible for freeing the C++ object, |
| then a "free" function must be registered for the object. If the Ruby |
| object is not responsible for freeing the underlying memory, then a |
| "free" function must not be registered for the object.</p> |
| |
| |
| |
| |
| |
| <p>For the most part, SWIG takes care of memory management |
| issues. The rules it uses are:</p> |
| |
| |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| <li> When calling a C++ object's constructor from Ruby, SWIG |
| will assign a "free" function thereby making the Ruby object |
| responsible for freeing the C++ object</li> |
| |
| |
| |
| |
| |
| <li> When calling a C++ member function that returns a pointer, |
| SWIG will not assign a "free" function thereby making the underlying |
| library responsible for freeing the object.</li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| |
| |
| <p>To make this clearer, let's look at an example. Assume we have |
| a Foo and a Bar class. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>/* File "RubyOwernshipExample.h" */<br><br>class Foo<br>{<br>public:<br> Foo() {}<br> ~Foo() {}<br>};<br><br>class Bar<br>{<br> Foo *foo_;<br>public:<br> Bar(): foo_(new Foo) {}<br> ~Bar() { delete foo_; }<br> Foo* get_foo() { return foo_; }<br> Foo* get_new_foo() { return new Foo; }<br> void set_foo(Foo *foo) { delete foo_; foo_ = foo; }<br>};<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>First, consider this Ruby code: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>foo = Foo.new</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In this case, the Ruby code calls the underlying <tt>Foo</tt> |
| C++ constructor, thus creating a new <tt>foo</tt> object. |
| By default, SWIG will assign the new Ruby object a "free" function. |
| When the Ruby object is garbage collected, the "free" function will be |
| called. It in turn will call <tt>Foo's</tt> destructor.</p> |
| |
| |
| |
| |
| |
| <p>Next, consider this code: </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>bar = Bar.new<br>foo = bar.get_foo()</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In this case, the Ruby code calls a C++ member function, <tt>get_foo</tt>. |
| By default, SWIG will not assign the Ruby object a "free" function. |
| Thus, when the Ruby object is garbage collected the underlying C++ <tt>foo</tt> |
| object is not affected.</p> |
| |
| |
| |
| |
| |
| <p>Unfortunately, the real world is not as simple as the examples |
| above. For example:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>bar = Bar.new<br>foo = bar.get_new_foo()</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>In this case, the default SWIG behavior for calling member |
| functions is incorrect. The Ruby object should assume ownership of the |
| returned object. This can be done by using the %newobject directive. |
| See <a href="file:///d:/msys/1.0/src/SWIG/Doc/Manual/Customization.html#ownership"> |
| Object ownership and %newobject</a> for more information. </p> |
| |
| |
| |
| |
| |
| <p>The SWIG default mappings are also incorrect in this case:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>foo = Foo.new<br>bar = Bar.new<br>bar.set_foo(foo)</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Without modification, this code will cause a segmentation |
| fault. When the Ruby <tt>foo</tt> object goes out of |
| scope, it will free the underlying C++ <tt>foo</tt> |
| object. However, when the Ruby bar object goes out of scope, it will |
| call the C++ bar destructor which will also free the C++ <tt>foo</tt> |
| object. The problem is that object ownership is transferred from the |
| Ruby object to the C++ object when the <tt>set_foo</tt> |
| method is called. This can be done by using the special DISOWN type |
| map, which was added to the Ruby bindings in SWIG-1.3.26.</p> |
| |
| |
| |
| |
| |
| <p>Thus, a correct SWIG interface file correct mapping for these |
| classes is:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>/* File RubyOwnershipExample.i */<br><br>%module RubyOwnershipExample<br><br>%{<br>#include "RubyOwnershipExample.h"<br>%}<br><br>class Foo<br>{<br>public:<br> Foo();<br> ~Foo();<br>};<br><br>class Bar<br>{<br> Foo *foo_;<br>public:<br> Bar();<br> ~Bar();<br> Foo* get_foo();<br><br><span style="font-weight: bold;"> %newobject get_new_foo;</span><br> Foo* get_new_foo();<br><br><span style="font-weight: bold;"> %apply SWIGTYPE *DISOWN {Foo *foo};</span><br> void set_foo(Foo *foo);<br><span style="font-weight: bold;"> %clear Foo *foo;</span><br>};<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <p> This code can be seen in swig/examples/ruby/tracking.</p> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn60"></a>31.10.3 Object Tracking</H3> |
| |
| |
| <p>The remaining parts of this section will use the class library |
| shown below to illustrate different memory management techniques. The |
| class library models a zoo and the animals it contains. </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module zoo<br><br>%{<br>#include <string><br>#include <vector><br><br>#include "zoo.h"<br>%}<br><br>class Animal<br>{<br>private:<br> typedef std::vector<Animal*> AnimalsType;<br> typedef AnimalsType::iterator IterType;<br>protected:<br> AnimalsType animals;<br>protected:<br> std::string name_;<br>public:<br> // Construct an animal with this name<br> Animal(const char* name) : name_(name) {}<br> <br> // Return the animal's name<br> const char* get_name() const { return name.c_str(); }<br>};<br><br>class Zoo<br>{<br>protected:<br> std::vector<animal *=""> animals;<br> <br>public:<br> // Construct an empty zoo<br> Zoo() {}<br> <br> /* Create a new animal. */<br> static Animal* Zoo::create_animal(const char* name)<br> {<br> return new Animal(name);<br> }<br><br> // Add a new animal to the zoo<br> void add_animal(Animal* animal) {<br> animals.push_back(animal); <br> }<br><br> Animal* remove_animal(size_t i) {<br> Animal* result = this->animals[i];<br> IterType iter = this->animals.begin();<br> std::advance(iter, i);<br> this->animals.erase(iter);<br><br> return result;<br> }<br> <br> // Return the number of animals in the zoo<br> size_t get_num_animals() const {<br> return animals.size(); <br> }<br> <br> // Return a pointer to the ith animal<br> Animal* get_animal(size_t i) const {<br> return animals[i]; <br> }<br>};<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Let's say you SWIG this code and then run IRB:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <span style="font-weight: bold;">irb</span><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be3820><br><br>irb(main):004:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>=> "tiger1"<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0a60><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo.get_num_animals()</span><br>=> 1<br><br>irb(main):007:0> <span style="font-weight: bold;">tiger2 = zoo.remove_animal(0)</span><br>=> #<Example::Animal:0x2bd4a18><br><br>irb(main):008:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>=> "tiger1"<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.equal?(tiger2)</span><br>=> false<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Pay particular attention to the code <tt>tiger1.equal?(tiger2)</tt>. |
| Note that the two Ruby objects are not the same - but they reference |
| the same underlying C++ object. This can cause problems. For example:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>irb(main):010:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):011:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):012:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>(irb):12: [BUG] Segmentation fault<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>After the the garbage collector runs, as a result of our call |
| to <tt>GC.start</tt>, calling<tt>tiger2.get_name()</tt> |
| causes a segmentation fault. The problem is that when <tt>tiger1</tt> |
| is garbage collected, it frees the underlying C++ object. Thus, when <tt>tiger2</tt> |
| calls the <tt>get_name()</tt> method it invokes it on a |
| destroyed object.</p> |
| |
| |
| |
| |
| |
| <p>This problem can be avoided if SWIG enforces a one-to-one |
| mapping between Ruby objects and C++ classes. This can be done via the |
| use of the <tt>%trackobjects</tt> functionality available |
| in SWIG-1.3.26. and later.</p> |
| |
| |
| |
| |
| |
| <p>When the <tt>%trackobjects</tt> is turned on, |
| SWIG automatically keeps track of mappings between C++ objects and Ruby |
| objects. Note that enabling object tracking causes a slight performance |
| degradation. Test results show this degradation to be about 3% to 5% |
| when creating and destroying 100,000 animals in a row.</p> |
| |
| |
| |
| |
| |
| <p>Since <tt>%trackobjects</tt> is implemented as a <tt>%feature</tt>, |
| it uses the same name matching rules as other kinds of features (see |
| the chapter on <a href="Customization.html#Customization"> |
| "Customization Features"</a>) . Thus it can be applied on a |
| class-by-class basis if needed. To fix the example above:</p> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br><span style="font-weight: bold;">/* Tell SWIG that create_animal creates a new object */</span><br><span style="font-weight: bold;">%newobject Zoo::create_animal;</span><br><br><span style="font-weight: bold;">/* Tell SWIG to keep track of mappings between C/C++ structs/classes. */</span><br style="font-weight: bold;"><span style="font-weight: bold;">%trackobjects;</span><br><br>%include "example.h"</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>When this code runs we see:<br> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre>$ <span style="font-weight: bold;">irb</span><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0a18><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):006:0> <span style="font-weight: bold;">tiger2 = zoo.remove_animal(0)</span><br>=> #<Example::Animal:0x2be37d8><br><br>irb(main):007:0> <span style="font-weight: bold;">tiger1.equal?(tiger2)</span><br>=> true<br><br>irb(main):008:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):010:0> <span style="font-weight: bold;">tiger.get_name()</span><br>=> "tiger1"<br>irb(main):011:0><br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>For those who are interested, object tracking is implemented |
| by storing Ruby objects in a hash table and keying them on C++ |
| pointers. The underlying API is:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>static void SWIG_RubyAddTracking(void* ptr, VALUE object);<br>static VALUE SWIG_RubyInstanceFor(void* ptr) ;<br>static void SWIG_RubyRemoveTracking(void* ptr);<br>static void SWIG_RubyUnlinkObjects(void* ptr);</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>When an object is created, SWIG will automatically call the <tt>SWIG_RubyAddTracking</tt> |
| method. Similarly, when an object is deleted, SWIG will call the <tt>SWIG_RubyRemoveTracking</tt>. |
| When an object is returned to Ruby from C++, SWIG will use the <tt>SWIG_RubyInstanceFor</tt> |
| method to ensure a one-to-one mapping from Ruby to C++ objects. Last, |
| the <tt>RubyUnlinkObjects</tt> method unlinks a Ruby |
| object from its underlying C++ object.</p> |
| |
| |
| |
| |
| |
| <p>In general, you will only need to use the <tt>SWIG_RubyInstanceFor</tt>, |
| which is required for implementing mark functions as shown below. |
| 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"></a>31.10.4 Mark Functions</H3> |
| |
| |
| <p>With a bit more testing, we see that our class library still |
| has problems. For example:<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>$ <b>irb</b><br>irb(main):001:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):002:0> tiger1 = <span style="font-weight: bold;">Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bea6a8><br><br>irb(main):003:0> zoo = <span style="font-weight: bold;">Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be7960><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):005:0> <span style="font-weight: bold;">tiger2 = zoo.get_animal(0)</span><br>(irb):12: [BUG] Segmentation fault</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>The problem is that Ruby does not know that the <tt>zoo</tt> |
| object contains a reference to a Ruby object. Thus, when Ruby garbage |
| collects <span style="font-family: monospace;">tiger1</span> |
| it frees the underlying C++ object.</p> |
| |
| |
| |
| |
| |
| <p>This can be fixed by implementing a <tt>mark</tt> |
| function as described above in the <a href="Ruby.html#Ruby_nn52">Mark |
| and Sweep Garbage Collector</a> section. You can specify a mark |
| function by using the <tt>%markfunc</tt> directive. Since |
| the <tt>%markfunc</tt> directive is implemented using |
| SWIG's' "features" mechanism it uses the same name matching rules as |
| other kinds of features (see the chapter on <a href="Customization.html#Customization">"Customization |
| Features"</a> for more details). </p> |
| |
| |
| |
| |
| |
| <p>A <tt>mark</tt> function takes a single argument, |
| which is a pointer to the C++ object being marked; it should, in turn, |
| call <tt>rb_gc_mark()</tt> for any instances that are |
| reachable from the current object. The mark function for our <tt> |
| Zoo</tt> class should therefore loop over all of the C++ animal |
| objects in the zoo object, look up their Ruby object equivalent, and |
| then call <tt>rb_gc_mark()</tt>. One possible |
| implementation is:</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>/* Keep track of mappings between C/C++ structs/classes<br> and Ruby objects so we can implement a mark function. */<br><span style="font-weight: bold;">%trackobjects;</span><br><br>/* Specify the mark function */<br><span style="font-weight: bold;">%markfunc Zoo "mark_Zoo";</span><br><br>%include "example.h"<br><br>%header %{<br><br>static void mark_Zoo(void* ptr) {<br> Zoo* zoo = (Zoo*) ptr;<br><br> /* Loop over each object and tell the garbage collector<br> that we are holding a reference to them. */<br> int count = zoo->get_num_animals();<br><br> for(int i = 0; i < count; ++i) {<br> Animal* animal = zoo->get_animal(i);<br> VALUE object = SWIG_RubyInstanceFor(animal);<br><br> if (object != Qnil) {<br> rb_gc_mark(object);<br> }<br> }<br>}<br>%}<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p> Note the <tt>mark</tt> function is dependent on |
| the <tt>SWIG_RUBY_InstanceFor</tt> method, and thus |
| requires that <tt>%trackobjects</tt> is enabled. For more |
| information, please refer to the track_object.i test case in the SWIG |
| test suite.</p> |
| |
| |
| |
| |
| |
| <p>When this code is compiled we now see:</p> |
| |
| |
| |
| |
| |
| <div class="targetlang"> |
| <pre>$ <b>irb<br></b>irb(main):002:0> <span style="font-weight: bold;">tiger1=Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):003:0> <span style="font-weight: bold;">Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be1780><br><br>irb(main):004:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2bde9c0><br><br>irb(main):005:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1 = nil</span><br>=> nil<br><br>irb(main):010:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br>irb(main):014:0> <span style="font-weight: bold;">tiger2 = zoo.get_animal(0)</span><br>=> #<Example::Animal:0x2be3bf8><br><br>irb(main):015:0> <span style="font-weight: bold;">tiger2.get_name()</span><br>=> "tiger1"<br>irb(main):016:0><br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <br> |
| |
| |
| |
| |
| |
| <p>This code can be seen in swig/examples/ruby/mark_function.</p> |
| |
| |
| |
| |
| |
| <H3><a name="Ruby_nn62"></a>31.10.5 Free Functions</H3> |
| |
| |
| <p>By default, SWIG creates a "free" function that is called when |
| a Ruby object is garbage collected. The free function simply calls the |
| C++ object's destructor.</p> |
| |
| |
| |
| |
| |
| <p>However, sometimes an appropriate destructor does not exist or |
| special processing needs to be performed before the destructor is |
| called. Therefore, SWIG allows you to manually specify a "free" |
| function via the use of the <tt>%freefunc</tt> directive. |
| The <tt>%freefunc</tt> directive is implemented 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> |
| |
| |
| |
| |
| |
| <p>IMPORTANT ! - If you define your own free function, then you |
| must ensure that you call the underlying C++ object's destructor. In |
| addition, if object tracking is activated for the object's class, you |
| must also call the <tt>SWIG_RubyRemoveTracking</tt> |
| function (of course call this before you destroy the C++ object). Note |
| that it is harmless to call this method if object tracking if off so it |
| is advised to always call it.</p> |
| |
| |
| |
| |
| |
| <p>Note there is a subtle interaction between object ownership |
| and free functions. A custom defined free function will only be called |
| if the Ruby object owns the underlying C++ object. This also to Ruby |
| objects which are created, but then transfer ownership to C++ objects |
| via the use of the <tt>disown</tt> typemap described |
| above. </p> |
| |
| |
| |
| |
| |
| <p>To show how to use the <tt>%freefunc</tt> |
| directive, let's slightly change our example. Assume that the zoo |
| object is responsible for freeing animal that it contains. This means |
| that the <span style="font-family: monospace;">Zoo::add_animal</span> |
| function should be marked with a <span style="font-family: monospace;">DISOWN</span> typemap |
| and the destructor should be updated as below::</p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>Zoo::~Zoo() {<br> IterType iter = this->animals.begin();<br> IterType end = this->animals.end();<br><br> for(iter; iter != end; ++iter) {<br> Animal* animal = *iter;<br> delete animal;<br> }<br>}</pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>When we use these objects in IRB we see:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre class="targetlang"><span style="font-weight: bold;">$irb</span><br>irb(main):002:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0fe8><br><br>irb(main):005:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bda760><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo = nil</span><br>=> nil<br><br>irb(main):008:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>(irb):12: [BUG] Segmentation fault<br><br></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>The error happens because the C++ <tt>animal</tt> |
| object is freed when the <tt>zoo</tt> object is freed. |
| Although this error is unavoidable, we can at least prevent the |
| segmentation fault. To do this requires enabling object tracking and |
| implementing a custom free function that calls the <tt>SWIG_RubyUnlinkObjects</tt> |
| function for each animal object that is destroyed. The <tt>SWIG_RubyUnlinkObjects</tt> |
| function notifies SWIG that a Ruby object's underlying C++ object is no |
| longer valid. Once notified, SWIG will intercept any calls from the |
| existing Ruby object to the destroyed C++ object and raise an exception.<br> |
| |
| |
| |
| |
| |
| </p> |
| |
| |
| |
| |
| |
| <div class="code"> |
| <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>/* Specify that ownership is transferred to the zoo<br> when calling add_animal */<br>%apply SWIGTYPE *DISOWN { Animal* animal };<br><br>/* Track objects */<br>%trackobjects;<br><br>/* Specify the mark function */<br>%freefunc Zoo "free_Zoo";<br><br>%include "example.h"<br><br>%header %{<br> static void free_Zoo(void* ptr) {<br> Zoo* zoo = (Zoo*) ptr;<br><br> /* Loop over each animal */<br> int count = zoo->get_num_animals();<br><br> for(int i = 0; i < count; ++i) {<br> /* Get an animal */<br> Animal* animal = zoo->get_animal(i);<br><br> /* Unlink the Ruby object from the C++ object */<br> SWIG_RubyUnlinkObjects(animal);<br><br> /* Now remove the tracking for this animal */<br> SWIG_RubyRemoveTracking(animal);<br> }<br><br> /* Now call SWIG_RemoveMapping for the zoo */<br> SWIG_RemoveMapping(ptr);<br> <br> /* Now free the zoo which will free the animals it contains */<br> delete zoo;<br> }<br>%} </pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Now when we use these objects in IRB we see:</p> |
| |
| |
| |
| |
| |
| <div class="code targetlang"> |
| <pre><span style="font-weight: bold;">$irb</span><br>irb(main):002:0> <span style="font-weight: bold;">require 'example'</span><br>=> true<br><br>irb(main):003:0> <span style="font-weight: bold;">zoo = Example::Zoo.new()</span><br>=> #<Example::Zoo:0x2be0fe8><br><br>irb(main):005:0> <span style="font-weight: bold;">tiger1 = Example::Animal.new("tiger1")</span><br>=> #<Example::Animal:0x2bda760><br><br>irb(main):006:0> <span style="font-weight: bold;">zoo.add_animal(tiger1)</span><br>=> nil<br><br>irb(main):007:0> <span style="font-weight: bold;">zoo = nil</span><br>=> nil<br><br>irb(main):008:0> <span style="font-weight: bold;">GC.start</span><br>=> nil<br><br>irb(main):009:0> <span style="font-weight: bold;">tiger1.get_name()</span><br>RuntimeError: This Animal * already released<br> from (irb):10:in `get_name'<br> from (irb):10<br>irb(main):011:0></pre> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| |
| |
| |
| <p>Notice that SWIG can now detect the underlying C++ object has |
| 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"></a>31.10.6 Embedded Ruby and the C++ Stack</H3> |
| |
| |
| <p>As has been said, the Ruby GC runs and marks objects before |
| its |
| sweep phase. When the garbage collector is called, it will |
| also |
| try to mark any Ruby objects (VALUE) it finds in the machine registers |
| and in the C++ stack.</p> |
| |
| |
| |
| |
| |
| <p>The stack is basically the history of the functions that have |
| been |
| called and also contains local variables, such as the ones you define |
| whenever you do inside a function:</p> |
| |
| |
| |
| |
| |
| <div class="diagram">VALUE obj; </div> |
| |
| |
| |
| |
| |
| <p>For ruby to determine where its stack space begins, during |
| initialization a normal Ruby interpreter will call the ruby_init() |
| function which in turn will call a function called Init_stack or |
| similar. This function will store a pointer to the location |
| where |
| the stack points at at that point in time.</p> |
| |
| |
| |
| |
| |
| <p>ruby_init() is presumed to always be called within the main() |
| function of your program and whenever the GC is called, ruby will |
| assume that the memory between the current location in memory and the |
| pointer that was stored previously represents the stack, which may |
| contain local (and temporary) VALUE ruby objects. Ruby will |
| then be careful not to remove any of those objects in that location.</p> |
| |
| |
| |
| |
| |
| <p>So far so good. For a normal Ruby session, all the |
| above is |
| completely transparent and magic to the extensions developer. |
| </p> |
| |
| |
| |
| |
| |
| <p>However, with an embedded Ruby, it may not always be possible |
| to |
| modify main() to make sure ruby_init() is called there. As |
| such, |
| ruby_init() will likely end up being called from within some other |
| function. This can lead Ruby to measure incorrectly where the |
| stack begins and can result in Ruby incorrectly collecting |
| those |
| temporary VALUE objects that are created once another function |
| is |
| called. The end result: random crashes and segmentation |
| faults.</p> |
| |
| |
| |
| |
| |
| <p>This problem will often be seen in director functions that are |
| used for callbacks, for example. </p> |
| |
| |
| |
| |
| |
| <p>To solve the problem, SWIG can now generate code with director |
| functions containing the optional macros SWIG_INIT_STACK and |
| SWIG_RELEASE_STACK. These macros will try to force Ruby to |
| reinitiliaze the beginning of the stack the first time a |
| director |
| function is called. This will lead Ruby to measure and not |
| collect any VALUE objects defined from that point on. </p> |
| |
| |
| |
| |
| |
| <p>To mark functions to either reset the ruby stack or not, you |
| can use:</p> |
| |
| |
| |
| |
| |
| <div class="indent code" style="font-family: monospace;">%initstack |
| Class::memberfunction; // only re-init the stack |
| in this director method<br> |
| |
| |
| |
| |
| |
| %ignorestack Class::memberfunction; // do not re-init the |
| stack in this director method<br> |
| |
| |
| |
| |
| |
| %initstack Class; |
| // init the stack on all |
| the methods of this class<br> |
| |
| |
| |
| |
| |
| %initstack; // all director functions will |
| re-init the stack</div> |
| |
| |
| </body> |
| </html> |